MCSTP

模组

· 作者 lucasoyen

用于 MCCTP 的丰富游戏状态遥测插件。每秒通过 WebSocket 广播玩家统计信息、战斗上下文、威胁扫描、输入状态、屏幕信息和状态效果。

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

需要前置:MCCTP

最新 1.1.0 · 1.21.11 · Fabric

一键开服(送7天)

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

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源