Documentation développeur de Hou.la Connect

Ce que tu peux construire

• Un plugin de jeu : rendre un jeu pilotable par les packs, au moyen d'un mod, de RCON, d'un WebSocket ou d'une API HTTP.
• Une intégration avec un programme ou un appareil : un outil local, un logiciel de stream, un objet connecté, par HTTP, WebSocket, MQTT ou OSC.
• Un pack : des interactions prêtes à installer, à partager dans le Store.

1. 1

   Lance un serveur HTTP local

   Enregistre ce code dans server.js, puis lance node server.js. Le serveur écoute sur 127.0.0.1:7777, expose une route POST par action et répond 204 quand l'action a réussi. Si la variable TOKEN est définie, il exige l'en-tête Authorization: Bearer <TOKEN>.

   server.js JavaScriptCopier

   // server.js : node server.js
   const http = require('node:http')
   
   const TOKEN = process.env.TOKEN || ''
   const ROUTES = new Set(['/actions/soin', '/actions/ennemi'])
   
   http
       .createServer((req, res) => {
           if (TOKEN && req.headers.authorization !== `Bearer ${TOKEN}`) {
               return res.writeHead(401).end()
           }
           let body = ''
           req.on('data', (chunk) => (body += chunk))
           req.on('end', () => {
               if (req.method !== 'POST' || !ROUTES.has(req.url)) {
                   return res.writeHead(404).end()
               }
               console.log(req.method, req.url, body)
               res.writeHead(204).end()
           })
       })
       .listen(7777, '127.0.0.1', () => console.log('http://127.0.0.1:7777'))

2. 2

   Vérifie-le

   Dans un autre terminal, envoie la requête que Connect enverra pour l'action soin :

   Shell Copier

   curl -i -X POST http://127.0.0.1:7777/actions/soin

   Résultat attendu : HTTP/1.1 204 No Content, et le serveur affiche POST /actions/soin. Une route inconnue rend 404.

3. 3

   Importe le plugin

   Le fichier ci-dessous déclare deux actions : soin (POST /actions/soin) et ennemi (POST /actions/ennemi, avec un corps JSON). Dans Connect : « Mes plugins », « + Créer un plugin », « Un jeu », onglet « JSON », « Importer ». Termine avec « Ajouter mon jeu » : il s'installe sur ce PC, sans relecture.

   plugin-mode-http.json

   plugin-mode-http.json JSONCopier

   {
     "id": "mon-outil-compagnon",
     "nom": "Mon outil compagnon",
     "protocole": "jeu",
     "mode": "http",
     "description": "Exemple : un programme que le joueur lance à côté du jeu, et qui expose une API HTTP locale (son adresse se saisit dans « URL de base », par exemple http://127.0.0.1:7777).",
     "actions": [
       {
         "id": "soin",
         "libelle": {
           "fr": "Soins : trousse",
           "en": "Health: medipack"
         },
         "effet": "aide",
         "method": "POST",
         "path": "/actions/soin"
       },
       {
         "id": "ennemi",
         "libelle": {
           "fr": "Ennemi : au choix",
           "en": "Enemy: pick one"
         },
         "effet": "gene",
         "params": [
           {
             "id": "quoi",
             "type": "choix",
             "defaut": "loup",
             "libelle": {
               "fr": "Ennemi",
               "en": "Enemy"
             },
             "valeurs": [
               {
                 "id": "loup",
                 "libelle": {
                   "fr": "Loup",
                   "en": "Wolf"
                 }
               },
               {
                 "id": "ours",
                 "libelle": {
                   "fr": "Ours",
                   "en": "Bear"
                 }
               }
             ]
           }
         ],
         "method": "POST",
         "path": "/actions/ennemi",
         "json": {
           "type": "{param.quoi}",
           "de": "{sender.name}"
         }
       }
     ]
   }

   Télécharger ce fichier
4. 4

   Crée la connexion

   Dans « Mes plugins », carte « HTTP / API », « Configurer » : ajoute une connexion dont l'« URL de base » est http://127.0.0.1:7777. Le jeton est facultatif ; s'il est rempli, Connect l'envoie dans l'en-tête Authorization: Bearer …, ou dans l'en-tête nommé par la connexion. Quand un pack utilise ton plugin, Connect lui lie une connexion HTTP existante, ou ouvre ce formulaire s'il n'en trouve aucune.

5. 5

   Joue une action depuis un pack

   Dans le Lab, crée un pack et un écouteur (un cadeau, par exemple). Ajoute à sa chaîne un bloc « Dans le jeu », choisis « Mon outil compagnon », puis l'action « Soins : trousse ». Clique « Tester » : l'écouteur est joué tout de suite, sans live.

   Résultat attendu : le serveur affiche POST /actions/soin, et la notification du test indique l'action comme jouée. En cas d'échec, elle donne la cause : aucune réponse en 5 secondes, statut HTTP hors 2xx, ou aucune connexion liée au pack.

