命令回执机制
用 engine.command_guid() 发指令时,回执能不能收到、会不会刷屏,取决于命令来源(origin) 和 gamerule sendCommandFeedback 的组合。这一页说明回执的真实链路、实测门控矩阵, 以及“静默执行 + 拿到回执”的几种可行做法。
问题现象
| 用法 | 执行 | 回执 | 副作用 |
|---|---|---|---|
engine.command_guid(),sendCommandFeedback=true | ✅ | ✅ 能收到 on_command_output | 管理员能看到全部回执,可能刷屏 |
engine.command_guid(),sendCommandFeedback=false | ✅ | ❌ 收不到 | 静默 |
engine.settingscommand() | ✅ | ❌ 永远收不到 | 完全静默,管理员也看不到 |
也就是说:普通玩家来源的指令回执被 gamerule 门控,而 settingscommand 走的是完全不 产生 CommandOutput 的另一条路。要同时满足“静默”和“有回执”,需要换通道或换来源。
回执链路
插件
└─ 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 取值
| 值 | 名称 | 含义 |
|---|---|---|
1 | LastOutput | 命令方块的“上一个输出”,会写进方块数据 |
2 | Silent | 静默回执:只发给命令发起者,不广播 |
3 | AllOutput | 完整回执:既发给发起者,也按 gamerule 广播 |
gamerule 门控(实测)
在房间 24350(MCBE 1.21.130 网易版)逐项验证:
sendCommandFeedback | AllOutput(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,按指令分类取回执
适合只需要“查询类 + 错误”反馈的场景:
engine.command_guid('/list', guid, 0) # 有 Silent 回执
engine.command_guid('/give @s stone', guid, 0) # 无回执,但确实执行了配合 engine.settingscommand('/gamerule sendCommandFeedback false') 关闭广播。 优点是零额外开销;缺点是有副作用的指令拿不到结果。
方案 B:用游戏状态代替回执
需要“确认结果”的写操作,读状态比等回执更可靠:
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
需要拿到“执行结果文本”又不想广播时,可以让命令方块执行指令,再读方块数据:
engine.command_update(...)更新命令方块(包 78)engine.openContainer(x, y, z)或game_state.get_block_actor(x, y, z)读LastOutput
这条通道不受 sendCommandFeedback 影响,但需要提前在世界里放好命令方块, 且每次执行有红石 / 条件限制。
自定义 CommandRequest
需要更细的控制时可以绕过 engine 直接构造包(packets 模块):
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):
| 字段 | 类型 | 说明 |
|---|---|---|
origin | dict | {origin, uuid, request_id, player_unique_id} |
output_type | int | 见上方取值表 |
success_count | int | 成功执行的子命令数量 |
messages / output_messages | list | 每条 {success, message, parameters} |
data_set | str | 数据集(通常为空串) |
on_command_output 收到的是精简版:[messages, guid],其中 messages 为 [[翻译键, [参数...]], ...]。
下一步
- engine API:
command_guid/settingscommand/ 结构化协议事件签名 - 协议数据包:
OnTextPacket、结构化事件 79 的解析 - vtapi:不依赖回执的静默查询通道
