Skip to content

NPCs and scripted behavior

Use new revo.Ped(model, position, rotation) on the server for an NPC visible to nearby players. The model accepts a name or hash. Rotation can be a heading, XYZ Euler angles in radians, or a quaternion. The constructor returns immediately and each client loads the ped when it enters their stream.

Set its dimension, clothing, health and other shared properties on the server. Use ped.destroy() there when the NPC is no longer needed. Custom ped assets describes model registration.

For a preview or another ped visible only on one client, use new revo.LocalPed(model, position, heading) in that client’s script. Set its dimension to the intended world and initialize tasks when ready is true or entityStreamIn fires. Client-created peds are removed when their script stops.

Ped.all and Ped.getById() contain NPCs. Use Player.all and Player.getById() for players. Client Ped.all also includes local peds, while LocalPed.all contains those created by the current resource.

The server stores the instruction. The simulation owner executes it in GTA. Other clients receive the resulting movement through synchronization.

These examples create a worker near the beach and have it walk to a nearby destination. The npc:destination key is owned by this example and contains an { x, y, z } object set by the server.

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
const worker = new revo.Ped('s_m_m_dockwork_01', { x: -1223, y: -1768, z: 3.1 }, 0);
worker.setSyncedMeta('npc:destination', { x: -1213, y: -1768, z: 3.1 });
revo.on('serverStop', () => {
if (worker.valid) worker.destroy();
});

Choose positions with a usable navigation mesh. The native uses a walking blend ratio of 1, a target radius of 0.5 metres and a final heading of 0 degrees. If no route exists, the NPC can remain still. See the navigation native for its flags and route diagnostics.

The client handles initial streaming, changed instructions and ownership changes. Its cache prevents duplicate notifications from restarting the same task. Clearing the cache on stream-out allows a recreated ped to receive its instruction again. The NPC keeps the destination after reaching it, so a new owner can restore the same goal. Change the metadata to send it elsewhere, or call worker.deleteSyncedMeta('npc:destination') to cancel the instruction.

See Ownership and simulation for handoff behavior and capacity limits. With no eligible owner nearby, the NPC remains on the server and has no client running its AI.

Methods such as goStraightToCoord(), standStill(), clearTasks(), setRagdoll() and setBlockingOfNonTemporaryEvents() operate on local peds created by the calling resource. They require a loaded GTA instance. The client wrapper for a server-created NPC rejects those writes, including when that client is its network owner.

For a shared NPC, use natives on its simulation owner as shown above. Check ready and isLocallySimulated again after any asynchronous wait. Keep the desired instruction in server state or metadata so a new owner can restore it. Task execution and pathfinding happen in GTA.

goStraightToCoord() requests direct movement. For obstacle-aware movement, use a navigation task. clearTasksImmediately() removes the current tasks without a transition and can visibly interrupt an action.

For clips and animation cleanup, see Animations. For NPC vehicle placement, see Occupants and seats.

Test from an observing client, then move the owner out of range while the observer stays near the NPC. The new owner should restore its destination. Also leave the area entirely and return, change the destination, and remove it while walking. An NPC that stops after handoff usually needs its instruction reapplied. An NPC that repeatedly starts walking needs its task issuance checked for duplicates.