WebSocket 机器人

WebSocket 机器人是一个通过 WebSocket 远程控制 MCC 的示例外部机器人 。 它在您的 MCC 会话中运行本地WebSocket 服务器，通过 JSON 消息形式接受命令， 并实时将游戏事件推回到已连接的客户端。

外部机器人

此机器人 不是 MCC 内建的。 使用 /script ChatBots/WebSocketBot.cs 将其加载为独立脚本。

快速入门

  1. 复制 config/ChatBots/WebSocketBot.cs 到您的 MCC config/ChatBots/ 文件夹（代码仓库的路径下已经包含此文件）。
  2. 打开文件并编辑首行代码：
    MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "CHANGE_THIS_PASSWORD"));
    • 将 127.0.0.1 替换为要绑定的 IP（使用 + 或 * 绑定所有接口）。
    • 将 8043 替换为您需要的端口。
    • 将 CHANGE_THIS_PASSWORD 替换为一个复杂密码。
  3. （可选）启用调试日志：
    MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "mypassword", debugMode: true));
  4. 在 MCC中，运行： /script ChatBots/WebSocketBot.cs

机器人会启动一个 WebSocket 服务器。 使用任何 WebSocket 客户端连接到 ws://127.0.0.1:8043/`。

协议概述

所有通信使用 WebSocket 文本帧传输 JSON。

身份验证流程

连接 WebSocket
        |
        v
（可选）发送 "ChangeSessionId" 设置会话名称
        |
        v
发送 "Authenticate" 和设置的密码
        |
        v
发送命令，接受事件

发送命令

命令是以下格式的 JSON 对象：

{
  "command": "命令名",
  "requestId": "任意-唯一-字符串",
  "parameters": [1, "text", true]
}
  • command - 程序名称（区分大小写）
  • requestId - 客户端生成的ID，用于匹配请求和响应
  • parameters - 包含参数的有序数组（类型取决于命令）

每个命令都生成一个 OnWsCommandResponse 事件，包含 success, requestId 和可选的 message 字段。

发送纯文本

您也可以直接发送纯文本：

  • 以 / 开头的文本将作为内部命令转发到 MCC（例如 /move north）。
  • 其它文本作为聊天发送。

接收事件

事件以JSON形式抵达：

{
  "event": "事件名",
  "data": "{ ... 序列化载荷 ... }"
}

data字段是一个JSON字符串，您可以单独解析以获取事件的有效载荷。

枚举序列化（字符化名称）

所有枚举值 (物品类型、实体类型、方向、主副手等） 都将序列化为 字符串名称，而不是数字 ID。

例如，类型为 Zombie 的实体表现为：

{ "type": "Zombie", "location": { "x": 10, "y": 64, "z": -20 } }

当发送接受枚举参数的命令时，传入字符串名称或数字值 皆可：

{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, "Interact", "MainHand"] }

或者：

{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, 0, 0] }

有两个专用命令可以查询完整的映射表：

  • GetItemTypeMappings 返回 { "DiamondSword": 798, "Stone": 1, ... }
  • GetEntityTypeMappings 返回 { "Player": 128, "Zombie": 119, ... }

如果您的客户端需要当前 MCC 版本的名称到ID查询，这些命令会很有用。

参考内容

  • 命令 - 可用命令的完整列表
  • 事件 - 可发送事件的完整列表

⭐ 参考实现：MCC.js

MCC.js 是该机器人的 Node.js/TypeScript 实现。 It handles authentication, JSON serialization, event subscriptions, and typed command wrappers out of the box.

If you're writing a client in JavaScript or TypeScript, start there.

Compatibility

  • Requires any MCC version that supports /script (standalone MCCScript 1.0 bots).
  • Uses only System.Text.Json (built into .NET), so no extra DLLs are needed.
  • Compatible with MCC.js and any WebSocket client library.