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

# Contrôle d'exécution

> Prenez à bail le mouvement, l'animation, la parole ou la perception de tout PNJ actif pour une durée bornée.

Toute ressource peut prendre le contrôle de domaines IA choisis de tout PNJ
actif (statique, ambiant, ou [externe](/fr/ai-npc/integrations/external-npcs)
et lié). Humalike cesse d'agir dans ces domaines jusqu'à la fin du bail. La
définition et l'entité du PNJ restent intactes.

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

## Acquérir un bail

```lua theme={null}
local result = exports.humalike:AcquireNpcControl(npcId, {
    domains = { 'movement', 'animation' },
    ttlMs = 30000,
    reason = 'hostage_scenario',
})
if not result.ok then return print(result.error) end
local lease = result.value  -- { id, npcId, kind, ownerResource, domains, reason, expiresInMs }

exports.humalike:RenewNpcControl(lease.id, 30000)
exports.humalike:ReleaseNpcControl(lease.id)
```

| Option    | Description                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| `domains` | De 1 à 4 parmi `movement`, `animation`, `speech`, `perception`, ou `all` seul. |
| `ttlMs`   | De 1 000 à 300 000. 30 000 par défaut.                                         |
| `reason`  | Chaîne facultative de 128 caractères au plus, renvoyée dans le bail.           |

| Domaine      | Effet pendant la détention                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `movement`   | Les actions de mouvement sont refusées et Humalike cesse de faire déambuler le ped.                                                   |
| `animation`  | Les actions d'animation sont refusées et la pose courante est oubliée.                                                                |
| `speech`     | Le PNJ ne parle pas. Le ciblage vocal et les libellés le montrent comme indisponible.                                                 |
| `perception` | Le PNJ n'entend pas les joueurs et les événements joueur ne lui sont pas livrés. Les observations serveur sont toujours enregistrées. |
| `all`        | Tout ce qui précède. `aiEnabled` rapporte `false`.                                                                                    |

Acquérir un bail annule l'action en cours du PNJ dans ce domaine. Une requête
qui chevauche un domaine déjà détenu est refusée dans son ensemble.

| Erreur                                                              | Signification                                                                        |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `npc_not_active`                                                    | Le PNJ n'a aucune entité active.                                                     |
| `invalid_domains`, `invalid_domain`, `all_domain_must_be_exclusive` | Liste `domains` incorrecte.                                                          |
| `invalid_ttl`, `invalid_reason`, `invalid_options`                  | Forme des arguments.                                                                 |
| `domain_conflict`                                                   | Un domaine demandé est déjà sous bail.                                               |
| `lease_not_found`, `not_owner`                                      | Renouvellement ou libération d'un bail inconnu ou appartenant à une autre ressource. |

Un bail prend fin à l'expiration de son TTL, lorsque sa ressource propriétaire
s'arrête, lorsque l'entité du PNJ disparaît, ou lorsqu'un PNJ ambiant est
réaffecté à un autre corps.

## État d'exécution

```lua theme={null}
local state = exports.humalike:GetNpcRuntimeState(npcId).value
local rows = exports.humalike:ListNpcRuntimeStates().value
```

| Champ                                               | Description                                                                                    |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `kind`                                              | `static`, `ambient` ou `external`.                                                             |
| `active`                                            | Indique si une entité active existe.                                                           |
| `entity`, `networkId`, `routingBucket`, `modelHash` | Entité courante. `entity` est un handle serveur ; utilisez `networkId` au-delà des frontières. |
| `aiEnabled`                                         | `false` tant que tous les domaines sont sous bail.                                             |
| `controlledDomains`                                 | Correspondance de domaine vers `{ leaseId, ownerResource, expiresInMs }`.                      |
| `entityOwner`                                       | `humalike`, `external` ou `despawned`.                                                         |
| `bindingId`, `despawnId`, `entityOwnerResource`     | Présents lorsqu'une ressource possède l'entité ou la disparition.                              |

`ListNpcRuntimeStates` renvoie chaque PNJ du registre, y compris les PNJ
externes non liés, plus les corps ambiants courants, triés par `npcId`, chacun
avec `name` et `model`. `GetNpcRuntimeState` échoue avec `npc_not_found` pour
un id absent du registre.

## Suite

* [Lier votre propre ped à un personnage](/fr/ai-npc/integrations/external-npcs).
* [Signaler des faits sur le PNJ](/fr/ai-npc/integrations/world-events#observations-serveur).
* [Référence compacte des exports](/fr/ai-npc/reference#exports-serveur).