External NPCs

An external NPC is a dashboard character whose ped is spawned, moved and deleted by your resource. HumaLike attaches the identity to your entity and never spawns, positions, freezes or deletes it. To take over the AI of an NPC HumaLike itself spawned, see Runtime control. All exports on this page return one result table: { apiVersion = 1, ok = true, value = ... } or { apiVersion = 1, ok = false, error = code }. They must be called from a resource other than humalike, or they fail with external_resource_required.

Create the character

In the dashboard, create the NPC with type External and the ped model your script will spawn. No placement is required. Mobility actions may be enabled. The NPC stays offline until a resource binds an entity to it.

Bind an entity

local result = exports.humalike:BindNpcEntity(npcId, networkId, { routingBucket = 0 })
if not result.ok then return print(result.error) end
local binding = result.value  -- { id, npcId, networkId, routingBucket, ownerResource }

exports.humalike:UnbindNpcEntity(binding.id)

Argument	Type	Description
`npcId`	string	The external NPC’s id.
`networkId`	integer	Network id of a ped your resource owns.
`options.routingBucket`	integer, optional	Refused if it differs from the entity’s actual bucket.

The entity must exist, be a non-player ped, use the NPC’s configured model and carry no other HumaLike identity. One binding per NPC and per entity. Repeating the same bind from the same resource returns the existing binding. Unbind removes HumaLike state and leaves the ped untouched.

Error	Meaning
`invalid_npc_id`, `invalid_network_id`, `invalid_options`, `invalid_routing_bucket`	Argument shape.
`npc_not_found`	Not on the synced roster.
`npc_not_external`	The NPC is static or ambient.
`entity_not_found`, `entity_not_ped`, `player_ped_not_allowed`	The network id does not resolve to a non-player ped.
`model_mismatch`	The ped’s model differs from the NPC’s configured model.
`routing_bucket_mismatch`	`options.routingBucket` differs from the entity’s bucket.
`entity_already_humalike`	The ped already carries a HumaLike identity.
`npc_ownership_conflict`	Another resource has bound this NPC.
`entity_ownership_conflict`	This entity is bound to another NPC.
`binding_not_found`, `not_owner`	`UnbindNpcEntity` with an unknown id or another resource’s binding.

Lifecycle

Your bindings are detached when your resource stops.
A binding is dropped when the entity disappears, changes model or routing bucket, or when the NPC’s type changes in the dashboard.
HumaLike emits the server event humalike:npc:ready with { apiVersion, generation } after the first roster sync of each runtime generation. A resource that starts later misses it.

Bind on your own start and again on every ready event. A bind attempted before the first roster sync fails with npc_not_found and succeeds on the event:

local function bindAll()
    for npcId, record in pairs(myPeds) do
        exports.humalike:BindNpcEntity(npcId, record.networkId)
    end
end

AddEventHandler('onResourceStart', function(resource)
    if resource == GetCurrentResourceName() then bindAll() end
end)

AddEventHandler('humalike:npc:ready', bindAll)

Despawn a static NPC

local despawn = exports.humalike:DespawnNpc(npcId)   -- value = { id, npcId, ownerResource }
local restored = exports.humalike:RespawnNpc(npcId)

Removes a static NPC’s ped from the runtime without changing its definition. Only the despawning resource can respawn it, and its despawns are restored when it stops.

Error	Meaning
`npc_not_found`, `npc_not_static`	Not a static NPC on the roster.
`runtime_binding_unavailable`	The NPC has no live runtime binding yet.
`despawn_not_found`, `not_owner`	`RespawnNpc` for an NPC this resource did not despawn.
`spawn_failed`	The ped could not be recreated.

Get started

Configure

Integrate

Operate

Create the character

Bind an entity

Lifecycle

Despawn a static NPC

Next

​Create the character

​Bind an entity

​Lifecycle

​Despawn a static NPC

​Next

Create the character

Bind an entity

Lifecycle

Despawn a static NPC

Next