> ## 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. # Signaler les événements joueur > Traduisez les événements roleplay du serveur en observations comprises par les PNJ IA. Utilisez l'export serveur lorsqu'une action de jeu se produit en dehors de Humalike mais que les PNJ à proximité doivent l'observer : ```lua theme={null} local accepted = exports.humalike:ReportPlayerEvent(playerId, event) ``` Il renvoie `true` après validation locale et mise en file d'attente. Il renvoie `false` pour un joueur invalide, un personnage non chargé ou un événement mal formé. ## Actions roleplay ```lua theme={null} exports.humalike:ReportPlayerEvent(source, { type = 'rp_action', kind = 'me', text = 'places the envelope on the table', }) ``` `kind` vaut `me` ou `do`. Le texte est débarrassé des espaces en début et fin, ne doit contenir aucun caractère de contrôle et est limité à 1 000 caractères Unicode. Signalez depuis le gestionnaire serveur après que votre ressource `/me` ou `/do` a accepté la commande. Ne laissez pas un client soumettre directement une narration. ## Document d'identité ```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', }) ``` Les cinq champs sont des chaînes requises, débarrassées des espaces en début et fin et limitées à 128 caractères Unicode sans caractères de contrôle. ## Objets ```lua theme={null} exports.humalike:ReportPlayerEvent(source, { type = 'item_dropped', item_name = 'water', quantity = 2, }) ``` Les types pris en charge sont `item_dropped` et `item_picked_up`. `item_name` peut contenir des lettres, des chiffres, `_`, `.` et `-`, avec un maximum de 100 caractères. `quantity` doit être un entier positif. Utilisez le nom interne de l'objet dans le framework. La description en langage naturel du PNJ provient du contexte environnant et des connaissances du personnage. ## Événements d'état simples Ces événements ne contiennent que `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 observe automatiquement le state bag joueur `HandsUp`. Ne signalez vous-même les événements de mains que si le serveur utilise un autre mécanisme d'état faisant autorité. ## Observations serveur Les événements joueur forment un vocabulaire fixe. Pour les faits que seul votre serveur connaît, déclarez vos propres observations sur le fournisseur d'actions (`Namespace` + `Observations`, voir le [descripteur d'actions](/fr/ai-npc/integrations/provider-api#descripteur-dactions)) et signalez chaque occurrence : ```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 | Type | Description | | ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------- | | `npcId` | string | Un PNJ du registre (statique, ou externe et lié) ou un corps ambiant actuellement sous bail de votre serveur. | | `playerId` | number | Le joueur concerné par le fait. Le PNJ s'en souvient comme d'une action de ce personnage. | | `key` | string | Une clé d'observation déclarée, sans l'espace de noms (`item_given`, pas `myserver:item_given`). | | `fields` | table | Chaque champ déclaré, exactement typé, et rien d'autre. | | `options` | table, facultatif | `{ react = false }` enregistre le fait sans réaction parlée. Par défaut, `react = true`. | Les valeurs des champs sont vérifiées à chaque signalement : * Les valeurs `string` comportent au plus 64 caractères sans caractères de contrôle. * Les valeurs `integer` sont entières. * Les valeurs `integer` et `number` sont finies et d'une magnitude d'au plus 2^53. La ressource rend le modèle de texte déclaré pour la langue du PNJ, en se repliant sur l'anglais, puis sur la première langue déclarée, et envoie cette ligne telle quelle. Seules la ligne rendue et les valeurs vérifiées quittent le serveur. Une ligne rendue comporte au plus 912 caractères ; `RegisterProvider` refuse un modèle de texte dont le rendu dans le pire des cas dépasserait cette limite. ### Valeur de retour ```lua theme={null} { ok = true, value = { key = 'myserver:item_given', text = '...' } } { ok = false, error = 'unknown_observation' } ``` | Erreur | Signification | | ---------------------- | ---------------------------------------------------------------------- | | `invalid_player` | `playerId` n'est pas un joueur connecté. | | `character_not_loaded` | Le fournisseur joueur ne signale aucun personnage chargé. | | `npc_not_found` | `npcId` n'est ni un PNJ du registre ni un corps ambiant sous bail. | | `npc_not_bound` | Le PNJ externe n'a aucun ped lié et apparu. | | `unknown_observation` | `key` n'est pas déclarée sur le fournisseur d'actions. | | `invalid_fields` | `fields` n'est pas une table. | | `invalid_field:` | Un champ déclaré est manquant, ou son type ou sa taille est incorrect. | | `unknown_field:` | `fields` contient une clé non déclarée. | | `invalid_options` | `options` n'est pas une table ou `react` n'est pas un booléen. | | `text_too_long` | La ligne rendue dépasse 912 caractères. | Les erreurs de déclaration sont signalées par `RegisterProvider` lui-même. ### Comportement Une observation signalée est un fait serveur, elle diffère donc d'un événement joueur : * Elle n'est pas conditionnée à la portée d'écoute. * Elle est enregistrée et, avec `react = true`, prononcée même lorsqu'un script détient `perception` sur le PNJ. Détenez `speech` pour garder le PNJ silencieux. * Une répétition de la même clé dans un délai d'environ 2,5 secondes est enregistrée mais n'est pas prononcée à nouveau. Avec `humalike_developer_tools 1`, signalez-en une à la main pendant que vous câblez le vrai hook : ```text theme={null} /humalike_dev observe [field=value ...] ``` ## Comportement de livraison L'export confirme l'acceptation locale, pas qu'un PNJ répondra. L'événement est livré avec la session courante du joueur et le contexte du monde. Les PNJ peuvent l'observer, s'en souvenir, réagir silencieusement ou parler selon le personnage et l'état de la conversation. ## Suite * [Déclarer des actions définies par le serveur](/fr/ai-npc/integrations/custom-actions) conditionnées à ces observations. * [Construire un pont personnalisé](/fr/ai-npc/integrations/custom-bridge). * [Revoir les contrats des fournisseurs](/fr/ai-npc/integrations/provider-api). * [Dépanner les commandes roleplay](/fr/ai-npc/operations#me-ou-do-est-ignoré).