Reportar eventos del jugador

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

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

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

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

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:

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) y reporta cada ocurrencia:

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

{ 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:

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

Declarar acciones definidas por el servidor condicionadas a estas observaciones.
Construir un puente personalizado.
Revisar los contratos de proveedor.
Solucionar problemas con los comandos de rol.

Primeros pasos

Configurar

Integrar

Operar

Reportar eventos del jugador

Acciones de rol

Documento de identidad

Objetos

Eventos de estado simples

Observaciones del servidor

Valor de retorno

Comportamiento

Comportamiento de entrega

Siguiente

​Acciones de rol

​Documento de identidad

​Objetos

​Eventos de estado simples

​Observaciones del servidor

​Valor de retorno

​Comportamiento

​Comportamiento de entrega

​Siguiente

Acciones de rol

Documento de identidad

Objetos

Eventos de estado simples

Observaciones del servidor

Valor de retorno

Comportamiento

Comportamiento de entrega

Siguiente