Chat plugin commands

Declara una tabla de comandos para comandos como !uptime o !so. Las tablas de comandos soportan alias, puertas de moderador, enfriamientos por usuario, argumentos analizados y listados automáticos de !help. Consulta fundamentos del chat para el data del mensaje de chat, envío de mensajes y filtros.

Registrar una tabla de comandos

Una tabla de comandos proporciona:

• un prefijo de comando configurable, con ! como predeterminado
• descripción, uso y alias por comando
• enfriamientos por usuario
• control de moderador solo basado en los alcances del remitente
• análisis de argumentos
• una 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="!")

Los controladores de JavaScript reciben msg, user, command, invokedAs, args, argString, reply, y replyPrivately. Python usa invoked_as, arg_string, y reply_privately.

Se permiten nombres de comandos duplicados, por lo que cada complemento coincidente se ejecuta. Los comandos desconocidos, las invocaciones restringidas por moderador y las invocaciones limitadas por enfriamiento son silenciosas. Declarar o recibir un comando no requiere permisión. Las acciones dentro del controlador aún requieren sus permisos habituales, como chat.send.

!help es automático pero no está reservado

Owncast publica un mensaje del sistema que enumera las descripciones de los comandos de cada complemento habilitado. Los comandos solo para moderadores permanecen ocultos para los no moderadores. Esta respuesta incorporada o necesita permisos de complemento.

!help y su alias !commands permanecen como mensajes de chat ordinarios. Los complementos también pueden declarar o responder a ellos. La respuesta incorporada no bloquea respuestas adicionales de complementos.

Usando controladores y filtros de chat ordinarios

Una tabla de comandos es opcional. Un complemento puede inspeccionar msg.body en un controlador onChatMessage para un solo comando fijo. Los comandos hechos a mano no aparecen en la lista de ayuda incorporada.

Los mensajes de comandos siguen siendo mensajes de chat ordinarios, por lo que un complemento puede usar tanto una tabla de comandos como un controlador de chat ordinario. Los filtros de chat se ejecutan antes de la coincidencia de comandos. Un mensaje desechado por un filtro no ejecuta ningún comando declarado.

Ejemplos de complementos

• mod-commands (JavaScript, Python): un prefijo ? personalizado con alias, enfriamientos y control de moderadores.
• stream-tracker (JavaScript, Python): una tabla de comandos con !uptime y !who, además de seguimiento de actividad de transmisión y de usuario de chat.
• stream-ops (JavaScript, Python): una tabla de comandos que informa sobre la telemetría de transmisión y video.
• timer-bot (JavaScript, Python): una tabla de comandos para recordatorios y cuentas regresivas (!remind, !every, !countdown).
• ip-bot (JavaScript, Python): un único comando !ip respondido con la IP pública del servidor.
• relay (JavaScript, Python): vuelve a emitir /announce \<text> como un anuncio de transmisión.

A dónde ir después

• Complementos de chat para el data del mensaje de chat, envío de mensajes y filtros.
• Referencia de controladores para los eventos de chat a los que tu complemento puede suscribirse.
• Referencia de APIs para cada método owncast.* y el permiso que necesita.