Étapes suivantes : ajoute des réglages à tes actions (Référence, « Format d'un plugin de jeu »), puis publie le plugin pour tous les streamers (Publication).

Déclencheurs

Un déclencheur est l'événement qui lance une interaction : cadeau Hou.la (dont les cadeaux personnalisés), follow, message ou commande du chat, likes et partages, spectateurs, sondage, roue, raccourci du streamer, événements d'overlay ou de boutique, et événements de TikTok, YouTube et Kick ("type": "platform"). Une interaction accepte jusqu'à 8 déclencheurs : n'importe lequel lance la chaîne. Chaque déclencheur remplit ses propres variables, comme {sender.name} ou {gift.quantity}.

Actions et chaînes

Une action est ce que Connect joue : un son, une requête OBS, un message de chat, une action de jeu… Connect connaît quinze types d'actions (effect.type), listés dans la référence. Un pack choisit dans cette liste ; un type inconnu fait refuser le pack.

Une interaction (rules[i]) relie ses déclencheurs à une chaîne de blocs (do) jouée dans l'ordre : actions, attentes, conditions, tirages au sort, répétitions, compteurs, variables. La durée d'une chaîne est calculée avant de la jouer : 30 secondes au plus.

Connexions et rôles

Une action qui joint un service (RCON, OBS, HTTP, WebSocket, MQTT…) passe par une connexion du streamer. Le pack la désigne par un rôle : par défaut le type de l'action (rcon, http…), ou connector pour en nommer un autre ; un plugin de jeu utilise le rôle jeu:<id>. À l'installation d'un pack, Connect lie chaque rôle à une connexion existante du bon type, ou demande d'en créer une.

Modes de liaison d'un plugin de jeu

Le mode dit comment Connect joint le jeu. Il fixe les champs de la connexion que le streamer remplit, et la forme de chaque action.

Cycle de vie : privé, en relecture, public

Un plugin et un pack passent par ces états.

1. PrivéAjouté avec « Ajouter mon jeu » : installé sur ton PC, utilisable dans tes packs, invisible des autres.
2. En relectureEnvoyé avec le premier pack publié dans le Store qui l'utilise : relu par Hou.la avant d'entrer dans le Store, en même temps que le pack. Le motif d'un refus de plugin s'affiche dans Connect.
3. PublicVisible dans le Store et installable par tous les streamers. Toute modification repasse en relecture.

Les trois façons de relier un jeu

Connect joint un jeu de l'une de trois façons, selon ce que le jeu offre déjà. Identifie la tienne avant d'écrire le plugin : elle fixe son mode, ce que tu écris, et ce que le streamer doit faire.

1. 1

   Le jeu a un serveur ou une API qui accepte des commandes

   RCON, console Telnet, WebSocket ou HTTP, comme Minecraft, Counter-Strike 2, Rust ou 7 Days to Die. Un plugin suffit, en mode rcon, telnet, rcon-evrima, ws ou http : chaque action devient une commande, un message ou une requête. Le streamer n'installe rien d'autre que le pack ; il saisit au plus l'adresse de son serveur dans la connexion.

2. 2

   Le jeu accepte les mods

   Écris le mod une fois, puis envoie son archive dans l'assistant, mode « Un mod dans le jeu ». Hou.la l'héberge. Chez chaque streamer qui installe un pack de ce jeu, Connect installe le mod automatiquement dans le dossier du jeu. Exemple : Pratfall.

3. 3

   Le jeu n'a ni l'un ni l'autre

   Crée-lui une porte d'entrée. La voie recommandée est un mod chargé par le jeu : même circuit qu'à la voie 2, rien à installer pour le streamer. À défaut, un programme externe qui expose une API locale, en mode http ou ws : le streamer doit le télécharger et le lancer lui-même, ce qui est plus contraignant.

Quelle voie pour mon jeu ?

Réponds aux questions dans l'ordre : la première réponse « oui » donne la voie.

Créer un plugin de jeu

Ce guide part du cas courant : écrire un pack pour un jeu que Connect ne connaît pas encore. Le plugin du jeu se trouve ou se crée depuis le pack, sans quitter le Lab. Un plugin de jeu est une fiche JSON : l'assistant de Connect l'écrit et la valide, et son onglet « JSON » importe et exporte le fichier.

1. 1

   Ouvre la liste des jeux depuis ton pack

   Dans le Lab, onglet « Informations », ouvre le champ « Jeu » de la fiche du pack (le bloc « Dans le jeu » propose la même liste). Si ton jeu n'y figure pas, choisis « Mon jeu n'est pas dans la liste », puis « Ajouter mon jeu » : l'assistant s'ouvre sans quitter le pack.

2. 2

   Installe un plugin existant, s'il y en a un

   Connect propose les plugins de la communauté pour les jeux qui ne sont pas encore installés sur ce PC. Un clic installe le plugin, mod compris, et le jeu est choisi dans le pack : passe à l'étape 8.

3. 3

   Sinon, ouvre l'assistant

   « Ajouter mon jeu » ouvre l'assistant sans quitter le pack (il s'ouvre aussi depuis « Mes plugins », « + Créer un plugin », « Un jeu »). Ses étapes : « Le jeu », « La liaison », « Les actions », « Le mod » (mode mod seulement), « Terminer ». Si ton mod est déjà connecté au pont, le jeu est proposé « en développement » et l'assistant reprend les actions qu'il annonce.

4. 4

   Le jeu

   Nom, identifiant (minuscules, chiffres et tirets, 2 à 40 caractères ; le même que dans le mod), numéro Steam et description. Le numéro Steam est facultatif, mais Connect en a besoin pour trouver le dossier où installer un mod. Dans la description, indique ce que le streamer doit installer ou lancer.

5. 5

   La liaison

   Choisis le mode selon ce que le jeu offre. Un serveur qui accepte RCON : rcon. Une console texte sur TCP : telnet. Le serveur de The Isle : rcon-evrima. Une API HTTP ou un WebSocket, du jeu ou d'un programme compagnon : http ou ws. Aucun des deux, mais un jeu modable : mod. Les champs de la connexion découlent du mode : le plugin ne les déclare pas.

6. 6

   Les actions

   Pour chacune : un nom (en français, et en anglais si tu le souhaites), une description, un effet (aide, gene ou neutre) et jusqu'à 8 réglages (un entier borné, ou un choix dans une liste). 60 actions au plus. En rcon, ws et http, écris le modèle de la commande, du message ou de la requête (Référence, « Format d'un plugin de jeu »).

7. 7

   Le mod (mode mod)

   Moteur, dossier d'installation relatif au dossier du jeu (3 niveaux au plus, sans ..), version (1.0.0), prérequis, puis l'archive .zip (100 Mo au plus). Hou.la l'héberge et en calcule l'empreinte. Le code du mod suit le guide « Écrire un mod qui parle au pont local ».

8. 8

   Ajoute ton jeu, puis teste

   Termine avec « Ajouter mon jeu » : le plugin s'installe sur ce PC, sans relecture. De retour dans le pack, le jeu est déjà choisi, et chaque bloc « Dans le jeu » ajouté le reprend : choisis une action et ses réglages, puis « Tester » joue l'écouteur tout de suite, sans live. Vérifie ainsi chaque action.

9. 9

   Publie ton pack, le plugin suit

   Publie le pack « dans le Store (public) » : le plugin part en relecture avec lui, sans autre geste. Le pack entre dans le Store une fois le plugin validé ; d'ici là, Connect affiche « Attend son jeu » (voir Publication).

