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

# Sterowanie w czasie działania

> Dzierżaw ruch, animację, mowę lub percepcję dowolnego aktywnego NPC na ograniczony czas.

Dowolny zasób może przejąć wybrane domeny AI dowolnego aktywnego NPC
(statycznego, otoczenia lub powiązanego
[zewnętrznego](/pl/ai-npc/integrations/external-npcs)). Humalike przestaje
działać w tych domenach do końca dzierżawy. Definicja i encja NPC pozostają
nietknięte.

Wszystkie exporty na tej stronie zwracają jedną tabelę wyniku:
`{ apiVersion = 1, ok = true, value = ... }` lub
`{ apiVersion = 1, ok = false, error = code }`. Muszą być wywoływane z zasobu
innego niż `humalike`, w przeciwnym razie kończą się błędem
`external_resource_required`.

## Uzyskaj dzierżawę

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

| Opcja     | Opis                                                                                |
| --------- | ----------------------------------------------------------------------------------- |
| `domains` | Od 1 do 4 spośród `movement`, `animation`, `speech`, `perception`, albo samo `all`. |
| `ttlMs`   | Od 1000 do 300 000. Domyślnie 30 000.                                               |
| `reason`  | Opcjonalny ciąg do 128 znaków, zwracany w dzierżawie.                               |

| Domena       | Efekt w trakcie trzymania                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `movement`   | Akcje ruchu są odrzucane, a Humalike przestaje przemieszczać peda.                                         |
| `animation`  | Akcje animacji są odrzucane, a bieżąca poza jest zapominana.                                               |
| `speech`     | NPC nie mówi. Targetowanie głosowe i etykiety pokazują go jako niedostępnego.                              |
| `perception` | NPC nie słyszy graczy, a zdarzenia gracza nie są mu dostarczane. Obserwacje serwerowe są nadal zapisywane. |
| `all`        | Wszystko powyższe. `aiEnabled` raportuje `false`.                                                          |

Uzyskanie dzierżawy anuluje trwającą akcję NPC w tej domenie. Żądanie, które
pokrywa się z trzymaną domeną, jest odrzucane w całości.

| Błąd                                                                | Znaczenie                                                  |
| ------------------------------------------------------------------- | ---------------------------------------------------------- |
| `npc_not_active`                                                    | NPC nie ma aktywnej encji.                                 |
| `invalid_domains`, `invalid_domain`, `all_domain_must_be_exclusive` | Zła lista `domains`.                                       |
| `invalid_ttl`, `invalid_reason`, `invalid_options`                  | Kształt argumentu.                                         |
| `domain_conflict`                                                   | Żądana domena jest już dzierżawiona.                       |
| `lease_not_found`, `not_owner`                                      | Odnowienie lub zwolnienie nieznanej albo cudzej dzierżawy. |

Dzierżawa kończy się po upływie TTL, gdy zasób będący jej właścicielem się
zatrzymuje, gdy encja NPC znika lub gdy NPC otoczenia zostaje przypisany do
innego ciała.

## Stan czasu działania

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

| Pole                                                | Opis                                                                              |
| --------------------------------------------------- | --------------------------------------------------------------------------------- |
| `kind`                                              | `static`, `ambient` lub `external`.                                               |
| `active`                                            | Czy istnieje aktywna encja.                                                       |
| `entity`, `networkId`, `routingBucket`, `modelHash` | Bieżąca encja. `entity` to uchwyt serwerowy; między granicami używaj `networkId`. |
| `aiEnabled`                                         | `false`, gdy każda domena jest dzierżawiona.                                      |
| `controlledDomains`                                 | Mapa domeny na `{ leaseId, ownerResource, expiresInMs }`.                         |
| `entityOwner`                                       | `humalike`, `external` lub `despawned`.                                           |
| `bindingId`, `despawnId`, `entityOwnerResource`     | Obecne, gdy zasób posiada encję lub despawn.                                      |

`ListNpcRuntimeStates` zwraca każdego NPC z listy NPC, w tym niepowiązane NPC
zewnętrzne, oraz bieżące ciała otoczenia, posortowane według `npcId`, każdy z
`name` i `model`. `GetNpcRuntimeState` kończy się błędem `npc_not_found` dla id
spoza listy NPC.

## Dalej

* [Powiąż własnego peda z postacią](/pl/ai-npc/integrations/external-npcs).
* [Zgłaszaj fakty o NPC](/pl/ai-npc/integrations/world-events#obserwacje-serwerowe).
* [Zwięzła dokumentacja exportów](/pl/ai-npc/reference#eksporty-serwera).