Chat plugin commands

Dichiara una tabella comandi per comandi come !uptime o !so. Le tabelle comandi supportano alias, gate per moderatori, cooldown per utente, argomenti analizzati e elenchi automatici di !help. Vedi nozioni di base sulle chat per il payload del messaggio in chat, invio di messaggi e filtri.

Registrare una tabella comandi

Una tabella comandi fornisce:

• un prefisso comandi configurabile, con ! come predefinito
• descrizione, uso e alias per comando
• cooldown per utente
• gate per moderatori basati sugli ambiti del mittente
• analisi degli argomenti
• un elenco automatico di !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="!")

I gestori di JavaScript ricevono msg, user, command, invokedAs, args, argString, reply, e replyPrivately. Python usa invoked_as, arg_string, e reply_privately.

I nomi dei comandi duplicati sono consentiti, quindi ogni plugin corrispondente viene eseguito. Comandi sconosciuti, invocazioni soggette a moderatori e invocazioni limitate da cooldown ingoiano. Dichiarare o ricevere un comando non richiede autorizzazioni. Le azioni all'interno del gestore richiedono comunque le loro consuete autorizzazioni, come chat.send.

!help è automatico ma non riservato

Owncast pubblica un messaggio di sistema che elenca le descrizioni dei comandi di ogni plugin abilitato. I comandi solo per moderatori rimangono nascosti ai non moderatori. Questa risposta incorporata non richiede autorizzazioni del plugin.

!help e il suo alias !commands rimangono messaggi di chat ordinari. I plugin possono anche dichiararli o rispondere a essi. La risposta integrata non blocca le ulteriori risposte del plugin.

Utilizzare gestori e filtri di chat ordinari

Una tabella comandi è opzionale. Un plugin può ispezionare msg.body in un gestore onChatMessage per un singolo comando fisso. I comandi artigianali non appaiono nell'elenco di aiuto incorporato.

I messaggi di comando rimangono messaggi di chat ordinari, quindi un plugin può utilizzare sia una tabella comandi che un gestore di chat ordinario. I filtri della chat vengono eseguiti prima della corrispondenza dei comandi. Un messaggio eliminato da un filtro non esegue alcun comando dichiarato.

Plugin di esempio

• mod-commands (JavaScript, Python): un prefisso personalizzato ? con alias, cooldown e gate per moderatori.
• stream-tracker (JavaScript, Python): una tabella comandi con !uptime e !who, oltre al tracciamento dell'attività di stream e utente in chat.
• stream-ops (JavaScript, Python): una tabella comandi che riporta telemetria di trasmissione e video.
• timer-bot (JavaScript, Python): una tabella comandi per promemoria e conteggi (!remind, !every, !countdown).
• ip-bot (JavaScript, Python): un singolo comando !ip risposto con l'IP pubblico del server.
• relay (JavaScript, Python): riemette /announce \<text> come annuncio di trasmissione.

Dove andare dopo

• Plugin chat per il payload del messaggio della chat, invio di messaggi e filtri.
• Riferimento ai gestori per gli eventi di chat a cui il tuo plugin può iscriversi.
• Riferimento alle API per ogni metodo owncast.* e l'autorizzazione di cui ha bisogno.