Un exemple par mode

Chaque fichier passe le validateur de Hou.la. Importe-le dans l'assistant (onglet « JSON ») comme point de départ.

{
  "id": "mon-jeu-godot",
  "nom": "Mon jeu Godot",
  "protocole": "jeu",
  "mode": "mod",
  "description": "Exemple : un jeu Godot 4 .NET piloté par un mod qui se relie à Hou.la Connect.",
  "actions": [
    {
      "id": "ralenti",
      "libelle": {
        "fr": "Ralenti",
        "en": "Slow motion"
      },
      "description": {
        "fr": "Le jeu tourne au ralenti quelques secondes.",
        "en": "The game runs in slow motion for a few seconds."
      },
      "effet": "gene",
      "params": [
        {
          "id": "secondes",
          "type": "entier",
          "min": 1,
          "max": 10,
          "defaut": 3,
          "libelle": {
            "fr": "Durée (secondes)",
            "en": "Duration (seconds)"
          }
        }
      ]
    },
    {
      "id": "soigner",
      "libelle": {
        "fr": "Soigner",
        "en": "Heal"
      },
      "effet": "aide",
      "params": [
        {
          "id": "cible",
          "type": "choix",
          "defaut": "moi",
          "libelle": {
            "fr": "Qui",
            "en": "Who"
          },
          "valeurs": [
            {
              "id": "moi",
              "libelle": {
                "fr": "Le streamer",
                "en": "The streamer"
              }
            },
            {
              "id": "tous",
              "libelle": {
                "fr": "Tout le monde",
                "en": "Everyone"
              }
            }
          ]
        }
      ]
    }
  ],
  "mod": {
    "moteur": "godot",
    "dossier": "mods/MonMod",
    "version": "1.0.0",
    "prerequis": {
      "fr": "Aucun : le jeu charge les mods de son dossier mods.",
      "en": "None: the game loads mods from its mods folder."
    }
  }
}

{
  "id": "mon-serveur-rcon",
  "nom": "Mon serveur RCON",
  "protocole": "jeu",
  "mode": "rcon",
  "description": "Exemple : un jeu à serveur dédié qui accepte des commandes RCON.",
  "actions": [
    {
      "id": "gravite",
      "libelle": {
        "fr": "Changer la gravité",
        "en": "Change gravity"
      },
      "effet": "neutre",
      "params": [
        {
          "id": "valeur",
          "type": "entier",
          "min": 100,
          "max": 2000,
          "defaut": 200,
          "libelle": {
            "fr": "Gravité (800 = normale)",
            "en": "Gravity (800 = normal)"
          }
        }
      ],
      "commandes": [
        "sv_gravity {param.valeur}"
      ]
    },
    {
      "id": "annonce",
      "libelle": {
        "fr": "Annonce",
        "en": "Announcement"
      },
      "effet": "neutre",
      "commandes": [
        "say {sender.name} a offert {gift.name} !"
      ]
    }
  ]
}

{
  "id": "mon-jeu-websocket",
  "nom": "Mon jeu WebSocket",
  "protocole": "jeu",
  "mode": "ws",
  "description": "Exemple : un jeu qui écoute déjà un WebSocket sur ce PC (son adresse se saisit dans la connexion, par exemple ws://127.0.0.1:8123).",
  "actions": [
    {
      "id": "ennemis",
      "libelle": {
        "fr": "Faire apparaître des ennemis",
        "en": "Spawn enemies"
      },
      "effet": "gene",
      "params": [
        {
          "id": "nombre",
          "type": "entier",
          "min": 1,
          "max": 10,
          "defaut": 3,
          "libelle": {
            "fr": "Nombre",
            "en": "Count"
          }
        },
        {
          "id": "type",
          "type": "choix",
          "defaut": "petit",
          "libelle": {
            "fr": "Type",
            "en": "Type"
          },
          "valeurs": [
            {
              "id": "petit",
              "libelle": {
                "fr": "Petits",
                "en": "Small"
              },
              "valeur": "goblin"
            },
            {
              "id": "gros",
              "libelle": {
                "fr": "Gros",
                "en": "Big"
              },
              "valeur": "troll"
            }
          ]
        }
      ],
      "message": "{\"action\":\"spawn\",\"enemy\":\"{param.type}\",\"count\":{param.nombre},\"by\":\"{sender.name}\"}"
    }
  ]
}

{
  "id": "mon-outil-compagnon",
  "nom": "Mon outil compagnon",
  "protocole": "jeu",
  "mode": "http",
  "description": "Exemple : un programme que le joueur lance à côté du jeu, et qui expose une API HTTP locale (son adresse se saisit dans « URL de base », par exemple http://127.0.0.1:7777).",
  "actions": [
    {
      "id": "soin",
      "libelle": {
        "fr": "Soins : trousse",
        "en": "Health: medipack"
      },
      "effet": "aide",
      "method": "POST",
      "path": "/actions/soin"
    },
    {
      "id": "ennemi",
      "libelle": {
        "fr": "Ennemi : au choix",
        "en": "Enemy: pick one"
      },
      "effet": "gene",
      "params": [
        {
          "id": "quoi",
          "type": "choix",
          "defaut": "loup",
          "libelle": {
            "fr": "Ennemi",
            "en": "Enemy"
          },
          "valeurs": [
            {
              "id": "loup",
              "libelle": {
                "fr": "Loup",
                "en": "Wolf"
              }
            },
            {
              "id": "ours",
              "libelle": {
                "fr": "Ours",
                "en": "Bear"
              }
            }
          ]
        }
      ],
      "method": "POST",
      "path": "/actions/ennemi",
      "json": {
        "type": "{param.quoi}",
        "de": "{sender.name}"
      }
    }
  ]
}

Créer un mod

Un mod Hou.la est une archive .zip que Connect extrait dans le dossier du jeu. Connect n'exécute jamais son contenu : c'est le jeu qui le charge, par son propre système de mods ou par un chargeur comme BepInEx.

