Skip to content
San Andreas Online Docs

getAmbientPedCivilianCoupleCandidate

Client-side
SA:O APISynchronized NPCs and road traffic

Ask GTA for two compatible civilian skins and nearby path positions that can spawn together as a walking couple.

Syntax

table|false, string? getAmbientPedCivilianCoupleCandidate(Vector3 origin)

Arguments

originVector3

Finite world position around which GTA should look for the couple.

Returns

A couple table with two member records containing model, ped type, position, direction, path interpolation, heading, and civilian metadata; 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 only proposes a pair and creates nothing. The server must validate the result, create both peds together, and assign one simulation owner.

Example

local couple, reason = getAmbientPedCivilianCoupleCandidate(localPlayer.position)
if couple then
    for _, member in ipairs(couple.members) do
        outputDebugString(("model %d at %.1f, %.1f, %.1f"):format(member.model, member.x, member.y, member.z))
    end
end

Where this comes from

SOURCECLuaWorldDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaWorldDefs.cpp INTRODUCED / EXTENDED6cb144d8aRead 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 →
updateAmbientPedPopulationModels Runs GTA's ped-only zone-model residency pass around an origin without enabling unmanaged population creation. resetAmbientPedPopulationModels Releases the stock population-model residency established by the ambient-ped update pass. addPedNativeGunAimedAtEvent Inserts GTA's real aimed-at event on the authoritative ambient-ped owner.

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