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

# Reportar eventos del jugador

> Traduce los eventos de rol del servidor en observaciones que los NPC con IA entienden.

Usa el export de servidor cuando el juego ocurre fuera de Humalike pero los NPC
cercanos deberían observarlo:

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

Devuelve `true` tras la validación local y el encolado. Devuelve `false` si el
jugador es inválido, el personaje no está cargado o el evento está mal formado.

## Acciones de rol

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

`kind` es `me` o `do`. El texto se recorta, no debe contener caracteres de
control y está limitado a 1.000 caracteres Unicode.

Repórtalo desde el handler del servidor después de que tu recurso de `/me` o
`/do` haya aceptado el comando. No permitas que un cliente envíe la narración
directamente.

## Documento de identidad

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

Los cinco campos son strings obligatorios, recortados y limitados a 128
caracteres Unicode sin caracteres de control.

## Objetos

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

Los tipos admitidos son `item_dropped` e `item_picked_up`. `item_name` puede
contener letras, dígitos, `_`, `.` y `-`, con un máximo de 100 caracteres.
`quantity` debe ser un entero positivo.

Usa el nombre interno del objeto en el framework. La descripción en lenguaje
natural del NPC proviene del contexto circundante y del conocimiento del
personaje.

## Eventos de estado simples

Estos eventos contienen solo `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 observa automáticamente el state bag `HandsUp` del jugador. Reporta tú
mismo los eventos de manos solo si el servidor usa otro mecanismo de estado
autoritativo.

## Observaciones del servidor

Los eventos del jugador son un vocabulario fijo. Para hechos que solo tu
servidor conoce, declara tus propias observaciones en el proveedor de acciones
(`Namespace` + `Observations`, consulta el
[descriptor de acciones](/es/ai-npc/integrations/provider-api#descriptor-de-acciones))
y reporta cada ocurrencia:

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

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

| Argumento  | Tipo            | Descripción                                                                                                                            |
| ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `npcId`    | string          | Un NPC de la plantilla (estático, o externo y vinculado) o un cuerpo ambiental que tu servidor tiene actualmente en concesión (lease). |
| `playerId` | number          | El jugador al que concierne el hecho. El NPC lo recuerda como una acción de ese personaje.                                             |
| `key`      | string          | Una clave de observación declarada, sin el espacio de nombres (`item_given`, no `myserver:item_given`).                                |
| `fields`   | table           | Todos los campos declarados, con el tipo exacto, y nada más.                                                                           |
| `options`  | table, opcional | `{ react = false }` archiva el hecho sin una reacción hablada. Por defecto es `react = true`.                                          |

Los valores de los campos se comprueban en cada reporte:

* Los valores `string` tienen como máximo 64 caracteres sin caracteres de control.
* Los valores `integer` son enteros.
* Los valores `integer` y `number` son finitos y de magnitud máxima 2^53.

El recurso renderiza la plantilla declarada para el idioma del NPC, recurriendo
al inglés y después al primer idioma declarado, y envía esa línea literalmente.
Solo la línea renderizada y los valores comprobados salen del servidor. Una
línea renderizada tiene como máximo 912 caracteres; `RegisterProvider` rechaza
una plantilla cuyo renderizado en el peor caso supere ese límite.

### Valor de retorno

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

| Error                  | Significado                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| `invalid_player`       | `playerId` no es un jugador conectado.                                    |
| `character_not_loaded` | El proveedor de jugador no informa de ningún personaje cargado.           |
| `npc_not_found`        | `npcId` no es un NPC de la plantilla ni un cuerpo ambiental en concesión. |
| `npc_not_bound`        | El NPC externo no tiene un ped vinculado y generado.                      |
| `unknown_observation`  | `key` no está declarada en el proveedor de acciones.                      |
| `invalid_fields`       | `fields` no es una tabla.                                                 |
| `invalid_field:<name>` | Falta un campo declarado o tiene un tipo o tamaño incorrecto.             |
| `unknown_field:<name>` | `fields` contiene una clave no declarada.                                 |
| `invalid_options`      | `options` no es una tabla o `react` no es un booleano.                    |
| `text_too_long`        | La línea renderizada supera los 912 caracteres.                           |

Los errores de declaración los reporta el propio `RegisterProvider`.

### Comportamiento

Una observación reportada es un hecho del servidor, por lo que difiere de un
evento del jugador:

* No está condicionada a estar al alcance del oído.
* Se archiva y, con `react = true`, se habla incluso mientras un script mantiene
  `perception` sobre el NPC. Mantén `speech` para que el NPC permanezca en
  silencio.
* Una repetición de la misma clave en unos 2,5 segundos se archiva pero no se
  vuelve a hablar.

Con `humalike_developer_tools 1`, reporta una a mano mientras cableas el hook
real:

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

## Comportamiento de entrega

El export confirma la aceptación local, no que un NPC vaya a responder. El evento
se entrega con la sesión actual del jugador y el contexto del mundo. Los NPC
pueden observarlo, recordarlo, reaccionar en silencio o hablar según el
personaje y el estado de la conversación.

## Siguiente

* [Declarar acciones definidas por el servidor](/es/ai-npc/integrations/custom-actions) condicionadas a estas observaciones.
* [Construir un puente personalizado](/es/ai-npc/integrations/custom-bridge).
* [Revisar los contratos de proveedor](/es/ai-npc/integrations/provider-api).
* [Solucionar problemas con los comandos de rol](/es/ai-npc/operations#me-o-do-se-ignora).