Chat plugin commands

Объявите таблицу команд для команд, таких как !uptime или !so. Таблицы команд поддерживают псевдонимы, ограничения для модераторов, перерывы на пользователя, разобранные аргументы и автоматические списки !help. Смотрите основы чата для получения данных о сообщениях чата, отправке сообщений и фильтрах.

Зарегистрировать таблицу команд

Таблица команд предоставляет:

• настраиваемый префикс команды, где ! является значением по умолчанию
• описание, использование и псевдонимы для каждой команды
• перерывы на пользователя
• ограничения только для модераторов на основе прав отправителя
• разбор аргументов
• автоматический список !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="!")

Обработчики JavaScript получают msg, user, command, invokedAs, args, argString, reply и replyPrivately. Python использует invoked_as, arg_string и reply_privately.

Разрешены дублирующие имена команд, поэтому выполняются все сопоставимые плагины. Неизвестные команды, вызовы, ограниченные модераторами, и вызовы с ограничениями по времени молчат. Объявление или получение команды не требует никаких разрешений. Действия внутри обработчика все равно требуют их обычных прав, таких как chat.send.

!help является автоматическим, но не зарезервированным

Owncast отправляет системное сообщение со списком описаний команд от каждого включенного плагина. Команды только для модераторов скрыты от немодераторов. Этот встроенный ответ не требует разрешений на плагин.

!help и его псевдоним !commands остаются обычными сообщениями в чате. Плагины также могут объявлять или отвечать на них. Встроенный ответ не блокирует дополнительные ответы плагина.

Использование обычных обработчиков и фильтров чата

Таблица команд является необязательной. Плагин может просматривать msg.body в обработчике onChatMessage для одной фиксированной команды. Команды с ручным управлением не отображаются в встроенном списке помощи.

Сообщения команд остаются обычными сообщениями в чате, поэтому плагин может использовать как таблицу команд, так и обычный обработчик чата. Фильтры чата запускаются перед сопоставлением команд. Сообщение, отброшенное фильтром, не выполняет ни одной объявленной команды.

Примеры плагинов

• mod-commands (JavaScript, Python): пользовательский префикс ? с псевдонимами, перерывами и ограничениями для модераторов.
• stream-tracker (JavaScript, Python): таблица команд с !uptime и !who, плюс отслеживание активности потока и пользователей чата.
• stream-ops (JavaScript, Python): таблица команд, которая сообщает о телеметрии трансляции и видео.
• timer-bot (JavaScript, Python): таблица команд для напоминаний и обратного отсчета (!remind, !every, !countdown).
• ip-bot (JavaScript, Python): одна команда !ip, отвечающая на публичный IP сервера.
• relay (JavaScript, Python): повторно передает /announce \<text> как трансляционное объявление.

Куда двигаться дальше

• Плагины чата для получения данных о сообщениях чата, отправке сообщений и фильтрах.
• Справочник обработчиков для событий чата, на которые ваш плагин может подписаться.
• Справочник API для каждого метода owncast.* и разрешения, которое ему требуется.