🧩 Créer un module

🌱 Par où commencer si tu débarques

Pas de panique. Tu n'as pas besoin d'être informaticien·ne pour créer un module OpenOverlay. Un module c'est simplement un petit programme qui dit à ton overlay quoi faire quand quelque chose se passe sur ta chaîne. Et ce "petit programme", ça ressemble à des instructions écrites en anglais simplifié — pas si différent d'une recette de cuisine.

Ce dont tu as besoin

🗺️ Les concepts clés

Avant de plonger dans le code, voici comment fonctionne OpenOverlay en quelques mots.

L'overlay et l'admin : deux mondes séparés

OpenOverlay tourne sur deux pages différentes en même temps dans ton navigateur. La page overlay est celle que tu captures dans OBS — c'est ton stream. La page admin est le tableau de bord où tu configures tout. Ces deux pages communiquent ensemble en temps réel.

Un module, c'est quoi concrètement ?

Un module est un dossier avec 4 fichiers minimum. Chaque fichier a un rôle précis :

• manifest.json — la carte d'identité du module. Son nom, sa description, ses réglages par défaut. Pas de code ici, juste des données.
• overlay.html — ce que tu veux afficher sur le stream. Comme construire une maison vide que tu vas ensuite meubler avec le code.
• overlay.js — le code qui s'exécute sur le stream. C'est lui qui "écoute" les événements Twitch et anime l'overlay.
• admin.js — le code qui construit l'interface de configuration dans le tableau de bord.

Les "hooks" : brancher sur ce qui se passe

Un hook, c'est une fonction que tu déclares une fois, et OpenOverlay l'appelle automatiquement quand quelque chose se passe. C'est comme brancher une prise — tu prépares le câble, et l'électricité coule quand il y en a.

📁 Structure d'un module

Un module est un dossier dans mods/. Son nom de dossier correspond à son identifiant unique.

manifest.json — la carte d'identité

{
  "id":          "mon-module",
  "name":        "Mon Module",
  "description": "Ce que fait mon module en une phrase",
  "icon":        "✨",
  "configKey":   "mon_module",
  "defaultConfig": {
    "enabled": true,
    "message": "Bonjour !",
    "volume":  1.0
  },
  "version": "1.0.0",
  "author":  "TonPseudo",
  "files": ["manifest.json", "overlay.js", "overlay.html", "admin.js"]
}

🎬 Module overlay (overlay.js)

C'est le cœur de ton module — le code qui tourne sur la page stream et qui réagit à ce qui se passe sur Twitch. Tu déclares ton module avec OverlayMods.register() en lui passant un objet qui contient toutes tes réponses aux événements.

OverlayMods.register({
  id: 'mon-module',

  // Appelé une fois au démarrage
  init(api) { },

  // Appelé quand le streamer sauvegarde ses réglages
  onConfigReload(api) { },

  // Appelé à chaque événement Twitch (follow, sub, raid…)
  onTwitchEvent(type, event, api) { },

  // Appelé quand un message commence par ! dans le chat
  onChatCommand(cmd, args, api, sender) { },

  // Appelé quand un viewer envoie son premier message
  onFirstChatter(username, isFirstEver, api) { },

  // Appelé quand l'admin envoie un message à l'overlay
  onAdminMessage(data, api) { },
});

Hooks d'événements — le détail

init(api)

Appelé une seule fois, après que tout est chargé et connecté. C'est le bon endroit pour démarrer un timer, écouter des événements DOM, ou initialiser des variables d'état.

onConfigReload(api)

Déclenché quand le streamer clique sur "Sauvegarder" dans le dashboard. Utilise ce hook pour relire la configuration et adapter l'overlay sans tout recharger.

onTwitchEvent(type, event, api)

C'est l'événement le plus important. Il est appelé pour chaque notification Twitch : un follow, un sub, un raid, des bits, un échange de points de chaîne… Le paramètre type est une chaîne de caractères qui dit quel événement c'est. Le paramètre event est l'objet avec toutes les données.

onTwitchEvent(type, event, api) {
  if (api.config.mon_module?.enabled === false) return;
  if (type !== 'channel.follow') return;
  console.log('Nouveau follow de', event.user_name);
},

onChatCommand(cmd, args, api, sender)

Appelé pour chaque message du chat qui commence par !. cmd est la commande en minuscules (ex : '!salut'), args est un tableau avec les mots qui suivent. sender décrit qui a envoyé le message.

onFirstChatter(username, isFirstEver, api)

Déclenché quand un viewer envoie un message pour la première fois. isFirstEver est true si c'est son tout premier message depuis la création de la chaîne.

onAdminMessage(data, api)

Appelé quand l'admin envoie quelque chose à l'overlay via tools.sendToOverlay(). Utilise data.type pour distinguer tes différents messages.

L'objet api

overlay.html — construire la scène

Ce fichier est inséré dans la page stream au chargement. Il contient les éléments HTML que ton module va animer. Ils sont invisibles au départ (classe hidden) et ton JavaScript les rend visibles au bon moment.

