> ## 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.

# NPC externos

> Vincula un personaje de Humalike a un ped que tu propio recurso genera y controla.

Un NPC **externo** es un personaje del panel cuyo ped es generado, movido y
eliminado por tu recurso. Humalike adjunta la identidad a tu entidad y nunca la
genera, posiciona, congela ni elimina. Para tomar el control de la IA de un NPC
que Humalike mismo generó, consulta [Control en tiempo de ejecución](/es/ai-npc/integrations/runtime-control).

Todos los exports de esta página devuelven una tabla de resultado:
`{ apiVersion = 1, ok = true, value = ... }` o
`{ apiVersion = 1, ok = false, error = code }`. Deben llamarse desde un recurso
distinto de `humalike`, o fallan con `external_resource_required`.

## Crear el personaje

En el panel, crea el NPC con tipo **External** y el modelo de ped que tu script
generará. No se requiere ubicación. Se pueden activar acciones de movilidad. El
NPC permanece desconectado hasta que un recurso le vincula una entidad.

## Vincular una entidad

```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)
```

| Argumento               | Tipo              | Descripción                                          |
| ----------------------- | ----------------- | ---------------------------------------------------- |
| `npcId`                 | string            | El id del NPC externo.                               |
| `networkId`             | integer           | Id de red de un ped que tu recurso controla.         |
| `options.routingBucket` | integer, opcional | Se rechaza si difiere del bucket real de la entidad. |

La entidad debe existir, ser un ped que no sea de jugador, usar el modelo
configurado del NPC y no llevar ninguna otra identidad de Humalike. Una
vinculación por NPC y por entidad. Repetir la misma vinculación desde el mismo
recurso devuelve la vinculación existente. Desvincular elimina el estado de
Humalike y deja el ped intacto.

| Error                                                                               | Significado                                                                   |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `invalid_npc_id`, `invalid_network_id`, `invalid_options`, `invalid_routing_bucket` | Forma de los argumentos.                                                      |
| `npc_not_found`                                                                     | No está en la plantilla sincronizada.                                         |
| `npc_not_external`                                                                  | El NPC es estático o ambiental.                                               |
| `entity_not_found`, `entity_not_ped`, `player_ped_not_allowed`                      | El id de red no se resuelve a un ped que no sea de jugador.                   |
| `model_mismatch`                                                                    | El modelo del ped difiere del modelo configurado del NPC.                     |
| `routing_bucket_mismatch`                                                           | `options.routingBucket` difiere del bucket de la entidad.                     |
| `entity_already_humalike`                                                           | El ped ya lleva una identidad de Humalike.                                    |
| `npc_ownership_conflict`                                                            | Otro recurso ha vinculado este NPC.                                           |
| `entity_ownership_conflict`                                                         | Esta entidad está vinculada a otro NPC.                                       |
| `binding_not_found`, `not_owner`                                                    | `UnbindNpcEntity` con un id desconocido o con la vinculación de otro recurso. |

## Ciclo de vida

* Tus vinculaciones se desprenden cuando tu recurso se detiene.
* Una vinculación se descarta cuando la entidad desaparece, cambia de modelo o
  de routing bucket, o cuando el tipo del NPC cambia en el panel.
* Humalike emite el evento de servidor `humalike:npc:ready` con
  `{ apiVersion, generation }` tras la primera sincronización de la plantilla de
  cada generación del tiempo de ejecución. Un recurso que arranca más tarde se
  lo pierde.

Vincula en tu propio inicio y de nuevo en cada evento ready. Una vinculación
intentada antes de la primera sincronización de la plantilla falla con
`npc_not_found` y tiene éxito en el evento:

```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)
```

## Eliminar un NPC estático

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

Elimina el ped de un NPC estático del tiempo de ejecución sin cambiar su
definición. Solo el recurso que lo eliminó puede volver a generarlo, y sus
eliminaciones se restauran cuando ese recurso se detiene.

| Error                             | Significado                                                         |
| --------------------------------- | ------------------------------------------------------------------- |
| `npc_not_found`, `npc_not_static` | No es un NPC estático de la plantilla.                              |
| `runtime_binding_unavailable`     | El NPC aún no tiene una vinculación viva en el tiempo de ejecución. |
| `despawn_not_found`, `not_owner`  | `RespawnNpc` para un NPC que este recurso no eliminó.               |
| `spawn_failed`                    | No se pudo volver a crear el ped.                                   |

## Siguiente

* [Tomar en concesión (lease) el control de los dominios de IA de un NPC](/es/ai-npc/integrations/runtime-control).
* [Reportar hechos sobre tu NPC](/es/ai-npc/integrations/world-events#observaciones-del-servidor).
* [Referencia compacta de exports](/es/ai-npc/reference#exports-de-servidor).