Skip to main content

Server NPC API

These APIs are server-side only. Server NPCs and Actors have their own entity namespace and never consume authenticated player slots. Ambient GTA pedestrians and traffic are a separate boolean toggle and cannot be controlled individually.

Server NPCs​

Server NPCs are controlled characters. Creation and mutation are authoritative and replicated to eligible clients.

const created = server.npcs.create(42, {
  modelId: 7,
  position: { x: 2495, y: -1681, z: 13 },
  heading: 90,
});

await server.npcs.set(42, "health", 100);
await server.npcs.set(42, "position", { x: 2500, y: -1681, z: 13, heading: 90 });
const position = await server.npcs.get(42, "position");
server.npcs.moveTo(42, { x: 2500, y: -1681, z: 13 });

create, destroy and moveTo validate IDs, finite coordinates and entity ownership. The request/response getters read native authoritative state rather than a local SDK cache. Supported properties are name, skin, health, maxHealth, invulnerable, position, heading, virtualWorld, interior, weapon, ammo and clipAmmo.

Setter requests are validated on the server and return a Promise<boolean>; a rejected request does not change native state. Weapon, ammo/clip ammo, interior and virtual-world setters now use this same request/response contract. Position and heading use the validated moveTo operation or the equivalent set(..., "position", ...) request; vehicle-control setters now cover creation/destruction, position, health, engine and lock state.

Actors​

Actors are static server-owned characters. They can be created, destroyed and animated, but they do not move through the Server NPC movement API and never use player slots.

Events​

The event surface includes npcSpawn, npcDeath, npcFinishPath and actorPlayerAim. Each event will carry the server entity ID and a typed payload; events are emitted only after native state validation. Events are not client-authoritative notifications.

Limits and security​

  • IDs are positive unsigned 32-bit values and are scoped to the server resource/runtime.
  • Model IDs are unsigned 16-bit values.
  • Coordinates and headings must be finite numbers.
  • Client code cannot call these server APIs directly or mutate their state.
  • NPC and Actor entities are excluded from the player-slot allocator and player max limit.