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 实现有趣功能的优秀插件，可供参考和启发：
（如果您开发的插件也使用了 ProtocolLib 并希望加入此列表，请联系作者。）
统计与赞助
匿名统计
ProtocolLib 通过 BStats 收集匿名使用统计（如 Spigot 版本、Java 版本等），以帮助调整开发方向。参与完全自愿，您可以随时在配置中禁用。
赞助与捐赠
如果 ProtocolLib 极大地便利了您的工作，或者您想支持项目的长期维护，请考虑赞助或捐赠。这能支持作者投入的大量维护时间并保持其动力。
- 赞助：请通过 GitHub Sponsors 进行。
- 一次性捐赠：可通过 PayPal 完成。
衷心感谢所有赞助者和捐赠者！（名单略，如有遗漏或希望匿名，请联系作者。）
---
最后提醒：请不要在评论区提交错误报告，那里无法提供有效支持。请使用 Issue Tracker，以便作者能够诊断和修复问题。