Règle d'or : préfixe tous tes identifiants avec le nom de ton module pour éviter les conflits.

<!-- overlay.html -->
<div id="mon-module-panel" class="hidden">
  <div id="mon-module-texte"></div>
</div>

⚙️ Module admin (admin.js)

Ce fichier construit l'interface de configuration qui apparaît dans le tableau de bord. C'est là que le streamer règle les messages, les sons, les couleurs de ton module.

AdminMods.register({
  id: 'mon-module',

  render(config, container, tools) {
    if (!config.mon_module) config.mon_module = {};
    const cfg = config.mon_module;

    container.innerHTML = `
      <div class="card">
        <div class="card-body">
          <div class="field">
            <label>Message</label>
            <input type="text" id="mm-msg" value="${cfg.message ?? ''}">
          </div>
        </div>
      </div>`;

    container.querySelector('#mm-msg').oninput = e => {
      cfg.message = e.target.value;
      tools.markDirty();
    };
  },

  getCommands(config) {
    return [
      { cmd: '!macommande', args: '[texte]', desc: 'Affiche quelque chose sur le stream' },
    ];
  },
});

L'objet tools

⚙️ Système de configuration

La configuration de l'utilisateur est un grand objet JSON stocké côté serveur. Chaque module occupe une clé, définie par configKey dans le manifest.

Au démarrage, OpenOverlay fusionne intelligemment trois sources (du moins au plus prioritaire) :

1. Le fichier config.json global
2. Le defaultConfig du manifest
3. La configuration sauvegardée par l'utilisateur

La fusion est profonde : si l'utilisateur n'a changé que le volume, les autres champs viennent de ton defaultConfig. Exception : les tableaux sont remplacés entièrement.

onTwitchEvent(type, event, api) {
  const cfg = api.config.mon_module;
  if (cfg?.enabled === false) return;
  const message = cfg?.message ?? 'Valeur par défaut';
  const volume  = cfg?.volume  ?? 1.0;
},

📡 Référence des événements Twitch

OpenOverlay s'abonne automatiquement à ces événements dès le démarrage. Tu les reçois tous dans onTwitchEvent(type, event, api).

💬 Commandes chat

Chaque message qui commence par ! déclenche onChatCommand() sur tous les modules. Il n'y a pas de routage exclusif — plusieurs modules peuvent répondre à la même commande.

onChatCommand(cmd, args, api, sender) {
  if (api.config.mon_module?.enabled === false) return;
  if (!sender?.isBroadcaster) return;
  if (cmd !== '!macommande') return;
  const texte = args.join(' ');
  api.sendChat(`Commande reçue : ${texte}`);
},

Niveaux d'accès

🗂️ Assets utilisateur

Chaque utilisateur dispose d'un espace de stockage personnel pour ses fichiers (GIFs, sons, images). Ces fichiers sont référencés avec le préfixe user:// dans la config, et résolus vers leur URL complète au moment de l'utilisation.

const uploadEl = container.querySelector('#mon-upload');
uploadEl.onchange = async (e) => {
  const file = e.target.files[0];
  if (!file) return;
  e.target.value = '';
  tools.showToast('Upload en cours…');
  try {
    const path = await tools.uploadAsset(file);
    cfg.sound = path;
    markDirty();
    tools.showToast('Fichier uploadé !');
  } catch (err) {
    tools.showToast(`Erreur : ${err.message}`, 'error');
  }
};

const soundPath = cfg?.sound;
if (soundPath) {
  const url = api.resolveAsset(soundPath);
  api.playSound(url, cfg.volume ?? 1);
}

🔗 Communication inter-modules

Les modules overlay peuvent se parler via OverlayMods.dispatch(). Cette fonction appelle une méthode sur tous les modules enregistrés qui l'implémentent.

OverlayMods.dispatch(
  'onChatCommand',
  '!macommande',
  ['arg1'],
  api,
  { isBroadcaster: true, login: 'viewer123', displayName: 'Viewer123' }
);

🚀 Exemple complet et commenté

Un module "Annonce de sub" — quand quelqu'un s'abonne, un panneau apparaît sur le stream avec un son. Le streamer peut configurer le message, la durée et le son depuis le dashboard.

Chaque ligne de code est commentée pour que tu comprennes exactement ce qui se passe.

{
  "id":          "sub-announce",
  "name":        "Annonce Abonnement",
  "description": "Affiche un panneau quand quelqu'un s'abonne",
  "icon":        "⭐",
  "configKey":   "sub_announce",
  "defaultConfig": {
    "enabled":  true,
    "message": "⭐ {username} vient de s'abonner !",
    "sound":   "",
    "volume":  1.0,
    "duration": 5000
  },
  "version": "1.0.0",
  "files": ["manifest.json", "overlay.js", "overlay.html", "admin.js"]
}

