MCCTP - Minecraft Control Transfer Protocol
一个 Fabric 模组,在您的 Minecraft 客户端上暴露一个 WebSocket 服务器。它每 tick 将游戏状态流式传输出来,并接收动作命令——让任何程序、使用任何语言来控制玩家。
特性
- WebSocket API — 基于 WebSocket 的 JSON 通信,与语言无关
- 13 种动作类型 — 移动、战斗、物品栏、摄像机等
- 每 tick 的游戏状态 — 生命值、位置、手持物品、战斗上下文
- 物品分类 — 自动分类(SWORD, BOW, BLOCK, FOOD 等)
- 快捷轮盘叠加层 — 显示全部 9 个槽位的圆形 HUD,可通过命令或 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 个游戏刻广播一次游戏状态(20 个游戏刻 = 1 秒) |
架构
任何客户端 ←── WebSocket (JSON) ──→ Fabric 模组
│
├── WebSocketServer (Netty, 独立线程组)
│ ├── WebSocketServerInitializer (HTTP → WS 升级)
│ ├── WebSocketFrameHandler (解析传入的 JSON)
│ └── ConnectionManager (跟踪通道,广播消息)
│
├── 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 (定时按键脉冲)
│
└── HotbarWheelRenderer (HUD 覆盖层)
关键实现细节:
- WebSocket 服务器使用 Netty 的
NioEventLoopGroup,完全独立于 Minecraft 的网络线程 - 所有操作处理器通过
MinecraftClient.execute()在游戏线程上运行 —— 与真实玩家输入相同 - 脉冲操作(跳跃、攻击、投掷、交换、库存)使用
KeyReleaseScheduler,该调度器将按键保持 3 个游戏刻并增加timesPressed,以匹配 Minecraft 处理单次按键的方式 - 持续操作(移动、潜行、冲刺、使用物品)直接设置
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
你是这个资源的作者?登录后可认领此资源。
相似资源
缓冲的原始输入和线程化的事件轮询
一个用于收集生物掉落物的多区块模组。
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
可定制的鞘翅模组,支持装饰纹饰、旗帜图案等更多功能!
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
查看物品与配方
评论 0
登录后参与评分
还没有评论,来抢沙发吧