Skip to main content

虚拟展示物品发包系统

概览​

这个项目的发包系统可以实现 Minecraft 中虚拟展示物品的创建、处理及转移发包。 它将基本的复杂网络抽象化，允许多版本的游戏无缝集成。

本文档将会指引开发者了解组件，实现细节，以及发包系统的用法。

关键组件​

1. PacketHandler​

  • 目的：管理发包处理及初始化逻辑。
  • 接口: PacketHandler<T>
  • 核心方法：
    • Map<String, PacketFactory<?>> factories()
      • 返回支持的 PacketFactory 映射表实例，以游戏版本为键名。
    • void initialize()
      • 初始化包处理器。
    • Optional<PacketFactory<?>> factory(String version)
      • 根据游戏版本返回 PacketFactory。

2. PacketFactory​

  • 目的：创建发送指定类型的包。
  • 接口: PacketFactory<T>
  • 支持的包：
    • 生成数据包：
      • 在指定位置生成虚拟物品。 通常使用 createSpawnPacket() 创造。
      • 示例用法：展示商店物品。
    • 元数据包：
      • 更新实体的元数据，例如外观或名称。 使用 createMetaDataPacket() 创建。
      • 示例用法：更新物品显示名称或其属性。
    • 速度数据包：
      • 为实体分配运动或速度。 使用 createVelocityPacket() 创建。
      • 示例用法：虚拟物品的自定义动画。
    • 删除数据包：
      • 从客户端视角移除实体。 使用 createDestroyPacket() 创建。
      • 示例用法：取消上传或删除虚拟展示物品。

实现自定义 PacketFactory 的开发者应确保这些数据包得到正确处理和优化。

3. VirtualDisplayItemManager​

  • 目的：监督虚拟展示物品的生命周期并与数据包处理器集成。
  • 核心方法：
    • 注册并初始化 PacketHandler 实例（例如ProtocolLibHandler 和 `PacketEventsHandler）。
    • 管理映射到区块的虚拟展示物品。
    • 提供用于添加和删除显示项的线程安全操作。

4. VirtualDisplayItem​

  • 目的：代表显示给玩家的虚拟物品。
  • 核心方法：
    • 生成和缓存数据包用于生成、元数据、速度和销毁方法。
    • 管理每个玩家的数据包发送程序。
    • 动态处理生成和移除操作。

5. ProtocolLibHandler 与 PacketEventsHandler​

  • 目的：分别使用 ProtocolLib 和 PacketEvents 提供 PacketHandler 的实现。
  • 区别：
    • ProtocolLibHandler 使用了 ProtocolLib API。
    • PacketEventsHandler 则使用 PacketEvents 库。

扩展协议系统​

有扩展或自定义协议系统需求的开发者可以遵循以下步骤：

实现新的 PacketHandler​

/**
 * PacketHandler 的自定义实现。
 * 可以初始化并管理不同版本的包工厂。
 *
 * @param <T> 为发包库使用的内部 API 实例。
 */
public class CustomPacketHandler implements PacketHandler<T> {
    
    private final Map<String, PacketFactory<?>> factories = new HashMap<>();
    
    @Override
    public Map<String, PacketFactory<?>> factories() {
        return factories;
    }

    @Override
    public String identifier() {
        return "customHandler";
    }

    @Override
    public String pluginName() {
        return "CustomPacketPlugin";
    }

    @Override
    public void initialize() {
        factories.put("1.22", new CustomPacketFactory());
    }
}

实现新的 PacketFactory​

/**
 * PacketFactory 的自定义实现。
 * 提供为指定游戏版本创建与发包的方法。
 */
public class CustomPacketFactory implements PacketFactory<CustomPacket> {

    @Override
    public CustomPacket createSpawnPacket(int id, @NotNull Location displayLocation) {
        return new CustomPacket("spawn", id, displayLocation);
    }

    @Override
    public CustomPacket createMetaDataPacket(int id, @NotNull ItemStack itemStack) {
        return new CustomPacket("metadata", id, itemStack);
    }

    @Override
    public boolean sendPacket(@NotNull Player player, @NotNull CustomPacket packet) {
        player.sendMessage("正在发包: " + packet.getType());
        return true;
    }
}

支持的游戏版本​

通过两个主要实现提供特定游戏版本的数据包工厂：

  • ProtocolLib：
    • 版本：1.20.1 - 1.21.4
    • 工厂：PacketFactoryv1_20、PacketFactoryv1_21
  • PacketEvents：
    • 版本：1.20.1 - 1.21.4
    • 工厂：PacketFactoryv1_20、PacketFactoryv1_21

最佳做法​

  1. 在清理过程中，总是取消注册区块监听器(unregisterSendChunk, unregisterUnloadChunk)。
  2. 在 VirtualDisplayItemManager 中使用线程安全方法修改映射。
  3. 确保数据包库（ProtocolLib、PacketEvents）更新到最新版本。

资源​

联系​

如需进一步援助，请联系开发团队，或参考源代码来详细执行工作。