Chat plugin commands

Déclarez une table de commandes pour des commandes telles que !uptime ou !so. Les tables de commandes supportent les alias, les restrictions des modérateurs, les temps de recharge par utilisateur, les arguments analysés, et les listes automatiques !help. Voir les bases du chat pour le payload de message de chat, l'envoi de messages et les filtres.

Enregistrez une table de commandes

Une table de commandes fournit :

• un préfixe de commande configurable, avec ! comme valeur par défaut
• description, usage et alias par commande
• temps de recharge par utilisateur
• restriction réservée aux modérateurs basée sur les portées de l'expéditeur
• analyse des arguments
• une liste automatique !help

JavaScript

const { definePlugin } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  commandPrefix: '!', // optional
  commands: {
    uptime: {
      description: "How long we've been live",
      run: ctx => ctx.reply("we've been live a while!"),
    },
    so: {
      description: 'Shout out a viewer',
      usage: '!so <name>',
      aliases: ['shoutout'],
      cooldownMs: 10_000,
      run: ctx => ctx.reply(`go follow ${ctx.args[0] || 'someone cool'}`),
    },
    clear: {
      description: 'Clear the chat',
      modOnly: true,
      run: ctx => ctx.replyPrivately('done'),
    },
  },
});

Python

from owncast_plugin import plugin

plugin.commands({
    "uptime": {
        "description": "How long we've been live",
        "run": lambda ctx: ctx.reply("we've been live a while!"),
    },
    "so": {
        "description": "Shout out a viewer",
        "usage": "!so <name>",
        "aliases": ["shoutout"],
        "cooldown_ms": 10_000,
        "run": lambda ctx: ctx.reply(
            f"go follow {ctx.args[0] if ctx.args else 'someone cool'}"
        ),
    },
    "clear": {
        "description": "Clear the chat",
        "mod_only": True,
        "run": lambda ctx: ctx.reply_privately("done"),
    },
}, prefix="!")

Les gestionnaires JavaScript reçoivent msg, user, command, invokedAs, args, argString, reply, et replyPrivately. Python utilise invoked_as, arg_string, et reply_privately.

Des noms de commandes en double sont autorisés, donc chaque plugin correspondant s'exécute. Les commandes inconnues, les invocations réservées aux modérateurs et les invocations limitées par temps de recharge sont silencieuses. Déclarer ou recevoir une commande ne nécessite aucune permission. Les actions à l'intérieur du gestionnaire nécessitent toujours leurs permissions habituelles, telles que chat.send.

!help est automatique mais pas réservé

Owncast publie un message système répertoriant les descriptions des commandes de chaque plugin activé. Les commandes réservées aux modérateurs restent cachées des non-moderateurs. Cette réponse intégrée ne nécessite aucune permission de plugin.

!help et son alias !commands restent des messages de chat ordinaires. Les plugins peuvent également les déclarer ou y répondre. La réponse intégrée n'empêche pas d'autres réponses de plugins supplémentaires.

Utilisation de gestionnaires et de filtres de chat ordinaires

Une table de commandes est optionnelle. Un plugin peut inspecter msg.body dans un gestionnaire onChatMessage pour une seule commande fixe. Les commandes faites à la main n'apparaissent pas dans la liste d'aide intégrée.

Les messages de commande restent des messages de chat ordinaires, donc un plugin peut utiliser à la fois une table de commandes et un gestionnaire de chat ordinaire. Les filtres de chat s'exécutent avant la correspondance des commandes. Un message supprimé par un filtre n'exécute aucune commande déclarée.

Exemples de plugins

• mod-commands (JavaScript, Python): un préfixe ? personnalisé avec alias, temps de recharge et restrictions de modérateur.
• stream-tracker (JavaScript, Python): une table de commandes avec !uptime et !who, plus le suivi de l'activité de streaming et d'utilisateur de chat.
• stream-ops (JavaScript, Python): une table de commandes qui rapporte la télémétrie de diffusion et vidéo.
• timer-bot (JavaScript, Python): une table de commandes pour des rappels et des comptes à rebours (!remind, !every, !countdown).
• ip-bot (JavaScript, Python): une seule commande !ip répondue avec l'IP publique du serveur.
• relay (JavaScript, Python): réémet /announce \<text> en tant qu'annonce de diffusion.

Où aller ensuite

• Plugins de chat pour le payload de message de chat, l'envoi de messages et les filtres.
• Référence des gestionnaires pour les événements de chat auxquels votre plugin peut s'inscrire.
• Référence des API pour chaque méthode owncast.* et la permission dont elle a besoin.