Skip to content

使用 ProtocolLib

警告

协议管理器是一个可选的管理器。只有在启用 PySpigot 插件时服务器上存在 ProtocolLib 插件时，才应访问该管理器。

PySpigot 包含一个管理器，用于在脚本中处理数据包如果您希望在脚本中处理数据包。

关于将占位符管理器导入到您的脚本的说明，请访问 通用信息 页面。

协议管理器使用

有多个函数可用于注册和注销数据包监听器的协议管理器。

  • registerPacketListener(function, packet_type)
  • registerPacketListener(function, packet_type, listener_priority): listener_priority represents the priority of the listener. It's similar to EventPriority for Bukkit events.
  • unregisterPacketListener(packet_listener): Requires a packet listener obtained from one of the register functions.
  • createPacket(packet_type): Generates and provides a packet based on the specified type.
  • sendServerPacket(player, packet): Dispatches a packet to the designated player.
  • broadcastServerPacket(packet): Relays a packet to all players on the server.
  • broadcastServerPacket(packet, entity): Sends the packet to all players currently observing the specified entity.
  • broadcastServerPacket(packet, entity, include_tracker): Sends the packet to all players observing the entity. includeTracker indicates whether the entity itself should also receive the broadcast, e.g., true or false.
  • broadcastServerPacket(packet, origin, max_observer_distance): Broadcasts the packet to players within a specified maximum observer distance from the center point (origin).
  • broadcastServerPacket(packet, target_players): Shares the packet with a specific group of target players.
提示

异步监听器

协议管理器还支持注册异步监听器。异步监听器允许您延迟数据包传输，等等。您还可以注册超时监听器，用于处理发送超时的数据包。

要获取异步协议管理器，请调用async()。例如，

1
2
3
import pyspigot as ps

async_manager = ps.protocol.async()

以下函数可从异步协议管理器中使用：

  • registerAsyncPacketListener(function, packet_type)
  • registerAsyncPacketListener(function, packet_type, listener_priority)
  • registerTimeoutPacketListener(function, packet_type)
  • registerTimeoutPacketListener(function, packet_type, listener_priority)
  • unregisterAsyncPacketListener(packet_listener): 通过其中一个注册函数返回的数据包监听器。
Note

有关异步和超时监听器的详细信息，请参阅ProtocolLib的文档。

代码示例

让我们看一下以下定义并注册聊天数据包监听器的代码：

1
2
3
4
5
6
7
8
9
import pyspigot as ps # (1)!
from com.comphenix.protocol import PacketType # (2)!

def chat_packet_event(event): # (3)!
    packet = event.getPacket() # (4)!
    message = packet.getStrings().read(0) # (5)!
    print(f'玩家发送了一条消息！他们的消息是：{message}')

packet_listener = ps.protocol.registerPacketListener(chat_packet_event, PacketType.Play.Client.CHAT) # (6)!

  1. 在这里，我们将PySpigot作为ps导入，以便使用协议管理器（protocol）。

  2. 这里，我们从 ProtocolLib 中导入 PacketType。这将用于定义我们要监听的数据包。

  3. 在这里，我们定义了函数 chat_packet_event，这是一个在被拦截的数据包传入时被调用的函数。此函数有一个参数 event，代表发生的事件（接收到的聊天数据包）。

  4. 这里，我们获取被拦截的数据包，并将其赋值给 packet。

  5. 在这里，我们从数据包中读取数据（聊天消息），接着在下一行打印被拦截的消息。

  6. 在这里，我们调用协议管理器来注册数据包监听器，传入我们在第 5 行定义的函数 chat_packet_event 以及我们要监听的数据包 PacketType.Play.Client.CHAT，并将返回的值赋给 packet_listener。

所有数据包监听器都必须在 PySpigot 的协议管理器中注册。注册数据包监听器与在 PySpigot 的监听器管理器中注册事件监听器非常相似，只是在注册函数中传递的是数据包类型，而不是事件。

  • 第一个参数接受应在拦截数据包时调用的函数。
  • 第二个参数接受要监听的数据包类型。

registerPacketListener 函数返回一个 ScriptPacketListener，代表已注册的数据包监听器。这可以在以后的时间用于取消注册数据包监听器。

阅读有关可用数据包类型的完整列表，请查看PacketType类。数据包类型根据游戏过程中发送/接收的阶段被分为几种类型：Configuration（配置）、Handshake（握手）、Login（登录）、Play（游戏）和Status（状态）。每个类别根据数据包的起源是客户端还是服务器进一步细分为Client（客户端）和Server（服务器）。

取消注册数据包监听器

继续上述代码示例：

1
ps.protocol.unregisterPacketListener(listener) # (1)!
  1. 在这里，我们通过传递先前注册数据包监听器时分配的ScriptPacketListener对象来取消注册数据包监听器。

总结

  • 要为您的监听器定义数据包类型，您必须从ProtocolLib导入PacketType。
  • 所有数据包监听器应该被定义为脚本中的函数，这些函数接受一个参数，即数据包事件（参数名称可以是任意名称）。
  • 所有数据包监听器都必须向PySpigot的数据包管理器注册。可以通过多种方式完成这一操作，但最基本的方法是使用registerPacketListener(function, packet_type)。
  • 数据包监听器被异步调用。任何与Bukkit或PySpigot进行交互的代码应该是同步运行的。您可以通过使用任务管理器（runTask(function)）来实现这一点。
  • 在注册数据包监听器时，注册函数都会返回一个ScriptPacketListener，可以用于取消注册监听器。