NPCs and scripted behavior
Create an NPC
Section titled “Create an NPC”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.
Give a shared NPC a destination
Section titled “Give a shared NPC a destination”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.
// @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();});// @ts-check/// <reference types="@revomp/types-client" />/// <reference types="@revomp/types-natives" />import * as revo from 'revo-client';import * as natives from 'natives';
/** @type {WeakMap<revo.Ped, string>} */const applied = new WeakMap();
/** @param {revo.Base} entity */function applyDestination(entity) { if (!(entity instanceof revo.Ped) || entity instanceof revo.Player || !entity.isNetworked) return;
if (!entity.ready || !entity.isLocallySimulated) { applied.delete(entity); return; }
/** @type {import('revo-shared').IVector3 | undefined} */ const destination = entity.getSyncedMeta('npc:destination'); if (!destination) { if (applied.delete(entity)) { natives.clearPedTasks(entity); natives.setBlockingOfNonTemporaryEvents(entity, false); } return; }
const key = `${destination.x},${destination.y},${destination.z}`; if (applied.get(entity) === key) return;
natives.setBlockingOfNonTemporaryEvents(entity, true); natives.taskFollowNavMeshToCoord( entity, destination.x, destination.y, destination.z, 1, -1, 0.5, 0, 0, ); applied.set(entity, key);}
revo.on('entityStreamIn', applyDestination);revo.on('netOwnerChanged', applyDestination);revo.on('syncedMetaChange', (entity, key) => { if (key === 'npc:destination') applyDestination(entity);});revo.on('entityStreamOut', entity => { if (entity instanceof revo.Ped) applied.delete(entity);});
for (const ped of revo.Ped.all) applyDestination(ped);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.
Task methods and natives
Section titled “Task methods and natives”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.
Check behavior
Section titled “Check behavior”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.