<div id="sa-panel" class="hidden" style="
  position: fixed; top: 50%; left: 50%;
  transform: translate(-50%, -50%);
  background: #1a1a2e; border: 2px solid #9147ff;
  border-radius: 16px; padding: 32px 40px;
  font-family: sans-serif; color: white;
  font-size: 28px; text-align: center; z-index: 9999;">
  <div id="sa-text"></div>
</div>

OverlayMods.register({
  id: 'sub-announce',
  _timer: null,

  onTwitchEvent(type, event, api) {
    const cfg = api.config.sub_announce;
    if (cfg?.enabled === false) return;
    if (type !== 'channel.subscribe' || event.is_gift) return;

    const text = (cfg?.message ?? '⭐ {username} s\'abonne !')
      .replace('{username}', event.user_name);

    if (cfg?.sound) {
      api.playSound(api.resolveAsset(cfg.sound), cfg.volume ?? 1);
    }
    this._show(text, cfg?.duration ?? 5000);
  },

  onAdminMessage(data, api) {
    if (data.type === 'sa_test') {
      this._show('⭐ TestUser vient de s\'abonner !', 3000);
    }
  },

  _show(text, duration) {
    clearTimeout(this._timer);
    const panel = document.getElementById('sa-panel');
    document.getElementById('sa-text').textContent = text;
    panel.classList.remove('hidden');
    this._timer = setTimeout(() => {
      panel.classList.add('hidden');
    }, duration);
  },
});

AdminMods.register({
  id: 'sub-announce',

  render(config, container, { markDirty, sendToOverlay, showToast, uploadAsset, addDropZone }) {
    if (!config.sub_announce) config.sub_announce = {};
    const cfg = config.sub_announce;

    container.innerHTML = `
      <div class="card">
        <div class="card-header no-border">
          <span class="card-title">⭐ Annonce Abonnement</span>
          <button class="btn btn-ghost btn-sm" id="sa-test">▶ Tester</button>
        </div>
        <div class="card-body grid">
          <div class="field">
            <label>Message <span class="hint">({username} = pseudo)</span></label>
            <input type="text" id="sa-msg" value="${cfg.message ?? ''}">
          </div>
          <div class="field">
            <label>Durée (ms)</label>
            <input type="number" id="sa-dur" min="1000" max="30000" step="500" value="${cfg.duration ?? 5000}">
          </div>
          <div class="field">
            <label>Son (optionnel)</label>
            <div style="display:flex;gap:8px">
              <input type="text" id="sa-snd" value="${cfg.sound ?? ''}" placeholder="user://...">
              <label class="btn btn-secondary btn-sm" style="cursor:pointer">⬆
                <input type="file" id="sa-snd-upload" accept="audio/*" style="display:none">
              </label>
            </div>
          </div>
        </div>
      </div>`;

    container.querySelector('#sa-msg').oninput = e => { cfg.message  = e.target.value;          markDirty(); };
    container.querySelector('#sa-dur').oninput = e => { cfg.duration = parseInt(e.target.value); markDirty(); };
    container.querySelector('#sa-snd').oninput = e => { cfg.sound    = e.target.value.trim();      markDirty(); };

    container.querySelector('#sa-test').onclick = () => {
      sendToOverlay({ type: 'sa_test' });
      showToast('Test envoyé — l\'overlay doit être ouvert');
    };

    const uploadEl = container.querySelector('#sa-snd-upload');
    const label    = uploadEl.closest('label');
    const doUpload = async (file) => {
      showToast('Upload en cours…');
      try {
        const path = await uploadAsset(file);
        cfg.sound = path;
        container.querySelector('#sa-snd').value = path;
        markDirty();
        showToast('Son uploadé !');
      } catch (err) {
        showToast(`Erreur : ${err.message}`, 'error');
      }
    };
    uploadEl.onchange = async (e) => {
      const f = e.target.files[0];
      if (!f) return;
      e.target.value = '';
      await doUpload(f);
    };
    addDropZone(label, ['audio/'], doUpload);
  },

  getCommands() { return []; },
});

🚀 Publier dans le Store

Tu as créé et testé un module qui te semble prêt à être partagé ? Voici le chemin complet, de la première ligne de code jusqu'à la disponibilité dans le Store officiel.

Tester en Mode Développeur

Avant de soumettre, tu dois valider ton module sur ta propre installation. Le Mode Développeur est accessible dans les Préférences du dashboard. Une fois activé, une section "Installer un module local" apparaît. Sélectionne le dossier de ton module — le dashboard le lit, le valide et l'envoie au serveur. Recharge ensuite la page.

Critères de validation

• Absence d'exfiltration de données — pas d'envoi du token, de la config ou de données personnelles vers des serveurs tiers
• Absence d'injection de code — pas d'exécution de scripts externes non déclarés
• Respect des APIs OpenOverlay — usage des hooks et méthodes documentés ici
• Fonctionnement stable — pas d'erreurs JS non catchées, pas de boucles infinies