Skip to content

协议数据包 ​

处理聊天消息 ​

proton.py 已经注册了 TextPacket(0x09) 的内核协议事件,解析后触发 OnTextPacket 用户事件,插件直接监听即可:

python
def on_text(args):
    data = args[0]                    # dict
    if data['type'] == 1:             # CHAT
        source = data['source_name']  # str(Unicode)
        msg = data['message']         # str(Unicode)
        print(f'<{source}> {msg}')    # Py3 f-string,中文直接打印

engine.register(on_text, "OnTextPacket")

Py3 下不要 decode

source_name / message 已经是 str,不要再调用 .decode('utf-8') (str 根本没有这个方法)。

data 的完整字段和 type 取值见事件系统 · OnTextPacket。

处理其他数据包 ​

用 engine.register_protocol_event(packet_id, cb, False) 注册;回调收到的 data 是原始二进制(bytes,包 ID 已去除):

python
import pkt

def on_move_player(data):
    runtime_id, off = pkt.read_varint(data, 0)
    x, y, z, off = pkt.unpack("fff", data, off)
    print(f'entity {runtime_id} moved to {x:.1f}, {y:.1f}, {z:.1f}')

# 第三个参数 False = 用户协议事件,重载时自动清除
engine.register_protocol_event(0x13, on_move_player, False)

第三个参数必须是 False

True 是内核协议事件,只有 proton.py 可以用。插件传 True 会破坏框架自己的注册。

不用手写解析器:结构化协议事件 ​

如果只是想拿字段,不必自己 pkt.unpack。以下包已经支持结构化解析, engine.register_structured_protocol_event(id, cb) 会直接给 dict:

MovePlayer、ContainerOpen、InventoryContent、BlockActorData、 PlayStatus、Text、CommandOutput、PlayerList

python
def on_packet(event):
    if event["parsed"]:
        print(event["packet_name"], event["data"])

engine.register_structured_protocol_event(56, on_packet)

字段说明见结构化协议事件。

该用哪个? ​

场景用
聊天 / 系统消息OnTextPacket(已解析好)
上表那 8 个包register_structured_protocol_event(拿 dict)
其他包 / 需要原始字节register_protocol_event + pkt 手工解析
指令返回on_command_output 事件(配合 engine.command_guid)

常用包 ID ​

包ID
TextPacket0x09
MovePlayer0x13
ContainerOpenPacket46
InventoryContentPacket49
BlockActorDataPacket56
CommandBlockUpdate78
CommandRequest77
CommandOutput79

手动构造 CommandRequest(包 77) ​

需要指定命令来源、或自己控制 GUID 时,可以直接用 packets 模块构造并发送:

python
import packets

req = packets.CommandRequest()
req.SetCommand('/list')
req.SetCommandOrigin(packets.CommandOrigin.Player)   # 枚举:Player / CommandBlock / Scripting …
req.SetRandomUUID(guid)                              # 必须 16 字节,否则 PacketError
req.Send()                                           # 等价于 engine.send(req.Serialize())

网易协议里的 origin 是字符串(player / commandblock / scripting …): SetCommandOrigin() 传枚举,序列化时按内置表映射成字符串;SetOriginName() 可直接指定 线上字符串(传空串表示按枚举映射)。

origin 不能随便改

实测 commandblock / scripting 会被服务端秒踢(reason 90),automationplayer 返回 commands.generic.invalidOrigin,clientautomation 静默执行但不产生回执。保持 Player 最稳。

两个包的关系:CommandRequest(77) 是发出去的指令,CommandOutput(79) 是回执。回执可以用 on_command_output 事件,也可以用 engine.register_structured_protocol_event(79, cb) 拿结构化字段。 完整说明见命令回执机制。

下一步 ​

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