MCSTP

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