> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humalike.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External NPCs

> Bind a Humalike character to a ped your own resource spawns and owns.

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](/ai-npc/integrations/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

```lua theme={null}
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:

```lua theme={null}
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

```lua theme={null}
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.                        |

## Next

* [Lease control of an NPC's AI domains](/ai-npc/integrations/runtime-control).
* [Report facts about your NPC](/ai-npc/integrations/world-events#server-observations).
* [Compact export reference](/ai-npc/reference#server-exports).