> ## 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 zewnętrzne

> Powiąż postać Humalike z pedem, którego spawnuje i posiada Twój własny zasób.

NPC **zewnętrzny** to postać z panelu, której ped jest spawnowany, przemieszczany
i usuwany przez Twój zasób. Humalike dołącza tożsamość do Twojej encji i nigdy
jej nie spawnuje, nie pozycjonuje, nie zamraża ani nie usuwa. Aby przejąć AI
NPC, którego Humalike zespawnował samodzielnie, zobacz
[Sterowanie w czasie działania](/pl/ai-npc/integrations/runtime-control).

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

## Utwórz postać

W panelu utwórz NPC typu **External** z modelem peda, który zespawnuje Twój
skrypt. Rozmieszczenie nie jest wymagane. Akcje mobilności mogą być włączone.
NPC pozostaje offline, dopóki jakiś zasób nie powiąże z nim encji.

## Powiąż encję

```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                | Typ                 | Opis                                                     |
| ----------------------- | ------------------- | -------------------------------------------------------- |
| `npcId`                 | string              | Id NPC zewnętrznego.                                     |
| `networkId`             | integer             | Network id peda, który posiada Twój zasób.               |
| `options.routingBucket` | integer, opcjonalne | Odrzucane, jeśli różni się od faktycznego bucketu encji. |

Encja musi istnieć, być pedem niebędącym graczem, używać skonfigurowanego modelu
NPC i nie nosić innej tożsamości Humalike. Jedno powiązanie na NPC i na encję.
Powtórzenie tego samego powiązania z tego samego zasobu zwraca istniejące
powiązanie. Odwiązanie usuwa stan Humalike i pozostawia peda nietkniętego.

| Błąd                                                                                | Znaczenie                                                       |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `invalid_npc_id`, `invalid_network_id`, `invalid_options`, `invalid_routing_bucket` | Kształt argumentu.                                              |
| `npc_not_found`                                                                     | Nie ma go na zsynchronizowanej liście NPC.                      |
| `npc_not_external`                                                                  | NPC jest statyczny lub otoczenia.                               |
| `entity_not_found`, `entity_not_ped`, `player_ped_not_allowed`                      | Network id nie wskazuje na peda niebędącego graczem.            |
| `model_mismatch`                                                                    | Model peda różni się od skonfigurowanego modelu NPC.            |
| `routing_bucket_mismatch`                                                           | `options.routingBucket` różni się od bucketu encji.             |
| `entity_already_humalike`                                                           | Ped już nosi tożsamość Humalike.                                |
| `npc_ownership_conflict`                                                            | Inny zasób powiązał tego NPC.                                   |
| `entity_ownership_conflict`                                                         | Ta encja jest powiązana z innym NPC.                            |
| `binding_not_found`, `not_owner`                                                    | `UnbindNpcEntity` z nieznanym id lub powiązaniem innego zasobu. |

## Cykl życia

* Twoje powiązania są odłączane, gdy Twój zasób się zatrzymuje.
* Powiązanie jest zrywane, gdy encja znika, zmienia model lub routing bucket,
  albo gdy typ NPC zmienia się w panelu.
* Humalike emituje zdarzenie serwerowe `humalike:npc:ready` z
  `{ apiVersion, generation }` po pierwszej synchronizacji listy NPC w każdej
  generacji czasu działania. Zasób, który startuje później, je przegapi.

Wiąż przy własnym starcie i ponownie przy każdym zdarzeniu ready. Próba
powiązania przed pierwszą synchronizacją listy NPC kończy się błędem
`npc_not_found` i udaje się przy zdarzeniu:

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

## Despawnuj NPC statycznego

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

Usuwa peda NPC statycznego z czasu działania bez zmiany jego definicji. Tylko
zasób, który go despawnował, może go respawnować, a jego despawny są
przywracane, gdy się zatrzymuje.

| Błąd                              | Znaczenie                                                   |
| --------------------------------- | ----------------------------------------------------------- |
| `npc_not_found`, `npc_not_static` | Nie jest NPC statycznym na liście NPC.                      |
| `runtime_binding_unavailable`     | NPC nie ma jeszcze aktywnego powiązania w czasie działania. |
| `despawn_not_found`, `not_owner`  | `RespawnNpc` dla NPC, którego ten zasób nie despawnował.    |
| `spawn_failed`                    | Nie udało się odtworzyć peda.                               |

## Dalej

* [Dzierżaw sterowanie domenami AI NPC](/pl/ai-npc/integrations/runtime-control).
* [Zgłaszaj fakty o swoim NPC](/pl/ai-npc/integrations/world-events#obserwacje-serwerowe).
* [Zwięzła dokumentacja exportów](/pl/ai-npc/reference#eksporty-serwera).