Documentation/NEXM Vehicles
NEXM VEHICLES / PRODUCT DOCUMENTATION

NEXM Vehicles

Installation, configuration, persistent lifecycle, locks, shared keys, tracker gameplay and public integration APIs for NEXM Vehicles.

v1.0.1PaidAsset EscrowNEXM Core required
Verified documentationBuilt from the supplied NEXM Vehicles v1.0.1 escrow-ready release package, README, public config.lua and integration documentation.
NEXM VEHICLES

Overview

v1.0.1

NEXM Vehicles is a server-authoritative persistent vehicle lifecycle system for FiveM. It keeps vehicle identity, lifecycle, streaming, persistence, locking, shared access and owner GPS tracking under one authoritative vehicle record while remaining framework-agnostic through NEXM Core.

Stable release1.0.1
Core dependency≥ 1.0.0-rc.1.hotfix.11
Vehicle identityImmutable vehicle_uuid
ProtectionCfx.re Asset Escrow
Authority rule

Persistent vehicle record != GTA entity. GTA entities may stream in/out and be recreated while retaining the same immutable vehicle UUID.

GETTING STARTED

Requirements

NEXM CoreRequired version >=1.0.0-rc.1.hotfix.11.
OneSyncRequired for persistent WORLD spawning, streaming and server-side entity authority.
DatabaseDatabase access and migrations are handled through NEXM Core; NEXM Vehicles does not use direct oxmysql calls.
LB PhoneOptional. Only required when the bundled My Vehicles phone app is enabled.
GETTING STARTED

Installation

Place the delivered folder in your server resources directory with the exact resource name nexm_vehicles. Do not rename it.

SERVER.CFGcfg
ensure nexm_core
ensure nexm_vehicles

When LB Phone support is enabled, start it first:

SERVER.CFG + LB PHONEcfg
ensure lb-phone
ensure nexm_core
ensure nexm_vehicles

Database migrations

The release ships frozen migrations 000_foundation through 004_vehicle_shared_keys. They register through NEXM Core. Do not edit an already-applied migration.

Tracker item

The V1 tracker item is vehicle_tracker. Use the matching example under install/ for ox_inventory, Qbox + ox_inventory, QBCore/qb-inventory or ESX, and copy the supplied vehicle_tracker.png into the correct inventory image directory.

Important

The usable-item behavior is registered by nexm_vehicles through NEXM Core. Do not add a second framework-specific usable-item handler.

GETTING STARTED

Configuration

Public customer configuration lives in config.lua.

Config.SpawningServer-side creation mode and optional model-type overrides.
Config.StreamingSpawn/despawn radius, scan interval and spatial cell size.
Config.PersistenceCapture/flush cadence and dirty-state persistence behavior.
Config.FuelSystemauto, native, ox_fuel, custom or none.
Config.LockingBuilt-in lock control, U keybind, distance, feedback and key-fob animation.
Config.SharedKeysGive/revoke commands, proximity policy and rate limits.
Config.Tracker.GameplayTracker item, range, durations, animation and item return behavior.
Config.GarageIntegrationOwner auto-exit and server settle timing for authoritative store flow.
Config.VehicleUIStandalone /vehicles interface and optional keybind.
Config.PhoneOptional bundled LB Phone app registration.
VEHICLE SYSTEM

Identity & Lifecycle

vehicle_uuid is immutable and authoritative. Plates are display/compatibility data and should not be used as the primary persistent identity.

LifecycleMeaning
WORLDPersistent vehicle exists in the world lifecycle and may be streamed in/out.
GARAGEDStored in a garage context.
IMPOUNDEDHeld in impound context.
SEIZEDHeld in seizure context.
DESTROYEDVehicle marked destroyed by authoritative damage policy.
DELETEDVehicle removed from the active lifecycle.

Legacy plate helpers exist for older integrations, but new integrations should persist the returned vehicle UUID.

VEHICLE SYSTEM

Persistence & Streaming

Persistent WORLD vehicles use server-side spawning, proximity-based spatial streaming, duplicate protection and restart recovery. The authoritative record persists transform, properties, fuel and the V1 damage baseline.

Driving stability

The stable V1 recovery lineage keeps confirmed periodic health checks read-only for already-authoritative live vehicles, preventing stored rotation/heading from being reapplied while driving.

SQL is persistence, not a realtime world lookup. Runtime state is cache-first and dirty/versioned, with writes coalesced by the configured flush cadence.

VEHICLE SYSTEM

My Vehicles UI

The standalone player interface opens with:

CLIENT COMMANDtext
/vehicles

The interface shows owned vehicles and valid SHARED-key vehicles with filters for world/stored/key access. Owner cards expose key management and tracker actions. SHARED-key cards intentionally hide owner-only GPS and key-management actions.

The same frontend is reused by the optional LB Phone integration.

VEHICLE SYSTEM

Locking

NEXM is the persistent lock-state authority. By default, U toggles the nearest accessible NEXM vehicle lock after server-side access and distance validation.

CONFIGLua
Config.Locking.Enabled = true
Config.Locking.DefaultControlEnabled = true
Config.Locking.Keybind = 'U'

1.0.1 key-fob animation

After a successful authoritative lock/unlock action, the built-in control can play the cosmetic key-fob animation anim@mp_player_intmenu@key_fob@ / fob_click. The animation never grants access or changes persistent state by itself.

External key resources

Disable only the built-in control when needed and call NEXM locking APIs. Do not maintain a second persistent lock state for the same vehicle.

VEHICLE SYSTEM

