SpawnNpc
spawnNpc
Creates a server-owned human visual NPC at an authoritative position.
Syntax
int|false spawnNpc(string name, string skinKey, number x, number y, number z [, number yaw = 0] [, table options])
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string |
yes | Validated display name for the NPC. |
skinKey |
string |
yes | A preset returned by getPlayerSkinNames.
|
x |
number |
yes | Spawn X coordinate in metres. |
y |
number |
yes | Spawn Y coordinate in metres. |
z |
number |
yes | Spawn Z coordinate in metres. |
yaw |
number |
no | Optional initial yaw in degrees; defaults to 0. |
options |
table |
no | Optional table. Set navigationCollisionMode to "combined", "builtin", or "custom"; the default is "combined".
|
Returns
Returns the new numeric NPC identifier, or false when validation or spawning fails.
Examples
Place a guard and equip it:
local npcId = spawnNpc("North Gate Guard", "guard_01", 12.5, 4.0, 1.8, 180, {
navigationCollisionMode = "combined",
})
if npcId then
setNpcArmor(npcId, "guard_armor")
setNpcWeapon(npcId, "1h_sword_01")
end
Notes
- Available only in server-side resource scripts.
- The calling resource owns the NPC and is the only resource allowed to mutate or remove it.
- The selected navigation collision mode is applied to initial placement. Pass it during spawn when replacing a known baked false positive with custom blockers.
- Identity, transform, skin, armor and weapon are replicated on relevance entry and late join.
- This creates a script-controlled visual proxy; routes are configured separately with
setNpcRoute.
Optional combat since 0.1.5
New NPC defaults: health/maxHealth 100, invulnerable=true, holstered, no target, base melee damage 10. Mana starts at 0/maxMana 100; arrows/bolts 0. No automatic aggression. Explicitly configure combat with NPC scripting.
Appearance API since 0.1.5
From 0.1.5 new NPCs have no explicit identity/tint/tattoo override; existing skin behaviour is preserved. Configure setNpcIdentity, setNpcSkinColor and setNpcTattoo after spawning. These do not start combat or replace equipped armor.
Direct private spawn (since 0.1.8)
The optional options table also accepts dimension, an integer number from 0 to 2147483647. Omitted means 0. Invalid values reject the spawn. This creates the actor directly in that dimension, avoiding temporary public exposure before a setter. All other spawn/type/placement validation remains active.
See Character dimensions for examples and setNpcDimension for moving an existing owned actor.