
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 并:
- 接收每个 tick 的游戏状态 JSON(默认 50ms)
- 发送 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
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。