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

# Control en tiempo de ejecución

> Toma en concesión (lease) el movimiento, la animación, el habla o la percepción de cualquier NPC activo durante un tiempo acotado.

Cualquier recurso puede tomar el control de dominios de IA seleccionados de
cualquier NPC activo (estático, ambiental o uno
[externo](/es/ai-npc/integrations/external-npcs) vinculado). Humalike deja de
actuar en esos dominios hasta que termina la concesión (lease). La definición y
la entidad del NPC no se tocan.

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

## Adquirir una concesión

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

| Opción    | Descripción                                                                        |
| --------- | ---------------------------------------------------------------------------------- |
| `domains` | De 1 a 4 de `movement`, `animation`, `speech`, `perception`, o `all` en solitario. |
| `ttlMs`   | De 1.000 a 300.000. Por defecto 30.000.                                            |
| `reason`  | String opcional de hasta 128 caracteres, devuelto en la concesión.                 |

| Dominio      | Efecto mientras se mantiene                                                                                                 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `movement`   | Las acciones de movimiento se rechazan y Humalike deja de pasear al ped.                                                    |
| `animation`  | Las acciones de animación se rechazan y se olvida la pose actual.                                                           |
| `speech`     | El NPC no habla. El targeting de voz y las etiquetas lo muestran como no disponible.                                        |
| `perception` | El NPC no oye a los jugadores y no se le entregan eventos del jugador. Las observaciones del servidor se siguen archivando. |
| `all`        | Todo lo anterior. `aiEnabled` informa `false`.                                                                              |

Adquirir una concesión cancela la acción en curso del NPC en ese dominio. Una
solicitud que se solape con un dominio ya en concesión se rechaza en su
totalidad.

| Error                                                               | Significado                                                   |
| ------------------------------------------------------------------- | ------------------------------------------------------------- |
| `npc_not_active`                                                    | El NPC no tiene una entidad viva.                             |
| `invalid_domains`, `invalid_domain`, `all_domain_must_be_exclusive` | Lista de `domains` incorrecta.                                |
| `invalid_ttl`, `invalid_reason`, `invalid_options`                  | Forma de los argumentos.                                      |
| `domain_conflict`                                                   | Un dominio solicitado ya está en concesión.                   |
| `lease_not_found`, `not_owner`                                      | Renovación o liberación de una concesión desconocida o ajena. |

Una concesión termina al cumplirse su TTL, cuando su recurso propietario se
detiene, cuando la entidad del NPC desaparece o cuando un NPC ambiental se
reasigna a otro cuerpo.

## Estado en tiempo de ejecución

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

| Campo                                               | Descripción                                                                         |
| --------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `kind`                                              | `static`, `ambient` o `external`.                                                   |
| `active`                                            | Si existe una entidad viva.                                                         |
| `entity`, `networkId`, `routingBucket`, `modelHash` | Entidad actual. `entity` es un handle de servidor; usa `networkId` entre fronteras. |
| `aiEnabled`                                         | `false` mientras todos los dominios están en concesión.                             |
| `controlledDomains`                                 | Mapa de dominio a `{ leaseId, ownerResource, expiresInMs }`.                        |
| `entityOwner`                                       | `humalike`, `external` o `despawned`.                                               |
| `bindingId`, `despawnId`, `entityOwnerResource`     | Presentes cuando un recurso es propietario de la entidad o de la eliminación.       |

`ListNpcRuntimeStates` devuelve todos los NPC de la plantilla, incluidos los
externos no vinculados, más los cuerpos ambientales actuales, ordenados por
`npcId`, cada uno con `name` y `model`. `GetNpcRuntimeState` falla con
`npc_not_found` para un id que no esté en la plantilla.

## Siguiente

* [Vincular tu propio ped a un personaje](/es/ai-npc/integrations/external-npcs).
* [Reportar hechos sobre el NPC](/es/ai-npc/integrations/world-events#observaciones-del-servidor).
* [Referencia compacta de exports](/es/ai-npc/reference#exports-de-servidor).