Chat plugin commands

Declare uma tabela de comandos para comandos como !uptime ou !so. Tabelas de comandos suportam aliases, controle de moderador, cooldowns por usuário, argumentos analisados, e listas automáticas de !help. Veja chat basics para a carga útil da mensagem de chat, envio de mensagens e filtros.

Registrar uma tabela de comandos

Uma tabela de comandos fornece:

• um prefixo de comando configurável, com ! como padrão
• descrição, uso, e aliases por comando
• cooldowns por usuário
• controle de moderador apenas com base nos escopos do remetente
• análise de argumentos
• uma lista automática de !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="!")

Os manipuladores de JavaScript recebem msg, user, command, invokedAs, args, argString, reply e replyPrivately. Python usa invoked_as, arg_string e reply_privately.

Nomes de comandos duplicados são permitidos, assim todos os plugins que correspondem são executados. Comandos desconhecidos, invocações com controle de moderador e invocações limitadas por cooldown são silenciosos. Declarar ou receber um comando não requer permissão. Ações dentro do manipulador ainda requerem suas permissões habituais, como chat.send.

!help é automático, mas não reservado

Owncast publica uma mensagem de sistema listando descrições de comandos de cada plugin habilitado. Comandos exclusivos de moderador permanecem ocultos de não-moderadores. Essa resposta interna não precisa de permissão de plugin.

!help e seu alias !commands permanecem mensagens de chat comuns. Plugins também podem declarar ou responder a eles. A resposta interna não bloqueia respostas de plugins adicionais.

Usando manipuladores de chat e filtros comuns

Uma tabela de comandos é opcional. Um plugin pode inspecionar msg.body em um manipulador onChatMessage para um único comando fixo. Comandos feitos manualmente não aparecem na listagem de ajuda interna.

Mensagens de comando permanecem mensagens comuns do chat, então um plugin pode usar tanto uma tabela de comandos quanto um manipulador de chat comum. Filtros de chat são executados antes da correspondência de comandos. Uma mensagem descartada por um filtro não executa qualquer comando declarado.

Plugins de exemplo

• mod-commands (JavaScript, Python): um prefixo ? customizado com aliases, cooldowns e controle de moderador.
• stream-tracker (JavaScript, Python): uma tabela de comandos com !uptime e !who, além de rastreamento de atividade de stream e usuário de chat.
• stream-ops (JavaScript, Python): uma tabela de comandos que relata telemetria de transmissão e vídeo.
• timer-bot (JavaScript, Python): uma tabela de comandos para lembretes e contagens regressivas (!remind, !every, !countdown).
• ip-bot (JavaScript, Python): um único comando !ip respondido com o IP público do servidor.
• relay (JavaScript, Python): re-emite /announce \<texto> como um anúncio de transmissão.

Para onde ir a seguir

• Plugins de chat para a carga útil da mensagem de chat, envio de mensagens e filtros.
• Referência de manipuladores para os eventos de chat que seu plugin pode se inscrever.
• Referência de APIs para cada método owncast.* e a permissão que ele precisa.