MCCTP

MCCTP

一个Fabric模组,在你的Minecraft客户端上暴露WebSocket服务器。它每个游戏刻流式输出游戏状态,并接收操作命令——让任何语言编写的任何程序都能控制玩家。

MCCTP - Minecraft 控制传输协议

一个 Fabric 模组,在你的 Minecraft 客户端上暴露一个 WebSocket 服务器。它每个 tick 向外流式传输游戏状态,并接收动作命令——让任何语言编写的任何程序都能控制玩家。

特性

  • WebSocket API — 基于 WebSocket 的 JSON,语言无关
  • 13 种动作类型 — 移动、战斗、物品栏、视角等
  • 每个 tick 广播游戏状态 — 生命值、位置、手持物品、战斗上下文
  • 物品分类 — 自动分类(SWORD、BOW、BLOCK、FOOD 等)
  • 快捷栏轮盘叠加层 — 圆形 HUD 显示全部 9 个槽位,可通过命令或 V 键控制
  • 线程安全 — WebSocket 运行在独立的 Netty 线程组上,动作分派到游戏线程

依赖要求

  • Minecraft 1.21.11
  • Fabric Loader >= 0.18.0
  • Fabric API
  • Java 21+

安装

./gradlew build

将 build/libs/mcctp-1.0.0.jar 复制到你的 .minecraft/mods/ 文件夹(与 Fabric Loader + Fabric API 一起)。

工作原理

当你加入一个世界时,模组会在端口 8765 上启动一个 WebSocket 服务器。任何客户端都可以连接到 ws://<host>:8765/mcctp 并:

  1. 接收每个 tick 的游戏状态 JSON(默认 50ms)
  2. 发送 JSON 动作命令来控制玩家

服务器运行在独立的 Netty NioEventLoopGroup 上,与 Minecraft 的网络线程完全分离。传入的动作通过 MinecraftClient.execute() 分派到游戏线程,因此它们是安全的,并且行为与真实输入完全一致。当你离开世界时,服务器停止。

协议

连接

ws://<host>:8765/mcctp

标准 WebSocket 连接。无身份验证。多个客户端可以同时连接。

游戏状态(服务器 → 客户端)

每个 tick 向所有已连接的客户端广播。所有字段始终存在。

{
  "type": "game_state",
  "timestamp": 1700000000000,
  "selectedSlot": 0,
  "heldItem": {
    "name": "minecraft:diamond_sword",
    "category": "SWORD",
    "stackCount": 1,
    "maxDurability": 1561,
    "currentDurability": 1500
  },
  "offhandItem": {
    "name": "minecraft:shield",
    "category": "SHIELD",
    "stackCount": 1,
    "maxDurability": 336,
    "currentDurability": 336
  },
  "playerState": {
    "health": 20.0,
    "maxHealth": 20.0,
    "hunger": 20,
    "saturation": 5.0,
    "x": 100.5,
    "y": 64.0,
    "z": -200.3,
    "yaw": 45.0,
    "pitch": -10.0,
    "onGround": true,
    "sprinting": false,
    "sneaking": false,
    "swimming": false,
    "flying": false,
    "inWater": false,
    "onFire": false
  },
  "combatContext": {
    "isUsingItem": false,
    "isBlocking": false,
    "activeHand": "MAIN_HAND",
    "crosshairTarget": "ENTITY",
    "crosshairEntityType": "minecraft:zombie",
    "crosshairBlockPos": null
  }
}

游戏状态字段

字段 类型 描述
type string 始终为 "game_state"
timestamp long Unix 毫秒时间戳
selectedSlot int 当前快捷栏槽位(0-8)

heldItem / offhandItem:

字段 类型 描述
name string 注册表 ID,例如 "minecraft:diamond_sword"
category string 见物品分类
stackCount int 当前堆叠数量
maxDurability int 最大耐久度(若不可损坏则为 0)
currentDurability int 剩余耐久度

playerState:

字段 类型 描述
health float 当前生命值(0-20)
maxHealth float 最大生命值
hunger int 饥饿值(0-20)
saturation float 饱和度
x, y, z float 世界坐标
yaw, pitch float 视角旋转(角度)
onGround bool 站在实体方块上
sprinting bool 当前正在疾跑
sneaking bool 当前正在潜行
swimming bool 当前正在游泳
flying bool 创造/鞘翅飞行
inWater bool 浸在水中
onFire bool 正在燃烧

combatContext:

字段 类型 描述
isUsingItem bool 按住右键(进食、拉弓等)
isBlocking bool 使用盾牌格挡
activeHand string "MAIN_HAND" 或 "OFF_HAND"
crosshairTarget string "ENTITY"、"BLOCK" 或 "MISS"
crosshairEntityType string? 实体注册表 ID,或 null
crosshairBlockPos int[3]? [x, y, z] 方块坐标,或 null

动作(客户端 → 服务器)

发送带有 action 和 params 的 JSON 消息:

{"action": "<action_name>", "params": {<params>}}

动作参考

