ProtocolLib - 协议库

ProtocolLib 是一个用于读写 Minecraft 网络协议包的库。它通过反射和通道注入处理了大部分底层操作，并提供了简化的数据包修改接口，让插件开发者无需直接处理复杂的版本兼容问题。

💡概述

ProtocolLib 为 Bukkit/Spigot 服务器插件提供了直接访问和修改 Minecraft 网络数据包的能力。许多通过标准 API 无法实现的功能（如修改进出数据包、注入自定义数据包）都可以借助它来完成。它能够适应大多数 Minecraft 版本更新，减少了插件因版本更迭而需要频繁修改的工作量。

• 支持 Minecraft 1.8 至 1.21.8。
• 处理了反射和通道注入的复杂细节。
• 提供包装类以简化数据包操作。
• 通常在小版本更新（如 1.8 的安全更新）中无需修改。

🎮实用链接

• 发布版本：请使用最新的发布版本（镜像）。
• 源代码：可在 GitHub 查看。
• 问题追踪：请在 Issue Tracker 报告问题。
• JavaDoc：开发文档。
• 支持：在请求帮助前，请先查阅常见错误 Wiki 页面。

🔧安装与使用

对于服务器管理员

只需下载 ProtocolLib 的 jar 文件并放入服务器的 plugins 文件夹。它本身不提供游戏功能，而是作为其他插件运行的基础库。

对于开发者

Maven

如果您使用 Maven，可以从 Maven Central 自动下载 jar 包、JavaDoc 和源码。在 pom.xml 中添加依赖：

<dependency>
    <groupId>net.dmulloy2</groupId>
    <artifactId>ProtocolLib</artifactId>
    <version>5.4.0</version>
</dependency>

注意：之前的 groupId 为 com.comphenix.protocol，现已迁移至 net.dmulloy2。

Gradle

在 build.gradle 中声明仓库和依赖：

repositories {
    mavenCentral()
}
dependencies {
    compileOnly 'net.dmulloy2:ProtocolLib:5.4.0'
}

教程资源

• 一个稍旧的教程可供参考。
• 新的教程正在 Wiki 上编写中。

轻量替代方案

TinyProtocol 是一个轻量级的替代方案，主要用于发送和接收原始数据包，不包含结构修改器或包装类。您可以在 GitHub 上找到它。

⭐命令与权限

所有管理命令都需要 protocol.admin 权限。

主命令：/protocol

• config：重新加载配置文件。
• check：检查 BukkitDev 上是否有新版本。
• version：显示当前运行的 ProtocolLib 版本。
• timings：切换测量每个插件占用 CPU 时间的统计。
• listeners：显示哪些插件正在使用 ProtocolLib 以及它们拦截的数据包类型。

数据包日志命令：/packetlog

将指定数据包的十六进制表示记录到文件或控制台。

• 语法：/packetlog <protocol> <sender> <packet> [file/console]
• 可接受的数据包类型列表请参考相关文档。

✨配置选项

配置文件提供以下选项

全局设置

auto-updater:
  notify: true      # 当有新版本时，通知拥有 protocol.info 权限的玩家。
  download: false   # 是否自动下载并安装最新版本（重启后生效）。
  delay: 43200      # 检查更新的间隔时间（秒）。
  last: 0           # 上次检查的时间戳，设为 0 可强制立即检查。
metrics: true       # 是否向 mcstats.org 发送匿名使用统计。
background-compiler: true # 是否通过即时编译替换反射代码以提升性能。
ignore-version-check: [] # 强制 ProtocolLib 在指定的不兼容 Minecraft 版本上启动。

❓常见问题与支持

报告问题前

• 检查 ProtocolLib 是否有更新，您的问题可能已被修复。
• 阅读错误堆栈跟踪，确认问题源于 ProtocolLib（其包名包含 com.comphenix.protocol）。
• 查阅常见错误 Wiki 页面。

报告问题时

• 请使用 Issue Tracker，不要在评论中报告错误。
• 报告前请先搜索是否已有相同问题。
• 提供尽可能多的信息，包括 ProtocolLib 版本、Spigot 版本。
• 使用 Pastebin 等工具提供完整的错误堆栈跟踪。

🔧兼容性与原理

ProtocolLib 的主要目标之一是实现与不同 Minecraft 版本的最大兼容性。其实现非常灵活，能够适应未来的版本变化。

• 原理：基本没有硬编码的名称。所有字段、方法和类都是通过分析字段类型、包名或参数类型推断出来的，这在不同版本间具有高度一致性。
• 结果：除了包结构变化外，它对新版本具有很好的适应性，通常只需为修复错误或添加新功能而更新。

⭐示例插件

以下是一些使用 ProtocolLib 实现有趣功能的优秀插件，可供参考和启发：

• Holographic Displays
• Advanced Anti Cheat
• Server List Plus
• FurnitureLib
• AntiAura
• PremiumVanish

（如果您开发的插件也使用了 ProtocolLib 并希望加入此列表，请联系作者。）

✨统计与赞助

匿名统计

ProtocolLib 通过 BStats 收集匿名使用统计（如 Spigot 版本、Java 版本等），以帮助调整开发方向。参与完全自愿，您可以随时在配置中禁用。

赞助与捐赠

如果 ProtocolLib 极大地便利了您的工作，或者您想支持项目的长期维护，请考虑赞助或捐赠。这能支持作者投入的大量维护时间并保持其动力。

• 赞助：请通过 GitHub Sponsors 进行。
• 一次性捐赠：可通过 PayPal 完成。

衷心感谢所有赞助者和捐赠者！（名单略，如有遗漏或希望匿名，请联系作者。）

---

最后提醒：请不要在评论区提交错误报告，那里无法提供有效支持。请使用 Issue Tracker，以便作者能够诊断和修复问题。