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

# Zgłaszaj zdarzenia gracza

> Tłumacz zdarzenia roleplay serwera na obserwacje rozumiane przez NPC AI.

Użyj exportu serwerowego, gdy rozgrywka dzieje się poza Humalike, ale pobliskie
NPC powinny ją zaobserwować:

```lua theme={null}
local accepted = exports.humalike:ReportPlayerEvent(playerId, event)
```

Zwraca `true` po lokalnej walidacji i zakolejkowaniu. Zwraca `false` dla
nieprawidłowego gracza, niewczytanej postaci lub źle sformułowanego zdarzenia.

## Akcje roleplay

```lua theme={null}
exports.humalike:ReportPlayerEvent(source, {
    type = 'rp_action',
    kind = 'me',
    text = 'places the envelope on the table',
})
```

`kind` to `me` lub `do`. Tekst jest przycinany, nie może zawierać znaków
sterujących i jest ograniczony do 1000 znaków Unicode.

Zgłaszaj z handlera serwerowego po tym, jak Twój zasób `/me` lub `/do` przyjął
komendę. Nie pozwalaj klientowi przesyłać narracji bezpośrednio.

## Dokument tożsamości

```lua theme={null}
exports.humalike:ReportPlayerEvent(source, {
    type = 'identity_document_shown',
    full_name = 'Alex Carter',
    last_name = 'Carter',
    sex = 'X',
    ssn = '123456',
    issued_at = '2026-01-15',
})
```

Wszystkie pięć pól to wymagane ciągi znaków, przycinane i ograniczone do 128
znaków Unicode bez znaków sterujących.

## Przedmioty

```lua theme={null}
exports.humalike:ReportPlayerEvent(source, {
    type = 'item_dropped',
    item_name = 'water',
    quantity = 2,
})
```

Obsługiwane typy to `item_dropped` i `item_picked_up`. `item_name` może zawierać
litery, cyfry, `_`, `.` i `-`, maksymalnie 100 znaków. `quantity` musi być
dodatnią liczbą całkowitą.

Używaj wewnętrznej nazwy przedmiotu z frameworka. Opis NPC w języku naturalnym
pochodzi z otaczającego kontekstu i wiedzy postaci.

## Proste zdarzenia stanu

Te zdarzenia zawierają tylko `type`:

```lua theme={null}
exports.humalike:ReportPlayerEvent(source, { type = 'police_badge_shown' })
```

* `police_badge_shown`
* `ems_badge_shown`
* `doj_badge_shown`
* `hands_raised`
* `hands_lowered`

Humalike automatycznie obserwuje state bag gracza `HandsUp`. Zgłaszaj zdarzenia
rąk samodzielnie tylko wtedy, gdy serwer używa innego autorytatywnego mechanizmu
stanu.

## Obserwacje serwerowe

