Skip to content
San Andreas Online Docs

acquirePedNativeEventProfile

Client-side
SA:O APINative ped tasks and gang tags

Exclusively leases one of San Andreas Online's stock native-event adapters for a script ped.

Syntax

int|false acquirePedNativeEventProfile(ped thePed, string profile)

GTA task mapping

NATIVE GTA BEHAVIOR
No CTask is created

Acquisition does not create a CTask. GTA's decision maker constructs a response only after the active profile accepts a native event; there is no direct SCM opcode for the lease.

Arguments

thePedped

Script ped; players are rejected. The mission profile requires setPedMissionActor, while ambient-wander rejects mission actors.

profilestring

mission, ambient-wander, or ambient-cop-safe.

Returns

A non-zero resource-private token, or false when the ped, profile prerequisite, profile name, or exclusive ownership check fails.

Ownership and lifecycle

Low-level ped task calls require the client that simulates the living, streamed ped. Driving tasks also require control of the streamed vehicle. They do not create lifecycle handles; the optional native-task-runtime adds server-owned route epochs and reconstruction for drive_to routes. Gang-tag ownership is resource-exclusive, survives object streaming and recreation, and is released automatically when the owner stops.

Important behavior
  • The logical lease may be acquired before stream-in or sync ownership and survives native recreation and syncer generations.
  • It becomes active only while this client is the authoritative ped syncer with a live native instance. Another resource cannot lease the same ped on this client.
  • mission restores the audited mission decision path for events such as an occupied vehicle catching fire. ambient-wander admits stock pedestrian and parked-vehicle avoidance plus civilian gun-threat and damage decisions.
  • ambient-cop-safe marks the ped as a city cop for locomotion purposes: setPedWander then builds San Andreas Online's safe ambient-cop wander task and rejects wanderSensibly = false. It grants no wanted, pursuit, or arrest behavior, which is unreachable by construction rather than suppressed at runtime.
  • No profile serializes the active response task across migration or loads custom SCM decision-maker files.

Example

assert(setPedMissionActor(ballas, true))
local token = assert(acquirePedNativeEventProfile(ballas, "mission"))

Where this comes from

SOURCECLuaPedDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaPedDefs.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 →
setPedMissionActor Persists GTA's PED_MISSION classification on a script-created ped across native model recreation. isPedMissionActor Reports the locally persisted mission-actor policy, including while the native model is streamed out. releasePedNativeEventProfile Releases one native ped event-profile token owned by the calling resource.

← Back to the SA:O Lua API · How Native ped tasks and gang tags works →