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

# PNJ externes

> Liez un personnage Humalike à un ped que votre propre ressource fait apparaître et possède.

Un PNJ **externe** est un personnage du tableau de bord dont le ped est créé,
déplacé et supprimé par votre ressource. Humalike attache l'identité à votre
entité et ne la fait jamais apparaître, ne la positionne, ne la fige ni ne la
supprime. Pour prendre le contrôle de l'IA d'un PNJ que Humalike a lui-même fait
apparaître, voir [Contrôle d'exécution](/fr/ai-npc/integrations/runtime-control).

Tous les exports de cette page renvoient une seule table de résultat :
`{ apiVersion = 1, ok = true, value = ... }` ou
`{ apiVersion = 1, ok = false, error = code }`. Ils doivent être appelés depuis
une ressource autre que `humalike`, sinon ils échouent avec
`external_resource_required`.

## Créer le personnage

Dans le tableau de bord, créez le PNJ avec le type **External** et le modèle de
ped que votre script fera apparaître. Aucun placement n'est requis. Les actions
de mobilité peuvent être activées. Le PNJ reste hors ligne jusqu'à ce qu'une
ressource lui lie une entité.

## Lier une entité

```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              | L'id du PNJ externe.                            |
| `networkId`             | integer             | Id réseau d'un ped que votre ressource possède. |
| `options.routingBucket` | integer, facultatif | Refusé s'il diffère du bucket réel de l'entité. |

L'entité doit exister, être un ped non-joueur, utiliser le modèle configuré du
PNJ et ne porter aucune autre identité Humalike. Une liaison par PNJ et par
entité. Répéter la même liaison depuis la même ressource renvoie la liaison
existante. Délier retire l'état Humalike et laisse le ped intact.

| Erreur                                                                              | Signification                                                             |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `invalid_npc_id`, `invalid_network_id`, `invalid_options`, `invalid_routing_bucket` | Forme des arguments.                                                      |
| `npc_not_found`                                                                     | Absent du registre synchronisé.                                           |
| `npc_not_external`                                                                  | Le PNJ est statique ou ambiant.                                           |
| `entity_not_found`, `entity_not_ped`, `player_ped_not_allowed`                      | L'id réseau ne correspond pas à un ped non-joueur.                        |
| `model_mismatch`                                                                    | Le modèle du ped diffère du modèle configuré du PNJ.                      |
| `routing_bucket_mismatch`                                                           | `options.routingBucket` diffère du bucket de l'entité.                    |
| `entity_already_humalike`                                                           | Le ped porte déjà une identité Humalike.                                  |
| `npc_ownership_conflict`                                                            | Une autre ressource a lié ce PNJ.                                         |
| `entity_ownership_conflict`                                                         | Cette entité est liée à un autre PNJ.                                     |
| `binding_not_found`, `not_owner`                                                    | `UnbindNpcEntity` avec un id inconnu ou la liaison d'une autre ressource. |

## Cycle de vie

* Vos liaisons sont détachées lorsque votre ressource s'arrête.
* Une liaison est abandonnée lorsque l'entité disparaît, change de modèle ou de
  routing bucket, ou lorsque le type du PNJ change dans le tableau de bord.
* Humalike émet l'événement serveur `humalike:npc:ready` avec
  `{ apiVersion, generation }` après la première synchronisation du registre de
  chaque génération d'exécution. Une ressource qui démarre plus tard le manque.

Liez à votre propre démarrage et à nouveau à chaque événement ready. Une liaison
tentée avant la première synchronisation du registre échoue avec
`npc_not_found` et réussit lors de l'événement :

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

## Faire disparaître un PNJ statique

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

Retire le ped d'un PNJ statique de l'exécution sans modifier sa définition.
Seule la ressource qui l'a fait disparaître peut le faire réapparaître, et ses
disparitions sont restaurées lorsqu'elle s'arrête.

| Erreur                            | Signification                                                          |
| --------------------------------- | ---------------------------------------------------------------------- |
| `npc_not_found`, `npc_not_static` | Pas un PNJ statique du registre.                                       |
| `runtime_binding_unavailable`     | Le PNJ n'a pas encore de liaison d'exécution active.                   |
| `despawn_not_found`, `not_owner`  | `RespawnNpc` pour un PNJ que cette ressource n'a pas fait disparaître. |
| `spawn_failed`                    | Le ped n'a pas pu être recréé.                                         |

## Suite

* [Prendre à bail le contrôle des domaines IA d'un PNJ](/fr/ai-npc/integrations/runtime-control).
* [Signaler des faits sur votre PNJ](/fr/ai-npc/integrations/world-events#observations-serveur).
* [Référence compacte des exports](/fr/ai-npc/reference#exports-serveur).