Skip to content

命令回执机制 ​

用 engine.command_guid() 发指令时,回执能不能收到、会不会刷屏,取决于命令来源(origin) 和 gamerule sendCommandFeedback 的组合。这一页说明回执的真实链路、实测门控矩阵, 以及“静默执行 + 拿到回执”的几种可行做法。

问题现象 ​

用法执行回执副作用
engine.command_guid(),sendCommandFeedback=true✅✅ 能收到 on_command_output管理员能看到全部回执,可能刷屏
engine.command_guid(),sendCommandFeedback=false✅❌ 收不到静默
engine.settingscommand()✅❌ 永远收不到完全静默,管理员也看不到

也就是说:普通玩家来源的指令回执被 gamerule 门控,而 settingscommand 走的是完全不 产生 CommandOutput 的另一条路。要同时满足“静默”和“有回执”,需要换通道或换来源。

回执链路 ​

text
插件
 └─ engine.command_guid(cmd, guid[, origin])
     └─ CommandRequest(77)  ── origin 是字符串(不是数字枚举)
         └─ 服务端执行
             └─ CommandOutput(79)
                 ├─ origin / request_id / output_type / success_count / messages / data_set
                 └─ C++ CallbackManager::onIDCommandOutput
                     └─ 内核事件 CommandOutputParsed(raw_messages, guid, output_type, success_count, data_set)
                         └─ proton.py 转成用户事件 on_command_output([messages, guid])

两个事件名别混淆

CommandOutputParsed 是 C++ 内核事件(5 个参数,register_kernel_event,只有 proton.py 用); 插件监听的是 on_command_output(2 个参数:[messages, guid])。

messages 的每一项是 [翻译键, [参数...]],例如 ['commands.give.success.single', ['1', 'diamond', 'Steve']]。翻译键需要自己映射成中文, 或直接用 engine.register_structured_protocol_event(79, cb) 拿结构化的 output_type。

output_type 取值 ​

值名称含义
1LastOutput命令方块的“上一个输出”,会写进方块数据
2Silent静默回执:只发给命令发起者,不广播
3AllOutput完整回执:既发给发起者,也按 gamerule 广播

gamerule 门控(实测) ​

在房间 24350(MCBE 1.21.130 网易版)逐项验证:

sendCommandFeedbackAllOutput(3)Silent(2)LastOutput(1)
true下发下发下发
false降级为 Silent 仍下发下发丢弃

关键结论:

  • 关掉 gamerule 后,Silent 回执依然会到达,只是不再广播 —— 这正是“静默 + 有回执”的 基础。
  • 但不是所有指令都会产生 Silent 回执。大量“有副作用”的指令在 output_type=2 下 既执行成功、也不回任何消息(服务端根本不发 CommandOutput)。
  • 因此“关掉 gamerule 就一定能拿到回执”是不成立的,必须按指令分类处理。

哪些指令会给 Silent 回执 ​

类别指令有回执
查询 / 列表list、help、version、seed、getpos、difficulty、scoreboard objectives list✅
反馈类tell、tellraw、gamerule 成功提示✅
错误全部语法错误、权限错误✅
有副作用give、clear、effect、tag、time、weather、tp、gamemode、xp、scoreboard add/remove、say、me、gamerule 查询❌ 执行生效但无回执

不要用“有没有回包”判断执行成功

对于上表第二类指令,没有回执不代表失败。需要确认结果时请读游戏状态: game_state.get_inventory()、pos.get() 或 vtapi 的 bag / score 查询。

其它发送方式的实测结果 ​

command_guid() 的第三个参数(engine.command() 的第二个参数)可以指定 origin。 网易协议把 origin 当作字符串发送,服务端对未知来源的处理很严格:

