MCSTP - Minecraft State Transfer Protocol
一个 Fabric 模组,为 MCCTP 添加了全面的游戏状态遥测功能。它通过 MCCTP 的 WebSocket 在每个游戏刻(tick)广播丰富的状态快照——包括玩家信息、战斗上下文、威胁扫描、输入状态、屏幕状态、状态效果等。
功能特性
- 每刻完整的游戏状态 — 位置、生命值、物品栏、战斗、威胁、输入、屏幕、状态效果
- 威胁扫描 — 检测 16 格内的敌对生物、最近距离/角度、数量
- 输入镜像 — 报告玩家按下的按键和鼠标增量
- 屏幕感知 — 知道 GUI 是否打开、光标位置、鼠标/Shift 键状态
- 状态效果追踪 — 11 种常见效果的布尔标志
- GUI 操作 — 针对打开屏幕的光标定位和点击模拟
- 插件架构 — 注册到 MCCTP 的 API,共享同一个 WebSocket 连接
依赖要求
- Minecraft 1.21.11
- Fabric Loader >= 0.16.0
- Fabric API
- MCCTP >= 1.0.0
- Java 21+
安装方法
# 先构建 MCCTP(MCSTP 依赖于它的 JAR 文件)
cd mcctp
./gradlew build
# 然后构建 MCSTP
cd ../MCSTP
./gradlew build
将两个 JAR 文件从 build/libs/ 复制到你的 .minecraft/mods/ 文件夹中。
工作原理
MCSTP 作为模块接入 MCCTP。在初始化时,它会向 MCCTP 的 API 注册一个状态提供者和两个动作处理器。它不运行自己的服务器——MCCTP 的 WebSocket 处理所有通信。
当两个模组都安装后,客户端在连接时会收到握手消息:
{"type": "handshake", "modules": ["mcctp", "mcstp"], "version": "1.0"}
如果只安装了 MCCTP,modules 字段为 ["mcctp"],且不会广播任何状态数据。
协议规范
游戏状态(服务端 → 客户端)
MCSTP 扩展了 MCCTP 广播的游戏状态负载。包含所有 MCCTP 的基础字段,以及以下额外部分:
{
"type": "game_state",
"timestamp": 1700000000000,
"selectedSlot": 0,
"heldItem": {
"name": "minecraft:diamond_sword",
"category": "SWORD",
"stackCount": 1,
"maxDurability": 1561,
"currentDurability": 1400
},
"offhandItem": {
"name": "minecraft:shield",
"category": "SHIELD",
"stackCount": 1,
"maxDurability": 336,
"currentDurability": 336
},
"playerState": {
"health": 18.0,
"maxHealth": 20.0,
"hunger": 19,
"saturation": 3.0,
"x": 142.5,
"y": 72.0,
"z": -38.3,
"yaw": 45.0,
"pitch": -10.0,
"onGround": true,
"sprinting": false,
"sneaking": false,
"swimming": false,
"flying": false,
"inWater": false,
"onFire": false,
"experienceLevel": 24,
"experienceProgress": 0.65,
"totalExperience": 897
},
"combatContext": {
"isUsingItem": false,
"isBlocking": false,
"activeHand": "MAIN_HAND",
"crosshairTarget": "ENTITY",
"crosshairEntityType": "minecraft:zombie",
"crosshairBlockPos": null,
"crosshairDistance": 3.2,
"crosshairEntityHealth": 14.0,
"crosshairEntityMaxHealth": 20.0
},
"playerInput": {
"movementForward": 1.0,
"movementSideways": 0.0,
"jump": false,
"sprint": true,
"sneak": false,
"attack": false,
"useItem": false,
"drop": false,
"swapOffhand": false,
"openInventory": false,
"yawDelta": 2.35,
"pitchDelta": -0.5
},
"screenState": {
"screenOpen": false,
"screenType": null,
"cursorX": 0.0,
"cursorY": 0.0,
"mouseLeft": false,
"mouseRight": false,
"shiftHeld": false
},
"statusEffects": {
"speed": false,
"slowness": false,
"strength": true,
"fireResistance": false,
"poison": false,
"wither": false,
"regeneration": false,
"resistance": false,
"invisibility": false,
"waterBreathing": false,
"absorption": false,
"activeEffectCount": 1
},
"threat": {
"targetEntityHostile": true,
"targetDistance": 3.2,
"nearestHostileDist": 3.2,
"nearestHostileYaw": 45.0,
"hostileCount": 3
}
}
游戏状态字段说明
来自 MCCTP 的字段(heldItem、offhandItem、playerState 基础字段、combatContext 基础字段)已在 MCCTP README 中记录。MCSTP 新增以下内容:
playerState(扩展版):
| 字段 | 类型 | 描述 |
|---|---|---|
experienceLevel |
int | 当前经验等级 |
experienceProgress |
float | 下一级进度 (0-1) |
totalExperience |
int | 总经验点数 |
combatContext(扩展版):
| 字段 | 类型 | 描述 |
|---|---|---|
crosshairDistance |
float | 准星目标距离(未命中时为 -1) |
crosshairEntityHealth |
float | 目标实体生命值(非活体时为 -1) |
crosshairEntityMaxHealth |
float | 目标实体最大生命值(非活体时为 -1) |
playerInput:
| 字段 | 类型 | 描述 |
|---|---|---|
movementForward |
float | 前后移动输入 (-1 到 1) |
movementSideways |
float | 左右移动输入 (-1 到 1) |
jump |
bool | 跳跃键是否按住 |
sprint |
bool | 疾跑键是否按住 |
sneak |
bool | 潜行键是否按住 |
attack |
bool | 攻击键是否按住 |
useItem |
bool | 使用键是否按住 |
drop |
bool | 丢弃键是否按住 |
swapOffhand |
bool | 切换副手键是否按住 |
openInventory |
bool | 打开物品栏键是否按住 |
yawDelta |
float | 自上一刻以来的水平旋转变化量(度) |
pitchDelta |
float | 自上一刻以来的垂直旋转变化量(度) |
screenState:
| 字段 | 类型 | 描述 |
|---|---|---|
screenOpen |
bool | 任意 GUI 界面已打开 |
screenType |
string? | 界面类名(例如 "InventoryScreen"),或 null |
cursorX |
float | 归一化的游标 X 坐标 (0-1) |
cursorY |
float | 归一化的游标 Y 坐标 (0-1) |
mouseLeft |
bool | 按住鼠标左键 |
mouseRight |
bool | 按住鼠标右键 |
shiftHeld |
bool | 按住 Shift 键(用于 shift+点击) |
statusEffects:
| 字段 | 类型 | 描述 |
|---|---|---|
speed |
bool | 速度效果处于激活状态 |
slowness |
bool | 迟缓效果处于激活状态 |
strength |
bool | 力量效果处于激活状态 |
fireResistance |
bool | 抗性火焰效果处于激活状态 |
poison |
bool | 中毒效果处于激活状态 |
wither |
bool | 凋零效果处于激活状态 |
regeneration |
bool | 生命恢复效果处于激活状态 |
resistance |
bool | 抗性提升效果处于激活状态 |
invisibility |
bool | 隐身效果处于激活状态 |
waterBreathing |
bool | 水下呼吸效果处于激活状态 |
absorption |
bool | 伤害吸收效果处于激活状态 |
activeEffectCount |
int | 激活状态的总效果数量 |
threat:
| 字段 | 类型 | 描述 |
|---|---|---|
targetEntityHostile |
bool | 准星指向的目标为敌对生物 |
targetDistance |
float | 到准星指向目标的距离(若非敌对则为 -1) |
nearestHostileDist |
float | 16 格内最近敌对生物的距离(若无则为 -1) |
nearestHostileYaw |
float | 朝向最近敌对生物的偏航角(角度) |
hostileCount |
int | 16 格内的敌对生物数量 |
动作(客户端 → 服务器)
MCSTP 在 MCCTP 的 14 个基础动作之上,增加了两个用于 GUI 交互的动作:
| 动作 | 参数 | 描述 |
|---|---|---|
cursor |
x: float (0-1), y: float (0-1) |
将游标移动到归一化的屏幕位置。仅在打开界面时有效。 |
click |
button: "left" "right" |
在当前游标位置点击。仅在打开界面时有效。 |
动作示例
// 将游标移动到屏幕中心
{"action": "cursor", "params": {"x": 0.5, "y": 0.5}}
// 左键点击
{"action": "click", "params": {"button": "left"}}
// 右键点击
{"action": "click", "params": {"button": "right"}}
配置
配置文件:.minecraft/config/mcstp.json(首次启动时创建)
{
"tickInterval": 1
}
| 字段 | 默认值 | 描述 |
|---|---|---|
tickInterval |
1 | 每 N 刻广播一次游戏状态(20 刻 = 1 秒) |
当安装 MCSTP 时,这会覆盖 MCCTP 的刻间隔设置。
架构
任何客户端 ←── WebSocket (JSON) ──→ MCCTP (Fabric 模组)
│
├── WebSocketServer (Netty)
├── ConnectionManager
├── ActionDispatcher
│ ├── 14 个基础处理器 (移动、视角、跳跃、...)
│ ├── CursorHandler ← MCSTP
│ └── ClickHandler ← MCSTP
│
└── StateProviderRegistry
└── MCSTPStateProvider ← MCSTP
├── PlayerStateInfo (扩展)
├── HeldItemInfo + ItemCategorizer
├── CombatContextInfo (扩展)
├── PlayerInputInfo
├── ScreenStateInfo
├── StatusEffectInfo
└── ThreatInfo
关键实现细节:
- MCSTP 通过
MCCTPApi.registerModule("mcstp")向 MCCTP 注册 —— 这将其添加到握手过程中 - 状态收集实现了 MCCTP 的
StateProvider接口 —— MCCTP 每刻调用它并广播结果 - 动作处理器实现了 MCCTP 的
ActionHandler接口,并通过ActionDispatcher.registerHandler()注册 - 威胁扫描使用
getEntitiesByClass(HostileEntity.class)在 16 格的包围盒内进行搜索 - 界面状态直接读取 GLFW 的鼠标/按键状态
- 玩家输入使用
Input.getMovementInput()获取移动向量,并使用GameOptions的按键绑定获取按钮状态
从源码构建
# 必须先构建 MCCTP
cd mcctp
./gradlew build
# 然后构建 MCSTP
cd ../MCSTP
./gradlew build
# 输出 jar 包
build/libs/mcstp-1.0.0.jar
构建目标为 Java 21。已在 Gradle 9.2.0 和 Fabric Loom 1.15.3 上测试。
Python 客户端
python/ 目录中包含一个 Python 包。为完整的游戏状态提供类型化的 dataclass:
import time
from mcctp import SyncMCCTPClient, Actions
from mcstp import GameState
from mcstp import Actions as MCSTPActions
with SyncMCCTPClient("localhost", 8765) as client:
def on_state(data: dict):
state = GameState.from_dict(data)
print(f"HP: {state.player_state.health} | Hostiles: {state.threat.hostile_count}")
if state.combat_context.crosshair_target == "ENTITY":
print(f" Target: {state.combat_context.crosshair_entity_type} "
f"({state.combat_context.crosshair_entity_health} HP)")
client.on_state(on_state)
# MCCTP 动作正常工作
client.send(Actions.move("forward", "start"))
time.sleep(2)
client.send(Actions.move("forward", "stop"))
# MCSTP 为 GUI 增加游标/点击功能
client.send(Actions.open_inventory())
time.sleep(0.1)
client.send(MCSTPActions.cursor(0.5, 0.3))
client.send(MCSTPActions.click("left"))
GameState.to_control_dict() 返回一个扁平字典,包含用于决策的最有用字段(生命值、位置、手持物品、准星目标、敌对生物数量、屏幕状态)。
许可证
MIT
你是这个资源的作者?登录后可认领此资源。
相似资源
缓冲的原始输入和线程化的事件轮询
一个用于收集生物掉落物的多区块模组。
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
可定制的鞘翅模组,支持装饰纹饰、旗帜图案等更多功能!
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
查看物品与配方
评论 0
登录后参与评分
还没有评论,来抢沙发吧