Shared Keys

SHARED keys grant vehicle access without transferring ownership. The canonical owner remains unchanged.

FALLBACK COMMANDStext
/givekeys [playerId]
/revokekeys [playerId]

The owner, target player and vehicle must satisfy configured proximity checks when giving access. Existing grants can also be revoked from the My Vehicles UI, including persisted holders who are currently offline.

A SHARED holder may access and lock/unlock the vehicle, but cannot sell/delete it, transfer ownership, manage the owner's tracker, or view the owner's tracker location.

VEHICLE SYSTEM

Owner Tracker

V1 deliberately supports trackers on owned vehicles only. Covert tracking of another player's vehicle is outside V1 scope.

vehicle_trackerConfigured inventory item used for owner install gameplay.
InstallOwner must be physically beside the live WORLD vehicle; item is consumed only after authoritative commit succeeds.
RemoveOwner-only. Returns the tracker item by default.
LocateWORLD returns live/last-known location; stored/impounded/seized states return context instead of raw waypoint coordinates.

SHARED key holders cannot install, remove or locate through the owner's GPS tracker.

INTEGRATION

Garage Integration

Garage resources request lifecycle transitions from NEXM. They should not independently delete/spawn a persistent NEXM vehicle first.

Store a live player vehicle

SERVERLua
local result = exports['nexm_vehicles']:StorePlayerEntityVehicle(source, vehicleEntity, {
    garageId = garage.id,
    garageLabel = garage.label
})

if not result.success then return end
Do not call DeleteEntity first

NEXM needs the live entity for final authoritative capture. When the canonical owner is the only occupant, NEXM can ask them to exit safely before capture/despawn. Another occupant causes VEHICLE_OCCUPIED instead of silently deleting a passenger.

Release from garage

SERVERLua
local result = exports['nexm_vehicles']:ReleasePlayerVehicle(source, vehicleUuid, {
    coords = { x = spawn.x, y = spawn.y, z = spawn.z },
    heading = spawn.w,
    routingBucket = GetPlayerRoutingBucket(source),
    context = { garageId = garage.id, garageLabel = garage.label }
})
INTEGRATION

Dealership Integration

Dealerships should pass the FiveM source; NEXM resolves the canonical NEXM character owner server-side.

CREATE INTO GARAGELua
local created = exports['nexm_vehicles']:CreatePlayerVehicle(source, {
    model = vehicleModel,
    plate = generatedPlate,
    lifecycleState = 'GARAGED',
    properties = vehicleProperties,
    fuel = 100.0,
    garageData = { garageId = 'legion', garageLabel = 'Legion Square Garage' }
})

local vehicleUuid = created.success and created.data.vehicleUuid

Ownership transfer uses TransferVehicleToPlayer(vehicleUuid, buyerSource). Selling/deleting an owned vehicle uses DeletePlayerVehicle(source, vehicleUuid, reason).

INTEGRATION

Phone Integration

LB Phone support is bundled directly into nexm_vehicles and is disabled by default. No second NEXM phone resource is required.

CONFIGLua
Config.Phone.Enabled = true
Config.Phone.Provider = 'lb-phone'
Config.Phone.Resource = 'lb-phone'

Other phone systems can build their own app using the stable server API: GetPlayerVehicles, GetPlayerVehicle and LocatePlayerVehicle. The phone owns presentation; NEXM remains vehicle/location authority.

INTEGRATION

Public API

GetIntegrationContract()Discover the public integration contract.
CreatePlayerVehicle()Create an authoritative player-owned vehicle record.
StorePlayerEntityVehicle()Recommended live-entity garage store flow.
ReleasePlayerVehicle()Authoritative GARAGED → WORLD release/spawn.
GetPlayerVehicles()Owned + validated shared-key vehicle list.
LocatePlayerVehicle()Owner-authorized tracker location/context.
TogglePlayerVehicleLock()Access-checked authoritative lock toggle.
GiveVehicleKey()Grant SHARED access by immutable UUID.
RevokeVehicleKey()Revoke SHARED access.
InstallTracker()Trusted server integration tracker installation.

Plate-based helpers exist only for compatibility with legacy resources. Prefer UUID APIs for new integrations.

REFERENCE

Asset Escrow

NEXM Vehicles 1.0.1 is prepared for the official Cfx Asset Escrow pipeline.

Protected runtimeserver/*.lua, client/*.lua, shared/*.lua and migrations/*.lua.
Editable Luaconfig.lua, integrations/*.lua and install/*.lua.
Visible NUIweb/index.html, web/styles.css, web/app.js and web/icon.svg.
DeliveryCfx Portal asset delivered through Tebex FiveM Asset delivery.
REFERENCE

Troubleshooting

Core version rejectedInstall NEXM Core >=1.0.0-rc.1.hotfix.11 and start it before Vehicles.
Tracker item does nothingConfirm the matching inventory item definition is merged, the PNG is installed and no second usable-item handler was added.
Garage duplicates/deletes wrongCall the NEXM store export before any external DeleteEntity; persist vehicleUuid whenever possible.
Lock UI fights another key scriptKeep NEXM as the lock-state authority; disable the built-in control and call NEXM APIs from the external key resource.
LB Phone app missingEnable Config.Phone and ensure lb-phone starts before nexm_vehicles.
Shared holder cannot trackExpected behavior. Tracker install/remove/location are owner-only in V1.
SUPPORT

Need help with NEXM Vehicles?

Use the NEXM support page for installation, inventory setup and integration questions.

Open Support