origin结果
CommandOrigin.Player(0,默认)正常执行;回执受 gamerule 门控(上表)
CommandOrigin.CommandBlock / Scripting进服后立即被踢,reason 90
CommandOrigin.AutomationPlayer返回 commands.generic.invalidOrigin,不执行
CommandOrigin.ClientAutomation静默执行、无回执;带 tell 类指令会被踢(reason 90)
engine.settingscommand()执行生效;永远不产生 CommandOutput
settingscommand(cmd, suppress_output=True)被踢,reason 55(netease.report.kick.hint)
unlimit=True / internalSource=True彻底无回执
execute as @s run ...不改变门控结果

别用 CommandBlock / Scripting 来源

这两个字符串在当前服务端会被判定为非法来源并直接踢出(reason 90)。SetOriginName() 可以写任意字符串,但只建议用于测试,线上请保持默认 player。

推荐做法 ​

方案 A:关 gamerule,按指令分类取回执 ​

适合只需要“查询类 + 错误”反馈的场景:

python
engine.command_guid('/list', guid, 0)           # 有 Silent 回执
engine.command_guid('/give @s stone', guid, 0)  # 无回执,但确实执行了

配合 engine.settingscommand('/gamerule sendCommandFeedback false') 关闭广播。 优点是零额外开销;缺点是有副作用的指令拿不到结果。

方案 B:用游戏状态代替回执 ​

需要“确认结果”的写操作,读状态比等回执更可靠:

python
import vtapi

before = vtapi.bag.count('Steve', 'minecraft:stone')['count']
engine.settingscommand('/give Steve minecraft:stone 1')
after = vtapi.bag.count('Steve', 'minecraft:stone')['count']

vtapi 的 bag / score / pos 都不经过命令回执,不受 gamerule 影响,详见 vtapi 静默只读查询库。

方案 C:命令方块 + LastOutput ​

需要拿到“执行结果文本”又不想广播时,可以让命令方块执行指令,再读方块数据:

  1. engine.command_update(...) 更新命令方块(包 78)
  2. engine.openContainer(x, y, z) 或 game_state.get_block_actor(x, y, z) 读 LastOutput

这条通道不受 sendCommandFeedback 影响,但需要提前在世界里放好命令方块, 且每次执行有红石 / 条件限制。

自定义 CommandRequest ​

需要更细的控制时可以绕过 engine 直接构造包(packets 模块):

python
import packets

req = packets.CommandRequest()
req.SetCommand('/list')
req.SetCommandOrigin(packets.CommandOrigin.Player)   # 枚举 -> 映射成 origin 字符串
req.SetRandomUUID(guid)                              # 必须是 16 字节,否则抛 PacketError
req.SetRequestID('')                                 # 可选
req.Send()                                           # 等价于 engine.send(req.Serialize())

# 想直接指定线上的 origin 字符串(例如测试其它来源):
req.SetOriginName('player')                          # 空串 = 按 SetCommandOrigin 的枚举映射
print(req.GetOriginName())

origin 是字符串

网易版 CommandRequest(77) 的 origin 字段是 UTF-8 字符串(player / commandblock / scripting …),不是原版的 varint 枚举。SetCommandOrigin() 只负责映射成对应字符串, 真正上线的是 SetOriginName() 的值。

CommandRequest 完整字段:command、origin / origin_name、UUID、request_id、 player_id、internal_source、command_version、unlimit,以及 Serialize() / Send() / GetPacketID()。类型声明见 application/PythonAPI/Stubs/packets.pyi。

回执字段参考 ​

CommandOutput(79) 解析后的字段(结构化事件 79 或 on_command_output):

字段类型说明
origindict{origin, uuid, request_id, player_unique_id}
output_typeint见上方取值表
success_countint成功执行的子命令数量
messages / output_messageslist每条 {success, message, parameters}
data_setstr数据集(通常为空串)

on_command_output 收到的是精简版:[messages, guid],其中 messages 为 [[翻译键, [参数...]], ...]。

下一步 ​

  • engine API:command_guid / settingscommand / 结构化协议事件签名
  • 协议数据包:OnTextPacket、结构化事件 79 的解析
  • vtapi:不依赖回执的静默查询通道

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