1. 1

   Relie le mod à Connect

   Une fois chargé par le jeu, le mod se connecte au pont local de Connect, un WebSocket ouvert sur le PC du streamer. Il annonce le jeu et ses actions, reçoit chaque action et répond. Le protocole est décrit dans le guide « Écrire un mod qui parle au pont local » et dans la référence « Protocole du pont ».

2. 2

   Prépare l'archive

   Place à la racine de l'archive ce qui doit se trouver dans le dossier d'installation, rangé comme le jeu l'attend : la racine de l'archive devient ce dossier. Un installateur ou un exécutable n'y sert à rien : aucun fichier de l'archive n'est lancé. Si le jeu a besoin d'un chargeur de mods, indique-le dans les prérequis du plugin : Connect les affiche à l'installation, sans les installer.

3. 3

   Choisis le dossier d'installation

   Un chemin relatif au dossier du jeu, par exemple mods/MonJeu ou BepInEx/plugins/MonJeu : 3 niveaux et 120 caractères au plus, chaque niveau fait de lettres non accentuées, de chiffres, de _, . et -, sans .. ni chemin absolu. Connect trouve le dossier du jeu par Steam, grâce au numéro Steam du plugin. Pour un jeu hors de Steam, Connect n'installe pas le mod : le streamer l'installe à la main, d'après la description du plugin.

4. 4

   Respecte les limites de l'archive

   Zip classique (ni zip64 ni chiffrement), fichiers stockés ou compressés en deflate. 100 Mo au plus, 250 Mo une fois décompressée, 500 entrées au plus. Chaque chemin est relatif, séparé par /, de 200 caractères au plus, sans .. ni antislash, et ne contient que des lettres non accentuées, des chiffres, des espaces et _ . ( ) + -. Aucun lien symbolique, aucun fichier en double. Une archive hors de ces règles est refusée dès l'envoi, avec la raison.

5. 5

   Installation et mises à jour

   Connect télécharge l'archive, vérifie son empreinte, contrôle chaque chemin, puis écrit chaque fichier à côté avant de le renommer : le jeu ne charge jamais un fichier à moitié écrit. Sous Windows, un jeu lancé verrouille souvent ses fichiers : Connect demande alors de fermer le jeu. Change la version du mod à chaque nouvelle archive : Connect compare la version installée à celle du plugin et met le mod à jour quand elles diffèrent.

6. 6

   La relecture

   « Ajouter mon jeu » installe le plugin sur ton PC seulement, pour tes tests. Publier un pack public qui l'utilise envoie le plugin et son mod en relecture : un mod est du code, il est toujours relu par une personne avant d'être proposé aux autres streamers. Chaque nouvelle version repasse en relecture.

À lire ensuite : Écrire un mod qui parle au pont local · Protocole du pont (mode mod)

Écrire un mod qui parle au pont local

En mode mod, le mod est le client et Connect le serveur : le jeu n'ouvre aucun port, et le mod se reconnecte quand Connect redémarre. Les messages sont du JSON texte sur un WebSocket local. Le détail de chaque message est dans la référence (« Protocole du pont »).

1. 1

   Lis le fichier d'appairage

   Au démarrage, Connect écrit ~/.houla/pont-jeu.json : { "v": 1, "port": 30212, "jeton": "<48 caractères hexadécimaux>" }. Le jeton change à chaque démarrage de Connect et le fichier est effacé à sa fermeture : relis-le avant chaque tentative de connexion.

2. 2

   Connecte-toi

   Ouvre ws://127.0.0.1:<port>/pont/v1 avec l'en-tête X-Houla-Pont: <jeton>, sans en-tête Origin.

3. 3

   Envoie bonjour dans les 5 secondes

   Envoie bonjour avec l'identifiant du jeu, la version du mod et ses actions. En version 2, chaque action est décrite (identifiant, libellé, réglages) et l'assistant s'en sert pour préremplir le plugin. Connect répond bienvenue.

4. 4

   Reçois les actions

   Chaque message action porte un id, l'identifiant de l'action, ses réglages et l'auteur (de : pseudo, quantité, nom du cadeau). Joue l'action dans le jeu.

5. 5

   Réponds dans les 5 secondes

   Renvoie fait avec le même id : "ok": true, ou "ok": false avec une raison (codes de refus dans la référence) et un detail facultatif. Sans réponse en 5 secondes, l'action échoue.

6. 6

   Teste avant d'avoir un plugin

   Un identifiant de jeu valide sans plugin est accepté et affiché « en développement » dans « Mes plugins » : crée ensuite le plugin depuis ce jeu. Une seconde connexion du même jeu remplace la première (code de fermeture 4004).

Piloter un programme externe ou un objet connecté

