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

# Report player events

> Translate server roleplay events into observations understood by AI NPCs.

Use the server export when gameplay happens outside HumaLike but nearby NPCs
should observe it:

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

It returns `true` after local validation and queueing. It returns `false` for an
invalid player, an unloaded character, or a malformed event.

## Roleplay actions

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

`kind` is `me` or `do`. Text is trimmed, must contain no control characters,
and is limited to 1,000 Unicode characters.

Use this to integrate a custom `/me` or `/do` resource. Report from the server
handler after that resource has accepted the command; do not trust a client to
submit arbitrary narration directly.

## Identity document

```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',
})
```

All five fields are required strings, trimmed and limited to 128 Unicode
characters without control characters.

## Items

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

Supported types are `item_dropped` and `item_picked_up`. `item_name` may contain
letters, digits, `_`, `.`, and `-`, with a maximum of 100 characters. `quantity`
must be a positive integer.

Use the framework's internal item name. The NPC's natural-language description
comes from the surrounding context and character knowledge.

## Simple state events

These events contain only `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 observes the `HandsUp` player state bag automatically. Only report the
hands events yourself if the server uses another authoritative state mechanism.

## Delivery behavior

The export confirms local acceptance, not that an NPC will necessarily answer.
The event is delivered with the player's current session and world context. NPCs
may observe it, remember it, react silently, or speak depending on character and
conversation state.

## Next

* [Build a custom bridge](/ai-npc/integrations/custom-bridge).
* [Review provider contracts](/ai-npc/integrations/provider-api).
* [Troubleshoot roleplay commands](/ai-npc/operations#me-or-do-is-ignored).