Skip to content

结构化协议事件 ​

比手工 pkt.unpack 更省事:让 C++ 侧把包解析成 dict 再交给插件。

注册事件 ​

python
import engine

def on_packet(event):
    print(event["packet_id"], event["packet_name"], event["size"])
    if event["parsed"]:
        print(event["data"])
    elif event["error"] is not None:
        print("parse failed:", event["error"])

engine.register_structured_protocol_event(56, on_packet)

函数签名:

python
engine.register_structured_protocol_event(packet_id, callback, is_kernel=False)

第三个参数不要传 True

is_kernel 默认为 False。内核事件只应由框架自身注册,插件传 True 会与框架抢注册。

事件信封 ​

每次回调接收一个字典:

字段类型含义
packet_idint基岩版协议包 ID
packet_namestr已知包名,未知时为 Unknown
payloadbytes不含包 ID 的原始负载
sizeint原始负载长度
parsedbool是否已可靠解析为 data
datadict | None已解析字段;不支持解析时为 None
errorstr | None解析错误;没有错误时为 None

解析失败不会中断其他回调

解析异常会保留在 error 字段里,其他协议回调继续执行。

支持的包与字段 ​

包ID已解析字段
MovePlayer19entity_runtime_id、position{x,y,z}、pitch、yaw、head_yaw
ContainerOpen46window_id、window_type、position{x,y,z}、entity_unique_id
InventoryContent49window_id、slots、container_id、dynamic_container_id
BlockActorData56position{x,y,z}、raw_nbt、nbt、root_name
PlayStatus2status
Text9type、data、data2、system_message
CommandOutput79origin、request_id、output_type、success_count、messages、data_set
PlayerList63action、entries

其他包仍会提供完整事件信封和 payload,但 parsed 为 False、data 为 None。

字段详解 ​

MovePlayer ​

python
{
    "entity_runtime_id": 123,
    "position": {"x": 0.0, "y": 64.0, "z": 0.0},  # float
    "pitch": 0.0,
    "yaw": 0.0,
    "head_yaw": 0.0,
}

ContainerOpen ​

python
{
    "window_id": 2,
    "window_type": 0,
    "position": {"x": 106, "y": 93, "z": 69},     # int
    "entity_unique_id": 0,
}

InventoryContent ​

python
{
    "window_id": 2,
    "slots": [
        {
            "network_id": 276,
            "count": 1,
            "metadata": 0,
            "block_runtime_id": 0,
            "stack_id": 0 | None,
            "extra": b"",
        }
    ],
    "container_id": 0,
    "dynamic_container_id": 0 | None,
}

BlockActorData ​

python
{
    "position": {"x": 106, "y": 93, "z": 69},
    "raw_nbt": b"...",
    "nbt": nbt.Tag | None,
    "root_name": "..." | None,
}

NBT 解析失败时 nbt / root_name 为 None,错误写入事件信封的 error, parsed 为 False。

PlayStatus ​

python
{"status": 3}

Text ​

python
{
    "type": 1,                 # CHAT
    "data": "<玩家名>",         # chat/whisper/announcement 时是 source_name
    "data2": "消息内容",        # chat/whisper/announcement 时是 message
    "system_message": "",      # filtered_message
}

对非聊天类文本,data 是消息正文,data2 为空字符串。需要完整字段 (parameters、xuid、platform_chat_id、needs_translation)时,使用 TextParsed 原生事件或 register_protocol_event(9, ...) 自己解析。

CommandOutput ​

python
{
    "origin": 0,               # 当前实现固定为 Player
    "request_id": "...",
    "output_type": 1,          # 0 none / 1 lastoutput / 2 silent / 3 alloutput / 4 dataset
    "success_count": 1,
    "messages": [
        {"success": False, "message": "commands.give.success"}
        # 注意:结构化事件不包含 parameters
    ],
    "data_set": "",
}

需要 parameters 时使用 CommandOutputParsed 原生事件(见事件系统)。

PlayerList ​

python
{
    "action": 0,               # 0 add / 1 remove
    "entries": [
        {
            "uuid": b"...",             # 16 字节
            "entity_unique_id": 123,
            "username": "...",
            "xuid": "...",
            "platform_chat_id": "...",
        }
    ],
}

PlayerList 的完整条目(含皮肤、build_platform、host 等)通过 on_player_list 原生事件获得,或使用 game_state.get_players()。

包名映射 ​

packet_name 当前能识别:

text
Login  PlayStatus  Disconnect  StartGame  MovePlayer
ContainerOpen  InventoryContent  BlockActorData
CommandRequest  CommandOutput  PlayerList
PlayerAuthInput  SubChunk  PyRpc

不在表中的包返回 Unknown。

示例:从 BlockActorData 里取命令方块指令 ​

python
import engine

def on_block_actor(event):
    if not event["parsed"]:
        return
    tag = event["data"]["nbt"]
    if tag is None:
        return
    command = tag.Get("Command")
    if command is not None:
        print(command.GetValue())

engine.register_structured_protocol_event(56, on_block_actor)

该用哪个接口? ​

场景用
上表 8 个包,只要字段register_structured_protocol_event
其他包 / 需要原始字节register_protocol_event + pkt
聊天消息OnTextPacket 或 TextParsed(见事件系统)

下一步 ​

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