Connect ne lance aucun programme. Un programme externe (outil compagnon d'un jeu, logiciel de ton choix) tourne à côté de Connect et expose une API locale ; un plugin de jeu en mode http ou ws lui envoie les actions.

Un programme local avec une API

1. 1

   Expose une API locale

   Ton programme ouvre une API HTTP (ou un WebSocket) sur 127.0.0.1, à un port fixe. Une route par action : POST /actions/soin, POST /actions/ennemi… Réponds par un statut 2xx quand l'action a réussi. Délai maximal : 5 secondes en HTTP, 4 en WebSocket ; tout autre statut est affiché comme un échec dans le journal du live.

2. 2

   Publie un plugin en mode http

   Une action par route, avec ses réglages. Dans la description du plugin, indique où télécharger ton programme et quelle adresse saisir dans la connexion.

3. 3

   Le streamer installe ton programme

   Il le télécharge depuis ton site, le lance, puis saisit dans Connect l'« URL de base » (par exemple http://127.0.0.1:7777) et un jeton si ton programme en exige un.

4. 4

   Les packs utilisent tes actions

   Dans le Lab, le bloc « Dans le jeu » propose ton plugin et ses actions. Une adresse locale passe obligatoirement par une connexion : un pack ne peut pas écrire http://127.0.0.1 lui-même.

Un logiciel ou un objet connecté courant

Les plugins officiels génériques couvrent les protocoles courants : HTTP / API, WebSocket, MQTT (Zigbee2MQTT, Tasmota…), OSC (VRChat, TouchDesigner, Resolume), RCON, OBS et Streamlabs. D'autres sont prêts à l'emploi : Home Assistant, Elgato Key Light, Discord, Telegram, webhook. Un pack les utilise directement avec les actions http, ws, mqtt ou osc, par une connexion du streamer.

Écrire un pack

Le Lab écrit le JSON d'un pack à ta place ; les recettes ci-dessous montrent les constructions courantes. Chaque fichier passe le validateur de Hou.la et s'importe dans le Lab : onglet « Écouteurs », « JSON », « Importer un fichier… », puis « Vérifier mon pack ».

{
  "schema": 3,
  "rules": [
    {
      "id": "creeper",
      "label": "Creeper",
      "on": [
        {
          "type": "gift",
          "giftSlug": "ix_slot_01",
          "coinCost": 100,
          "group": "Pagaille"
        },
        {
          "type": "platform",
          "platform": "tiktok",
          "event": "gift",
          "min": 99
        },
        {
          "type": "platform",
          "platform": "youtube",
          "event": "superchat"
        },
        {
          "type": "platform",
          "platform": "kick",
          "event": "kicks",
          "min": 100
        },
        {
          "type": "platform",
          "platform": "twitch",
          "event": "bits",
          "min": 100
        }
      ],
      "do": [
        {
          "kind": "action",
          "id": "creeper",
          "effect": {
            "type": "jeu",
            "jeu": "minecraft",
            "action": "invoquer",
            "params": {
              "creature": "creeper",
              "position": "devant_3",
              "qui": "joueur"
            }
          }
        }
      ]
    }
  ]
}

{
  "schema": 3,
  "rules": [
    {
      "id": "paliers-likes",
      "label": "Paliers de likes",
      "on": [
        {
          "type": "hearts",
          "milestones": [
            1000,
            5000,
            10000
          ]
        },
        {
          "type": "platform",
          "platform": "tiktok",
          "event": "like_total",
          "milestones": [
            1000,
            5000,
            10000
          ]
        }
      ],
      "do": [
        {
          "kind": "switch",
          "id": "selon-palier",
          "conditions": [
            {
              "all": [
                {
                  "left": "hearts.palier",
                  "op": ">=",
                  "right": 10000
                }
              ]
            },
            {
              "all": [
                {
                  "left": "hearts.palier",
                  "op": ">=",
                  "right": 5000
                }
              ]
            }
          ],
          "branches": [
            [
              {
                "kind": "repeat",
                "id": "trois-fanfares",
                "times": 3,
                "gapMs": 1500,
                "branches": [
                  [
                    {
                      "kind": "action",
                      "id": "fanfare",
                      "effect": {
                        "type": "sound",
                        "soundId": "34f7bfb4-b51f-11f1-a1b0-920007989f15",
                        "volume": 0.8
                      }
                    }
                  ]
                ]
              }
            ],
            [
              {
                "kind": "action",
                "id": "wow",
                "effect": {
                  "type": "sound",
                  "soundId": "2ebf44c5-b51a-11f1-a1b0-920007989f15"
                }
              }
            ]
          ],
          "else": [
            {
              "kind": "action",
              "id": "merci",
              "effect": {
                "type": "chat",
                "text": "{hearts.palier} likes, merci à tous !",
                "cooldownMs": 10000
              }
            }
          ]
        }
      ]
    },
    {
      "id": "paliers-partages",
      "label": "Paliers de partages",
      "on": {
        "type": "share_total",
        "milestones": [
          10,
          50,
          100
        ]
      },
      "do": [
        {
          "kind": "action",
          "id": "voix",
          "effect": {
            "type": "tts",
            "text": "{shares.total} partages, merci !"
          }
        }
      ]
    },
    {
      "id": "selon-montant",
      "label": "Selon le montant du cadeau",
      "on": {
        "type": "gift",
        "minCoins": 1
      },
      "do": [
        {
          "kind": "switch",
          "id": "selon-pieces",
          "conditions": [
            {
              "all": [
                {
                  "left": "coins",
                  "op": ">=",
                  "right": 500
                }
              ]
            },
            {
              "all": [
                {
                  "left": "coins",
                  "op": ">=",
                  "right": 100
                }
              ]
            }
          ],
          "branches": [
            [
              {
                "kind": "action",
                "id": "gros",
                "effect": {
                  "type": "sound",
                  "soundId": "34f7bfb4-b51f-11f1-a1b0-920007989f15"
                }
              }
            ],
            [
              {
                "kind": "repeat",
                "id": "klaxons",
                "times": 1,
                "gapMs": 600,
                "cases": [
                  {
                    "when": {
                      "all": [
                        {
                          "left": "quantity",
                          "op": ">=",
                          "right": 5
                        }
                      ]
                    },
                    "times": 5
                  }
                ],
                "branches": [
                  [
                    {
                      "kind": "action",
                      "id": "klaxon",
                      "effect": {
                        "type": "sound",
                        "soundId": "301b847c-b529-11f1-a1b0-920007989f15"
                      }
                    }
                  ]
                ]
              }
            ]
          ],
          "else": [
            {
              "kind": "action",
              "id": "petit",
              "effect": {
                "type": "chat",
                "text": "Merci {sender.name} pour {gift.name} !",
                "cooldownMs": 5000
              }
            }
          ]
        }
      ]
    }
  ]
}

{
  "schema": 3,
  "rules": [
    {
      "id": "commande-klaxon",
      "label": "Klaxon",
      "on": {
        "type": "command",
        "name": "klaxon",
        "description": "Joue un klaxon au hasard",
        "perViewerMs": 30000
      },
      "enchainement": "ignorer",
      "do": [
        {
          "kind": "random",
          "id": "tirage",
          "weights": [
            70,
            30
          ],
          "branches": [
            [
              {
                "kind": "action",
                "id": "police",
                "effect": {
                  "type": "sound",
                  "soundId": "051db1d2-b523-11f1-a1b0-920007989f15",
                  "maxMs": 3000
                }
              }
            ],
            [
              {
                "kind": "action",
                "id": "dj",
                "effect": {
                  "type": "sound",
                  "soundId": "301b847c-b529-11f1-a1b0-920007989f15"
                }
              }
            ]
          ]
        }
      ]
    },
    {
      "id": "commande-dis",
      "label": "Dis-le à voix haute",
      "on": {
        "type": "command",
        "name": "dis",
        "description": "Le streamer lit ton message à voix haute",
        "coinCost": 10,
        "args": "texte",
        "who": "tous"
      },
      "do": [
        {
          "kind": "action",
          "id": "lire",
          "effect": {
            "type": "tts",
            "text": "{sender.name} dit : {commande.texte}"
          }
        }
      ]
    },
    {
      "id": "mot-gg",
      "label": "GG dans le chat",
      "on": {
        "type": "comment",
        "startsWith": "!gg",
        "platforms": [
          "houla",
          "tiktok",
          "youtube",
          "kick"
        ]
      },
      "enchainement": "ignorer",
      "do": [
        {
          "kind": "action",
          "id": "roulement",
          "effect": {
            "type": "sound",
            "soundId": "5703a3d3-b522-11f1-a1b0-920007989f15",
            "volume": 0.6
          }
        }
      ]
    }
  ]
}

{
  "schema": 3,
  "rules": [
    {
      "id": "bombes",
      "label": "Pluie de bombes",
      "on": {
        "type": "gift",
        "giftSlug": "ix_slot_01",
        "coinCost": 30,
        "group": "Pagaille"
      },
      "do": [
        {
          "kind": "action",
          "id": "bombes",
          "effect": {
            "type": "jeu",
            "jeu": "pratfall",
            "action": "bombes",
            "params": {
              "nombre": 3,
              "cible": "hasard"
            }
          }
        }
      ]
    },
    {
      "id": "soins",
      "label": "Soins",
      "on": {
        "type": "gift",
        "giftSlug": "ix_slot_02",
        "coinCost": 45,
        "group": "Coup de main"
      },
      "do": [
        {
          "kind": "action",
          "id": "soigner",
          "effect": {
            "type": "jeu",
            "jeu": "pratfall",
            "action": "soigner",
            "params": {}
          }
        }
      ]
    },
    {
      "id": "klaxon",
      "label": "Klaxon",
      "on": {
        "type": "gift",
        "giftSlug": "ix_slot_03",
        "coinCost": 5,
        "group": "Ambiance"
      },
      "do": [
        {
          "kind": "action",
          "id": "klaxon",
          "effect": {
            "type": "jeu",
            "jeu": "pratfall",
            "action": "klaxon",
            "params": {}
          }
        }
      ]
    },
    {
      "id": "resurrection",
      "label": "Résurrection",
      "on": {
        "type": "gift",
        "giftSlug": "ix_slot_04",
        "coinCost": 280,
        "group": "Coup de main"
      },
      "do": [
        {
          "kind": "action",
          "id": "ressusciter",
          "effect": {
            "type": "jeu",
            "jeu": "pratfall",
            "action": "ressusciter",
            "params": {
              "cible": "hasard"
            }
          }
        }
      ]
    }
  ]
}

{
  "schema": 3,
  "rules": [
    {
      "id": "trousse",
      "label": "Trousse de soins",
      "on": [
        {
          "type": "gift",
          "giftSlug": "ix_slot_01",
          "coinCost": 20,
          "group": "Coup de main"
        },
        {
          "type": "platform",
          "platform": "tiktok",
          "event": "gift",
          "giftId": "5655"
        }
      ],
      "do": [
        {
          "kind": "action",
          "id": "trousse",
          "effect": {
            "type": "jeu",
            "jeu": "tomb-raider-remastered",
            "action": "small_medkit",
            "params": {}
          }
        }
      ]
    },
    {
      "id": "trex",
      "label": "T-Rex",
      "on": {
        "type": "gift",
        "giftSlug": "ix_slot_02",
        "coinCost": 490,
        "group": "Pagaille"
      },
      "do": [
        {
          "kind": "action",
          "id": "annonce",
          "effect": {
            "type": "chat",
            "text": "{sender.name} lâche un T-Rex sur Lara !",
            "cooldownMs": 5000
          }
        },
        {
          "kind": "action",
          "id": "trex",
          "effect": {
            "type": "jeu",
            "jeu": "tomb-raider-remastered",
            "action": "trex",
            "params": {}
          }
        }
      ]
    }
  ]
}

Générer un pack avec une IA

1. Donne à l'IA le fichier guide-ia.md du kit et l'adresse de cette page, puis décris le pack : ce que les spectateurs déclenchent, et ce qui se passe.
2. Si le pack joue des sons, ajoute la liste des sons : dans Connect, « Sons », « Exporter la liste… » (ou « Liste des sons… » dans le Lab).
3. L'IA rend un fichier JSON. Dans le Lab : onglet « Écouteurs », « JSON », « Importer un fichier… », puis « Vérifier mon pack ».
4. Règle ensuite dans le Lab ce qu'une IA ne peut pas connaître : l'icône d'un cadeau personnalisé, les overlays du streamer, les connexions.

Format d'un plugin de jeu

Un libellé est une chaîne, ou un objet { "fr": "…", "en": "…" }.

Variables d'un modèle

{param.<réglage>} : la valeur d'un réglage de l'action. {player} et les autres champs non secrets de la connexion ; un mot de passe ou un jeton n'est jamais inséré dans un modèle. Les données de l'événement : {sender.name} (le pseudo du spectateur), {gift.name}, {gift.quantity}… Chaque valeur est échappée selon sa destination (adresse, JSON, texte).

Format d'un pack (schéma 3)

Un pack est un objet JSON. Squelette minimal :

{ "schema": 3, "rules": [ { "id": "…", "label": "…", "on": [ … ], "do": [ … ] } ] }

Clés du pack

Clés d'une interaction (rules[i])

Déclencheurs (on)

Chaque déclencheur a un type et ses propres réglages (seuil, palier, cadeau précis…). Les variables qu'il remplit et ses réglages exacts sont listés dans guide-ia.md.

Blocs d'une chaîne (do)

Chaque bloc a un kind et un id unique dans son interaction (lettres, chiffres, -, _, 24 caractères au plus).

Conditions

{ "all": [ … ] } (toutes vraies) ou { "any": [ … ] } (une suffit), 3 clauses au plus. Une clause compare left à une valeur écrite (right, jamais une variable) avec ==, !=, <, <=, >, >= ou contains. left : le montant (coins), la quantité, le message, le palier de likes (hearts.palier), le montant d'une autre plateforme (platform.amount), un tirage de 0 à 99 (random), un compteur, une variable…

{ "all": [ { "left": "coins", "op": ">=", "right": 100 } ] }

Variables dans les textes

Dans un texte (chat.text, tts.text, rcon.command…), {sender.name}, {gift.name}, {hearts.palier}, {commande.texte}… sont remplacées au moment de jouer. Seules les variables remplies par un déclencheur de l'interaction ont une valeur ; une variable inconnue fait refuser le pack. Une variable n'est jamais admise dans un identifiant (son, overlay, réglage de jeu, scène).

Bornes

48 blocs par interaction et 1200 par pack, 6 niveaux d'imbrication, 30 s de durée calculée par chaîne, 50 tours pour un repeat, 10 s par attente.

Protocole du pont (mode mod)

Un WebSocket local, des messages JSON texte. Versions acceptées : 1 et 2.

Messages

{ "t": "bonjour", "v": 2, "jeu": "mon-jeu", "versionMod": "1.0.0", "actions": [ … ] }

{ "t": "bienvenue", "v": 2 }

{ "t": "action", "id": "a7", "action": "ralenti", "params": { "secondes": 3 }, "de": { "pseudo": "Lina", "quantite": 1, "cadeau": "Rose" } }

{ "t": "fait", "id": "a7", "ok": true }

{ "t": "evenement", "nom": "joueur_mort", "donnees": { "niveau": 3 } }

Codes de refus (raison)

Codes de fermeture

Garanties du serveur

• Il n'écoute que sur 127.0.0.1.
• Le jeton est exigé et comparé en temps constant ; absent ou faux, la connexion est refusée (401).
• Tout en-tête Origin est refusé (403) : une page web ouverte sur le PC ne peut pas se faire passer pour un jeu.
• L'en-tête Host doit nommer 127.0.0.1 ou localhost, ce qui bloque le DNS rebinding.
• Un message fait 64 Ko au plus. Une action ne part que si un plugin la déclare, avec des réglages validés.

Types d'actions (effect)

Le champ type d'un effect choisit l'exécuteur. Les champs exacts et leurs valeurs admises sont dans guide-ia.md.

Plugins de jeu officiels

Livrés avec Connect, au même format que les plugins de la communauté. Utilise-les dans tes packs, ou lis-les comme exemples.

Extraits

Un plugin officiel par mode représenté : l'en-tête et les deux premières actions, tels que Connect les charge.

{
  "id": "pratfall",
  "nom": "Pratfall",
  "protocole": "jeu",
  "mode": "mod",
  "jeu": {
    "steamAppId": 4244510
  },
  "actions": [
    {
      "id": "bombes",
      "libelle": {
        "fr": "Pluie de bombes",
        "en": "Bomb rain",
        "it": "Pioggia di bombe",
        "es": "Lluvia de bombas",
        "pt": "Chuva de bombas"
      },
      "effet": "gene",
      "params": [
        {
          "id": "nombre",
          "type": "entier",
          "libelle": {
            "fr": "Nombre de bombes",
            "en": "Number of bombs",
            "it": "Numero di bombe",
            "es": "Número de bombas",
            "pt": "Número de bombas"
          },
          "min": 1,
          "max": 5,
          "defaut": 3
        },
        {
          "id": "cible",
          "type": "choix",
          "libelle": {
            "fr": "Qui",
            "en": "Who",
            "it": "Chi",
            "es": "Quién",
            "pt": "Quem"
          },
          "defaut": "moi",
          "valeurs": [
            {
              "id": "moi",
              "libelle": {
                "fr": "Toi",
                "en": "You",
                "it": "Tu",
                "es": "Tú",
                "pt": "Você"
              }
            },
            {
              "id": "hasard",
              "libelle": {
                "fr": "Un joueur au hasard",
                "en": "A random player",
                "it": "Un giocatore a caso",
                "es": "Un jugador al azar",
                "pt": "Um jogador aleatório"
              }
            }
          ]
        }
      ]
    },
    {
      "id": "mine",
      "libelle": {
        "fr": "Mine foreuse",
        "en": "Digging mine",
        "it": "Mina scavatrice",
        "es": "Mina excavadora",
        "pt": "Mina escavadora"
      },
      "effet": "gene",
      "params": [
        {
          "id": "cible",
          "type": "choix",
          "libelle": {
            "fr": "Qui",
            "en": "Who",
            "it": "Chi",
            "es": "Quién",
            "pt": "Quem"
          },
          "defaut": "moi",
          "valeurs": [
            {
              "id": "moi",
              "libelle": {
                "fr": "Toi",
                "en": "You",
                "it": "Tu",
                "es": "Tú",
                "pt": "Você"
              }
            },
            {
              "id": "hasard",
              "libelle": {
                "fr": "Un joueur au hasard",
                "en": "A random player",
                "it": "Un giocatore a caso",
                "es": "Un jugador al azar",
                "pt": "Um jogador aleatório"
              }
            }
          ]
        }
      ]
    }
  ]
}

{
  "id": "counter-strike-2",
  "nom": "Counter-Strike 2",
  "protocole": "jeu",
  "mode": "rcon",
  "jeu": {
    "steamAppId": 730,
    "alias": [
      "CS2",
      "Counter Strike 2",
      "CS"
    ],
    "moteur": "source"
  },
  "actions": [
    {
      "id": "gravite",
      "libelle": {
        "fr": "Changer la gravité (triche)",
        "en": "Change gravity (cheat)",
        "it": "Cambia la gravità (trucco)",
        "es": "Cambiar la gravedad (truco)",
        "pt": "Mudar a gravidade (trapaça)"
      },
      "effet": "neutre",
      "params": [
        {
          "id": "gravite",
          "type": "entier",
          "libelle": {
            "fr": "Gravité (800 = normale)",
            "en": "Gravity (800 = normal)",
            "it": "Gravità (800 = normale)",
            "es": "Gravedad (800 = normal)",
            "pt": "Gravidade (800 = normal)"
          },
          "min": 100,
          "max": 2000,
          "defaut": 200
        }
      ],
      "commandes": [
        "sv_gravity {param.gravite}"
      ]
    },
    {
      "id": "bunny_hop",
      "libelle": {
        "fr": "Bunny hop",
        "en": "Bunny hop",
        "it": "Bunny hop",
        "es": "Bunny hop",
        "pt": "Bunny hop"
      },
      "effet": "aide",
      "params": [
        {
          "id": "etat",
          "type": "choix",
          "libelle": {
            "fr": "État",
            "en": "State",
            "it": "Stato",
            "es": "Estado",
            "pt": "Estado"
          },
          "defaut": "oui",
          "valeurs": [
            {
              "id": "oui",
              "libelle": {
                "fr": "Activé",
                "en": "On",
                "it": "Attivo",
                "es": "Activado",
                "pt": "Ativado"
              },
              "valeur": "1"
            },
            {
              "id": "non",
              "libelle": {
                "fr": "Désactivé",
                "en": "Off",
                "it": "Disattivo",
                "es": "Desactivado",
                "pt": "Desativado"
              },
              "valeur": "0"
            }
          ]
        }
      ],
      "commandes": [
        "sv_enablebunnyhopping {param.etat}",
        "sv_autobunnyhopping {param.etat}"
      ]
    }
  ]
}

{
  "id": "tomb-raider-remastered",
  "nom": "Tomb Raider I Remastered (TRR Director)",
  "protocole": "jeu",
  "mode": "http",
  "jeu": {
    "steamAppId": 2478970,
    "alias": [
      "TRR",
      "Tomb Raider Remastered",
      "Tomb Raider 1",
      "Tomb Raider I",
      "Tomb Raider 1 Remastered",
      "TRR Director"
    ],
    "moteur": "autre"
  },
  "actions": [
    {
      "id": "small_medkit",
      "libelle": {
        "fr": "Soins : petite trousse de soins",
        "en": "Health: small medipack",
        "it": "Cure: medikit piccolo",
        "es": "Curación: botiquín pequeño",
        "pt": "Cura: kit médico pequeno"
      },
      "effet": "aide",
      "method": "POST",
      "path": "/small_medkit",
      "json": {
        "provider": "houla",
        "viewer": "{sender.name}"
      }
    },
    {
      "id": "large_medkit",
      "libelle": {
        "fr": "Soins : grande trousse de soins",
        "en": "Health: large medipack",
        "it": "Cure: medikit grande",
        "es": "Curación: botiquín grande",
        "pt": "Cura: kit médico grande"
      },
      "effet": "aide",
      "method": "POST",
      "path": "/large_medkit",
      "json": {
        "provider": "houla",
        "viewer": "{sender.name}"
      }
    }
  ]
}

Interdit à un pack, un plugin ou un mod

• Lancer un exécutable ou un script. Aucun pack, plugin ou mod ne peut lancer un programme : aucun champ ne désigne un fichier à exécuter. Pour piloter un programme externe, utilise le mode http ou ws vers une API locale exposée par ce programme.
• Viser ce PC ou le réseau local par une adresse écrite dans le pack (127.0.0.1, 192.168.…, localhost, ou un nom qui y mène). Seule une connexion saisie par le streamer, ou un hôte qu'il a approuvé, y accède.
• Envoyer un jeton ou un mot de passe ailleurs que vers la connexion du streamer, ou suivre une redirection depuis une adresse écrite dans le pack.
• Insérer un champ secret d'une connexion (mot de passe, jeton, webhook) dans une commande ou une requête.
• Jouer une commande RCON destructrice : stop, restart, op, ban, kick, whitelist, save-off, gamemode…
• Utiliser le clavier, la manette ou le pilote bas niveau sans que le streamer les ait activés : ils sont désactivés par défaut.
• Démarrer ou couper le stream depuis OBS ou Streamlabs.
• Envoyer à un jeu une action ou un réglage que son plugin ne déclare pas, ou mettre une variable venue du chat dans un réglage.
• Porter une clé inconnue : chaque objet est reconstruit depuis une liste fermée, et une clé en trop fait refuser le fichier.
• Faire exécuter un mod par Connect. Connect vérifie l'empreinte de l'archive, contrôle son contenu (aucun chemin hors du dossier, aucun lien symbolique) et l'extrait dans le dossier du jeu ; c'est le jeu qui charge le mod.

Limites actuelles

• Plugin ajouté avec « Ajouter mon jeu » : utilisable tout de suite sur ton PC, dans tes packs, invisible des autres. Rendu public avec le premier pack public qui l'utilise : relu par Hou.la avant d'entrer dans le Store ; chaque modification repasse en relecture. Un plugin avec un mod est toujours relu par une personne.
• Un pack public attend ses plugins : publier dans le Store un pack qui utilise un plugin de jeu privé envoie ce plugin en relecture. Le pack est relu de son côté, et n'est proposé dans le Store qu'une fois tous ses plugins approuvés. Un plugin refusé ou un mod sans archive bloque l'envoi (PLUGIN_JEU_A_CORRIGER), avec le motif.
• Un pack public est relu : l'analyse automatique peut seulement refuser, une personne approuve. Un pack approuvé est signé, et Connect vérifie sa signature.
• Installer un pack installe ses plugins : la liste se calcule depuis ses actions de jeu, sans rien à déclarer. Le mod d'un plugin s'installe avec lui.
• Commission : le créateur d'un pack peut fixer la sienne, de 0 à 15 %.

Télécharger le kit (291 Ko)

• guide-ia.md : la référence complète du format de pack : variables de chaque déclencheur, échelle des prix, bornes, et actions de chaque plugin de jeu officiel. Le même fichier que le bouton « Guide pour une IA… » du Lab.
• packs/ : les cinq packs d'exemple des guides.
• plugins/ : un plugin de jeu par mode.
• visuels/gabarit-banniere-1600x900.jpg, visuels/prompt-banniere.md : le gabarit de la bannière d'un pack (1600 x 900) et le prompt associé, pour une IA d'images. Icônes de cadeaux : 512 x 512, PNG transparent.