Skip to content
San Andreas Online Docs

setPedNavigateTo

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

Give an NPC a destination and GTA's pedestrian pathfinder takes over: it chooses a route through the native path network, goes around buildings, walks or runs naturally, slows down, and stops near the target.

Complete example

-- client.lua
-- GTA chooses the pedestrian route; Lua only gives the destination.
local sweet = createPed(270, 2495.2, -1687.4, 13.5)
local destination = Vector3(2520.0, -1672.0, 13.8)


if sweet then
    assert(setPedNavigateTo(sweet, destination, "run"))
end

Syntax

bool setPedNavigateTo(ped thePed, Vector3 target [, string movement = "walk", float radius = 0.5, float slowdownRadius = 3.0, float heightChangeThreshold = 2.0, bool keepNodesHeadingAwayFromTarget = false, int timeout = -1, bool useBlending = true])

GTA task mapping

ORIGINAL GTA TASK
CTaskComplexFollowNodeRoute

GTA builds and follows its pedestrian node route. San Andreas Online also preserves the task's native recovery when the ped meets a building collision. The audited source identifies task type 906; no numeric SCM opcode is claimed.

Arguments

thePedped

Living streamed ped simulated by this client.

targetVector3

Finite world destination.

movementstringoptional · default walk

walk, run, or sprint.

radiusfloatoptional · default 0.5

Positive arrival radius.

slowdownRadiusfloatoptional · default 3.0

Slowdown radius not smaller than radius.

heightChangeThresholdfloatoptional · default 2.0

Positive vertical-change threshold used while GTA builds the route.

keepNodesHeadingAwayFromTargetbooloptional · default false

Keep route nodes that initially head away from the target when GTA needs them.

timeoutintoptional · default -1

-1 for no timeout, or a non-negative timeout in milliseconds.

useBlendingbooloptional · default true

Blend the native movement transitions.

Returns

true when GTA accepted the route task; false when the ped, ownership, streaming, liveness, destination, movement, radii, height threshold, or timeout is invalid.

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
  • true means the task was accepted, not that the NPC has arrived. There is no completion event or durable route handle.

OOP aliases

  • ped:setNavigateTo(target, movement, radius, slowdownRadius, heightChangeThreshold, keepNodesHeadingAwayFromTarget, timeout, useBlending)

Where this comes from

SOURCECLuaPedDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaPedDefs.cpp INTRODUCED / EXTENDED7b4795ee3Read the commit and why the change was made TEST RESOURCE native-ped-navigate-harness test-resources/native-ped-navigate-harness
RELATED SA:O APIS

Continue exploring

Read the system guide →
setPedGoTo Send an NPC straight toward a nearby coordinate. GTA handles the walk or run, slows the NPC down, and stops it inside the arrival radius. setPedChatWith Pair two NPCs and GTA makes them face each other and perform its original conversation behavior, with one character leading and the other replying. setPedStandStill Queues GTA's simple stand-still task on a simulated ped.

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