getAmbientVehicleSpawnCandidate

Client-side

Ask GTA to choose a valid road lane, position, direction, speed, and driving style for a vehicle near the player—without creating the vehicle.

Syntax

table|false, string? getAmbientVehicleSpawnCandidate(Vector3 origin, int modelId)

Arguments

originVector3

Position around which GTA should look for a road.

modelIdint

Supported civilian road-vehicle model ID.

Returns

A table with model, x, y, z, rotation, cruiseSpeed, vehicleClass, and drivingStyle; or false plus a reason when GTA cannot find a valid road placement.

Ownership and lifecycle

Candidate queries create nothing. A multiplayer resource must validate each proposal, create and own the real NPCs and vehicles, assign one current syncer, handle ownership changes, and clean up every element. Native AI and event tokens belong to the calling resource and are revoked when that resource stops.

Important behavior

The function only proposes a spawn. The server still creates and owns the real vehicle.
The result uses GTA's road network and lane placement, including a ground check.

Example

local model = getAmbientVehicleModelCandidate()
if model then
    local spawn = getAmbientVehicleSpawnCandidate(localPlayer.position, model.model)
    if spawn then
        outputDebugString(("vehicle %d at %.1f, %.1f"):format(spawn.model, spawn.x, spawn.y))
    end
end

Where this comes from

SOURCECLuaWorldDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaWorldDefs.cpp INTRODUCED / EXTENDEDb23f57d74Read the commit and why the change was made TEST RESOURCE native-vehicle-traffic test-resources/native-vehicle-traffic

RELATED SA:O APIS

Continue exploring

Read the system guide →

← Back to the SA:O Lua API · How Synchronized NPCs and road traffic works →