MCCTP

模组

· 作者 lucasoyen

一个 Fabric 模组,它会在你的 Minecraft 客户端上暴露一个 WebSocket 服务器。该模组每刻(tick)向外流式传输游戏状态,并接收动作指令——从而允许任何程序、使用任何语言来控制玩家。

0 本站下载 0 关注 更新于 8 个月前

最新 1.2.0 · 1.21.11 · Fabric

一键开服(送7天)

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 并:

  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 个游戏刻广播一次游戏状态(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

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源