Skip to content

更新日志 ​

本页记录文档与客户端接口的变更。协议版本、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.commandcommand(command, origin=0)origin:packets.CommandOrigin 枚举值
engine.command_guidcommand_guid(command, guid, origin=0)origin:同上
engine.settingscommandsettingscommand(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)
协议版本 ProtocolVersion860(MCBE 1.21.120)898(MCBE 1.21.130)
游戏版本 MinecraftBedrockGameVersion1.21.1201.21.130
--protocol 默认值860898

相关页面(项目概览、构建、部署、 关键数据包)已同步。

修正:嵌入 Python 的方式 ​

旧文档写的是“必须在本机安装 Python 3.12(含 Development 组件),并由 find_package(Python3 3.12 COMPONENTS Development REQUIRED) 定位”。

当前 application/CMakeLists.txt 的做法是:

cmake
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 一致,cp312 wheel 可以直接装了用

详见构建与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。

下一步 ​

第三方库请参阅各自目录下的许可证文件