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 别名仍然是普通聊天消息。 插件也可以声明或响应它们。 内置响应不会阻塞其他 插件响应。

使用普通聊天处理程序和过滤器

指令表是可选的。 插件可以在 onChatMessage 处理程序中检查 msg.body 以获取单个固定指令。 手动指令不会出现在内置帮助列表中。

指令消息仍然是普通聊天消息，因此插件可以同时使用 指令表和普通聊天处理程序。 聊天过滤器在指令 匹配之前运行。 被过滤器丢弃的消息不会执行任何声明的指令。

示例插件

• 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.* 方法及其需要的权限。