动作 参数 描述
move direction: "forward" "backward" "left" "right", state: "start" "stop" WASD 移动。保持按键直到你发送 "stop"。
look yaw: float, pitch: float, relative: bool 视角控制。relative: true 会加到当前角度上。relative: false 设置绝对角度。
jump (无) 单次跳跃。
attack (无) 左键点击——挥动武器、攻击实体、开始破坏方块。
use_item state: "start" "stop" 按住右键。使用 "start" 开始(拉弓、进食、举盾),用 "stop" 释放。
throw_item (无) 单次右键脉冲——用于雪球、末影珍珠、发射已装填的弩。
select_slot slot: int (0-8) 切换当前快捷栏槽位。
sneak state: "start" "stop" 蹲下。保持直到停止。
sprint state: "start" "stop" 疾跑。保持直到停止。
drop_item full_stack: bool 丢弃手持物品。true 丢弃整组(Ctrl+Q)。
swap_hands (无) 交换主手和副手(F 键)。
open_inventory (无) 切换物品栏界面(E 键)。
toggle_wheel (无) 切换快捷栏轮盘 HUD 叠加层。

动作示例

// 向前走
{"action": "move", "params": {"direction": "forward", "state": "start"}}

// 停止行走
{"action": "move", "params": {"direction": "forward", "state": "stop"}}

// 向右转 90 度
{"action": "look", "params": {"yaw": 90.0, "pitch": 0.0, "relative": true}}

// 面朝北,直视前方
{"action": "look", "params": {"yaw": 180.0, "pitch": 0.0, "relative": false}}

// 拉弓并射箭
{"action": "use_item", "params": {"state": "start"}}
// ... 等待约 1 秒 ...
{"action": "use_item", "params": {"state": "stop"}}

// 投掷雪球
{"action": "throw_item", "params": {}}

// 切换到槽位 3 并攻击
{"action": "select_slot", "params": {"slot": 3}}
{"action": "attack", "params": {}}

物品分类

每个手持物品都会被归入以下类别之一:

类别 示例
SWORD 钻石剑、下界合金剑
BOW 弓
CROSSBOW 弩
AXE 铁斧、木斧
PICKAXE 钻石镐
SHOVEL 石锹
HOE 下界合金锄
TRIDENT 三叉戟
SHIELD 盾牌
FOOD 牛排、金苹果
BLOCK 圆石、泥土、木板
THROWABLE 雪球、鸡蛋、末影珍珠
FISHING_ROD 钓鱼竿
EMPTY 空手
OTHER 以上均未匹配的物品

配置

配置文件:.minecraft/config/mcctp.json(首次启动时创建)

{
  "port": 8765,
  "tickInterval": 1
}
字段 默认值 描述
port 8765 WebSocket 服务器端口
tickInterval 1 每 N 个 tick 广播一次游戏状态(20 tick = 1 秒)

架构

Any Client ←── WebSocket (JSON) ──→ Fabric Mod
                                       │
                                       ├── WebSocketServer (Netty, own thread group)
                                       │     ├── WebSocketServerInitializer (HTTP → WS upgrade)
                                       │     ├── WebSocketFrameHandler (parse inbound JSON)
                                       │     └── ConnectionManager (track channels, broadcast)
                                       │
                                       ├── GameStateCollector (END_CLIENT_TICK → JSON)
                                       │     ├── GameStatePayload
                                       │     ├── HeldItemInfo + ItemCategorizer
                                       │     ├── PlayerStateInfo
                                       │     └── CombatContextInfo
                                       │
                                       ├── ActionDispatcher (JSON → ActionHandler)
                                       │     ├── MoveHandler, LookHandler, JumpHandler
                                       │     ├── AttackHandler, UseItemHandler, ThrowItemHandler
                                       │     ├── SelectSlotHandler, SneakHandler, SprintHandler
                                       │     ├── DropItemHandler, SwapHandsHandler
                                       │     ├── OpenInventoryHandler, ToggleWheelHandler
                                       │     └── KeyReleaseScheduler (timed key pulses)
                                       │
                                       └── HotbarWheelRenderer (HUD overlay)

关键实现细节:

  • WebSocket 服务器使用 Netty 的 NioEventLoopGroup,与 Minecraft 的网络线程完全分离
  • 所有动作处理器都通过 MinecraftClient.execute() 在游戏线程上运行——与真实玩家输入相同
  • 脉冲动作(跳跃、攻击、投掷、交换、物品栏)使用 KeyReleaseScheduler,它会保持按键 3 个 tick 并递增 timesPressed,与 Minecraft 处理单次按键的方式一致
  • 保持动作(移动、潜行、疾跑、use_item)直接设置 KeyBinding.pressed,并保持按住直到收到 "stop" 命令
  • 状态收集挂接到 END_CLIENT_TICK,并使用 Gson 进行序列化
  • 模组使用 Mixin 访问器(KeyBindingAccessor)来访问 KeyBinding.pressed 和 KeyBinding.timesPressed

从源码构建

# 构建
./gradlew build

# 输出 jar
build/libs/mcctp-1.0.0.jar

构建目标为 Java 21。已使用 Gradle 9.2.0 和 Fabric Loom 1.15.3 测试。

Python 客户端

python/ 中包含一个参考 Python 客户端。安装方式:

cd python
pip install -e .

提供异步和同步 WebSocket 客户端,并带有针对游戏状态的类型化数据类:

import time
from mcctp import SyncMCCTPClient, Actions

with SyncMCCTPClient("localhost", 8765) as client:
    client.on_state(lambda s: print(s.player_state.health))
    client.send(Actions.move("forward", "start"))
    time.sleep(2)
    client.send(Actions.move("forward", "stop"))

还包括 remote_play.py——一个键盘/鼠标透传工具,让其他人可以从另一台电脑在你的世界中游玩。

许可

MIT