getAmbientPedSpawnCandidate

Client-side

Ask GTA where it would naturally place an NPC near a position. The result includes the suggested skin, NPC type, position, and facing direction—without creating the NPC.

Syntax

table|false, string? getAmbientPedSpawnCandidate(Vector3 origin [, string selection = "auto", int gangId = -1])

Arguments

originVector3

Finite population origin.

selectionstringoptional · default "auto"

auto, civilian, gang, dealer, or cop.

gangIdintoptional · default -1

Required only for gang selection; supported native gang IDs are 0 through 7.

Returns

A candidate table with model, pedType, position, direction, pathLerp, populationClass, worldLevel, and gang; or false plus a bounded miss reason.

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 creates no ped and grants no authority.
Forced gang, dealer, or cop queries do not silently fall back to civilians.
populationClass reports civilian, gang, dealer, or cop for the returned candidate.

Example

local candidate = getAmbientPedSpawnCandidate(localPlayer.position, "dealer")
if candidate then
    outputDebugString(("dealer model: %d"):format(candidate.model))
end

Where this comes from

SOURCECLuaWorldDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaWorldDefs.cpp INTRODUCED / EXTENDED5318f4360Read the commit and why the change was made TEST RESOURCE native-ped-traffic test-resources/native-ped-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 →