更新日志
本页记录文档与客户端接口的变更。协议版本、Python 版本这类环境事实也在这里同步, 避免文档与源码漂移。
2026-11 更新
新增:vtapi 静默只读查询库
纯 Python 插件库,不需要改 C++、不需要重新编译,用 engine.settingscommand() 发 tellraw、再用 on_text 收服务端展开的 selector / score 结果:
| 能力 | 入口 |
|---|---|
| 背包物品数量 | vtapi.bag.has() / count() / count_many() |
| 计分板分数 | vtapi.score.get() / get_many() |
| 玩家坐标 | vtapi.pos.get() / scan() / watch() / block() |
查询不产生命令回执、不刷屏、不受 sendCommandFeedback 影响。完整说明见 vtapi 静默只读查询库。
增强:engine 命令函数支持命令来源
三个函数都新增了可选参数,旧调用完全兼容(默认值 = 原来的行为):
| 函数 | 新签名 | 新增参数 |
|---|---|---|
engine.command | command(command, origin=0) | origin:packets.CommandOrigin 枚举值 |
engine.command_guid | command_guid(command, guid, origin=0) | origin:同上 |
engine.settingscommand | settingscommand(command, suppress_output=False) | suppress_output:是否要求服务端抑制输出 |
suppress_output=True 会被踢
实测 settingscommand(cmd, True) 会让服务端以 reason 55(netease.report.kick.hint) 踢出机器人,线上请保持默认 False。
origin 的作用与实测结果见命令回执机制。默认 0(Player) 与旧行为一致;CommandBlock / Scripting 会被服务端踢出,AutomationPlayer 返回 commands.generic.invalidOrigin。
增强:packets.CommandRequest 的来源字段可控
packets 模块中的 CommandRequest(77) 现在真正把来源写进包:
| 变更 | 说明 |
|---|---|
SetCommandOrigin(origin) | 之前是空操作(序列化恒写 player),现在会映射成对应 origin 字符串 |
SetOriginName(name) / GetOriginName() | 新增,直接指定线上 origin 字符串;空串 = 按枚举映射 |
SetRandomUUID(guid) | 统一校验必须 16 字节,否则抛 PacketError |
CommandOrigin 枚举 | 16 个取值:Player / CommandBlock / MinecartCommandBlock / DevConsole / Test / AutomationPlayer / ClientAutomation / DedicatedServer / Entity / Virtual / GameArgument / EntityServer / Precompiled / GameDirectorEntityServer / Scripting / ExecuteContext |
GetPacketID() / Serialize() / Send() | 保持不变,Send() 等价于 engine.send(req.Serialize()) |
网易版 origin 是字符串
CommandRequest(77) 的 origin 字段在网易协议里是 UTF-8 字符串,不是原版的 varint 枚举。 所以 SetCommandOrigin() 只是把枚举映射成字符串,最终上线的是 SetOriginName() 的值。
修正:协议版本与游戏版本
| 项 | 旧文档 | 当前代码(application/application.cpp) |
|---|---|---|
协议版本 ProtocolVersion | 860(MCBE 1.21.120) | 898(MCBE 1.21.130) |
游戏版本 MinecraftBedrockGameVersion | 1.21.120 | 1.21.130 |
--protocol 默认值 | 860 | 898 |
修正:嵌入 Python 的方式
旧文档写的是“必须在本机安装 Python 3.12(含 Development 组件),并由 find_package(Python3 3.12 COMPONENTS Development REQUIRED) 定位”。
当前 application/CMakeLists.txt 的做法是:
set(PY312_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../third_party/python312")
add_library(Python3::Python SHARED IMPORTED)
set_target_properties(Python3::Python PROPERTIES
IMPORTED_IMPLIB "${CMAKE_CURRENT_SOURCE_DIR}/../third_party/python312/python312.lib"
IMPORTED_LOCATION "${CMAKE_CURRENT_SOURCE_DIR}/../third_party/python312/python312.dll"
INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}/../third_party/python312/include")也就是说:
- 解释器与头文件随仓库自带(
third_party/python312),不再依赖本机 Python 安装 - 仓库当前只带
include/与python312.def,需要先用lib.exe从.def生成python312.lib,再从官方 Python 3.12.2 复制python312.dll进同目录 - 嵌入式解释器与普通 CPython 3.12 的 ABI 一致,
cp312wheel 可以直接装了用
详见构建与Python 运行时与扩展。
修正:模块数量
运行时注册的内置模块是 19 个(部分旧文档写 15 个): engine、setting、mod_log、utility、pkt、aes、_chacha、_websocket、 rotor、fop、_client、client_instance、easy_utils、_raknet、 tan_lobby_game_clicpp_wrapper、api_errors、nbt、packets、game_state。
兼容性
- 本次所有
engine变更都是新增可选参数,旧插件代码无需修改。 packets.CommandRequest的 setter 名字与参数未变;唯一的行为变化是SetCommandOrigin()现在真的生效(不调用时仍默认player,与旧行为一致)。SetRandomUUID()现在强制 16 字节。旧代码若传了非 16 字节数据,会从“静默补零” 变成抛PacketError。
