
MCSTP
MCCTP 的丰富游戏状态遥测插件。每 tick 通过 WebSocket 广播玩家统计数据、战斗上下文、威胁扫描、输入状态、屏幕信息和状态效果。
MCSTP - Minecraft 状态传输协议
一个 Fabric 模组,为 MCCTP 增加全面的游戏状态遥测功能。它每个游戏刻都会通过 MCCTP 的 WebSocket 广播丰富的状态快照——玩家信息、战斗上下文、威胁扫描、输入状态、屏幕状态、状态效果等等。
功能
- 每个刻的完整游戏状态 —— 位置、生命值、物品栏、战斗、威胁、输入、屏幕、状态效果
- 威胁扫描 —— 检测 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
将 build/libs/ 中的两个 JAR 复制到你的 .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 | 当前 XP 等级 |
experienceProgress |
float | 到下一级的进度(0-1) |
totalExperience |
int | 总 XP 点数 |
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 格内敌对生物的数量 |
操作(客户端 → 服务器)
在 MCCTP 的 14 个基础操作之上,MCSTP 增加了两个用于 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 的刻间隔。
架构
Any Client ←── WebSocket (JSON) ──→ MCCTP (Fabric Mod)
│
├── WebSocketServer (Netty)
├── ConnectionManager
├── ActionDispatcher
│ ├── 14 base handlers (move, look, jump, ...)
│ ├── CursorHandler ← MCSTP
│ └── ClickHandler ← MCSTP
│
└── StateProviderRegistry
└── MCSTPStateProvider ← MCSTP
├── PlayerStateInfo (extended)
├── HeldItemInfo + ItemCategorizer
├── CombatContextInfo (extended)
├── 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 actions work as normal
client.send(Actions.move("forward", "start"))
time.sleep(2)
client.send(Actions.move("forward", "stop"))
# MCSTP adds cursor/click for GUIs
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
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。