Zdarzenia gracza to stały słownik. Dla faktów, które zna tylko Twój serwer,
zadeklaruj własne obserwacje na dostawcy akcji (`Namespace` + `Observations`,
zobacz [deskryptor akcji](/pl/ai-npc/integrations/provider-api#deskryptor-akcji))
i zgłaszaj każde wystąpienie:

```lua theme={null}
local result = exports.humalike:ReportObservation(npcId, playerId, key, fields, options)

exports.humalike:ReportObservation(npcId, source, 'item_given', {
    item = 'amulet', quantity = 1,
})
```

| Argument   | Typ               | Opis                                                                                                                  |
| ---------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `npcId`    | string            | NPC z listy NPC (statyczny albo zewnętrzny i powiązany) lub ciało otoczenia aktualnie dzierżawione przez Twój serwer. |
| `playerId` | number            | Gracz, którego dotyczy fakt. NPC zapamiętuje go jako akcję tej postaci.                                               |
| `key`      | string            | Zadeklarowany klucz obserwacji, bez przestrzeni nazw (`item_given`, nie `myserver:item_given`).                       |
| `fields`   | table             | Każde zadeklarowane pole, dokładnie tego typu, i nic więcej.                                                          |
| `options`  | table, opcjonalne | `{ react = false }` zapisuje fakt bez wypowiedzianej reakcji. Domyślnie `react = true`.                               |

Wartości pól są sprawdzane przy każdym zgłoszeniu:

* Wartości `string` mają co najwyżej 64 znaki i nie zawierają znaków sterujących.
* Wartości `integer` są całkowite.
* Wartości `integer` i `number` są skończone i co najwyżej 2^53 co do wartości bezwzględnej.

Zasób renderuje szablon zadeklarowany dla języka NPC, z awaryjnym przejściem na
angielski, a następnie na pierwszy zadeklarowany język, i wysyła tę linię
dosłownie. Serwer opuszczają wyłącznie wyrenderowana linia i sprawdzone
wartości. Wyrenderowana linia ma co najwyżej 912 znaków; `RegisterProvider`
odrzuca szablon, którego najgorszy przypadek renderowania by to przekroczył.

### Wartość zwracana

```lua theme={null}
{ ok = true, value = { key = 'myserver:item_given', text = '...' } }
{ ok = false, error = 'unknown_observation' }
```

| Błąd                   | Znaczenie                                                            |
| ---------------------- | -------------------------------------------------------------------- |
| `invalid_player`       | `playerId` nie jest połączonym graczem.                              |
| `character_not_loaded` | Dostawca gracza nie zgłasza wczytanej postaci.                       |
| `npc_not_found`        | `npcId` nie jest NPC z listy NPC ani dzierżawionym ciałem otoczenia. |
| `npc_not_bound`        | NPC zewnętrzny nie ma powiązanego, zespawnowanego peda.              |
| `unknown_observation`  | `key` nie jest zadeklarowany na dostawcy akcji.                      |
| `invalid_fields`       | `fields` nie jest tabelą.                                            |
| `invalid_field:<name>` | Zadeklarowanego pola brakuje albo ma zły typ lub rozmiar.            |
| `unknown_field:<name>` | `fields` zawiera niezadeklarowany klucz.                             |
| `invalid_options`      | `options` nie jest tabelą lub `react` nie jest wartością logiczną.   |
| `text_too_long`        | Wyrenderowana linia przekracza 912 znaków.                           |

Błędy deklaracji zgłasza sam `RegisterProvider`.

### Zachowanie

Zgłoszona obserwacja jest faktem serwerowym, więc różni się od zdarzenia gracza:

* Nie jest ograniczona zasięgiem słuchu.
* Jest zapisywana i, przy `react = true`, wypowiadana nawet wtedy, gdy skrypt
  trzyma `perception` na NPC. Trzymaj `speech`, aby NPC milczał.
* Powtórzenie tego samego klucza w ciągu około 2,5 sekundy jest zapisywane, ale
  nie wypowiadane ponownie.

Przy `humalike_developer_tools 1` zgłoś jedną ręcznie podczas podłączania
prawdziwego hooka:

```text theme={null}
/humalike_dev observe <npc_uuid> <key> [field=value ...]
```

## Zachowanie dostarczania

Export potwierdza lokalne przyjęcie, a nie to, że NPC odpowie. Zdarzenie jest
dostarczane wraz z bieżącą sesją gracza i kontekstem świata. NPC mogą je
zaobserwować, zapamiętać, zareagować w milczeniu lub odezwać się, zależnie od
postaci i stanu rozmowy.

## Dalej

* [Zadeklaruj akcje zdefiniowane przez serwer](/pl/ai-npc/integrations/custom-actions) warunkowane tymi obserwacjami.
* [Zbuduj własny most](/pl/ai-npc/integrations/custom-bridge).
* [Przejrzyj kontrakty dostawców](/pl/ai-npc/integrations/provider-api).
* [Rozwiązuj problemy z komendami roleplay](/pl/ai-npc/operations#me-lub-do-jest-ignorowane).