ProtocolLib
ProtocolLib 大部分功能已迁移至 Spigot!如需支持,请前往那里!
某些任务无法通过标准的 Bukkit API 完成,可能需要直接与 Minecraft 交互甚至修改其内容。一种常见的技术是修改传入和传出的数据包(packets),或者向数据流中注入自定义数据包。然而,这样做相当繁琐,并且大多数实现在 Minecraft 新版本发布后就会失效,这主要是由于代码混淆所致。
更为关键的是,使用这种方法的不同插件可能会挂钩到相同的类上,从而导致不可预测的结果。这种情况经常导致插件崩溃,但也可能引发更隐蔽的 bug。
链接
支持
如果您遇到了尚未报告的问题,请创建一个包含尽可能多信息的 issue。带有巨大堆栈跟踪的评论将被删除。
如果您需要关于API的帮助,请使用问题追踪器。如果您的提问出于任何原因(包括安全漏洞)不能公开,请给我发一条私信。
面向服务器操作员
只需从上面的链接下载 ProtocolLib。它本身不会执行任何操作,只是允许其他插件正常运行。
常见问题解答
- 为什么我在尝试读取或写入数据包时会遇到 FieldAccessExceptions?
引用:
出现这些异常的原因是 ProtocolLib 并未使用 Wiki 上描述的数据包格式,而是使用了这些数据包在内存中的表示形式。通常,内存中的表示形式会使用整数代替短整型和字节,并直接存储更复杂的对象(如 ItemStack)。
你可以通过 Minecraft 源代码 来推断内存中的表示方式,或者直接使用该库中我已经为你完成所有工作的 PacketWrapper。
示例
在主要支持论坛的 这个帖子 中可以找到使用 ProtocolLib 的一批示例程序的源代码。
你可能也会对 PacketWrapper 感兴趣,这是一个允许你在无需 反编译 Minecraft 源代码的情况下修改数据包(packet)的库。
最后,对于那些希望在使用 ProtocolLib(如果存在)的同时,仍保留自己的数据包监听系统的进阶用户,我建议你查看这个 帖子。我在其中解释了在哪里以及如何向 CraftBukkit 注入代码,以便自行拦截发送和接收的数据包。
Maven 仓库
如果你正在使用 Maven,你将能够自动从 Maven Central 下载 JAR 文件、JavaDoc 以及相关源码。你可以像这样将其添加为依赖项:
<dependencies>
<dependency>
<groupId>net.dmulloy2</groupId>
<artifactId>ProtocolLib</artifactId>
<version>5.4.0</version>
</dependency>
<!-- And so on -->
</dependencies>
命令
Protocol
主要的管理命令。支持以下子命令:
- config:重新加载配置文件。
- check:检查 BukkitDev 上的新版本。
- update:检查新版本并自动下载 JAR 文件。需要重启服务器才能使更改生效。
- timings:切换测量每个插件消耗的 CPU 时间。有关更多信息,请参阅 此处。
- listeners:显示哪些插件正在使用 ProtocolLib 以及它们正在拦截的数据包类型。
所有这些命令都需要 protocol.admin 权限。
示例:
数据包
添加或移除调试数据包监听器。这对于插件作者非常有用,可以查看数据包发送的时间及其内容。
子命令:
- add:添加具有给定数据包 ID 的监听器。
- remove:移除一个或多个具有给定数据包 ID 的监听器。
- names:打印每个给定数据包 ID 的名称。
参数(按顺序):
- 连接方向:client(客户端)或 server(服务端)。
- 多个 ID 范围:可以是单个数据包 ID(如 14),也可以是范围(如 10 - 15)。如果未指定,默认为 0 - 255。
- 详细模式:如果为 TRUE,则打印完整的数据包内容。
示例:
/packet add client 10-13 true
对于 3.0.0 及更高版本,你应该指定协议、发送者和名称,而不是:
/packet add play server chat true
在 3.4.0-SNAPSHOT 及更高版本中,你还可以在数据包被任何数据包监听器修改之前显示它:
/packet add play server chat compare
移除所有监听器:
/packet remove client
/packet remove server
注意,此命令在生产服务器上应很少使用。监听过多的数据包可能会导致服务器崩溃。
Filter
过滤系统(引入于 2.4.1)使用 JVM 6(Rhino)中的内置 JavaScript 解释器,通过扩展数据包命令来增加过滤功能——现在可以仅针对给定的实体 ID 打印实体元数据包事件(packet add server 40):
> packet add server 40 true
Added listener ListeningWhitelist{priority=MONITOR, packets=[40]}
> filter add entity_filter 40
Enter filter program ('}' to complete or CANCEL):
function(event, packet) {
> return packet.a == 1000;
>}
Added filter entity_filter.
这比不得不编译测试插件并重新加载整个服务器要方便得多。出于安全原因,此功能默认处于禁用状态。要启用它,请在 config.yml 中添加 "debug: true"。
Configuration
提供了一组小型配置选项:
Global section
| Option |
Default |
|
| auto updater.notify |
true |
当 ProtocolLib 有新版本发布时,通知拥有 protocol.info 权限的任何玩家。 |
| auto updater.download |
true |
自动下载并安装 ProtocolLib 的最新版本。安装将在服务器重启时生效。 |
| auto updater.delay |
43200 |
每次检查新更新之间的秒数。 |
| auto updater.last |
0 |
这仅记录上次执行更新检查的时间(自 1970 年 1 月 1 日以来的秒数)。将其设置为 0 以强制进行新的更新检查。 |
| metrics |
true |
如果为 TRUE,ProtocolLib 将向 mcstats.org 发布匿名使用数据。将其设置为 FALSE 以选择不加入。 |
| background compiler |
true |
如果为 TRUE,ProtocolLib 将尝试通过在运行时用编译代码替换反射来提高性能。 |
| ignore version check |
None |
强制 ProtocolLib 在指定的 Minecraft 版本上启动,即使它不兼容。 |
| suppressed reports |
None |
如果此列表中存在任何 错误或警告 报告,它们将不会出现在控制台或日志中。 |
有关更多信息,请参阅 默认配置文件。
Tutorial for developers
更多信息请参阅 此页面。
Compatibility
本项目的主要目标之一是实现与 Minecraft 的最大兼容性。最终结果相当不错,它能够抵御未来的变化。很可能除了修复错误和性能问题外,我不需要再更新 ProtocolLib。
这是如何实现的?归根结底,这都依赖于反射。本质上,没有任何名称是硬编码的——每个字段、方法和类都是通过查看字段类型、包名或参数类型推导出来的。它在不同版本之间表现出惊人的一致性。
(注意:以下列表已很久未更新,实际情况可能有所不同)
看似兼容的插件
已知兼容的插件
使用 ProtocolLib 的插件
不再活跃的项目
如果您希望我将您的插件添加到此列表中,请告诉我。:)
隐私
本插件使用 BStats 生成并发布匿名汇总使用统计数据,但您可以通过将 config.yml 中的 metrics 设置为 false 来轻松选择退出。
如果启用,每十分钟将发送以下内容:
- Metrics 修订版本号(当前为 6)。
- 服务器的 GUID
- 当前在线玩家数量(非最大玩家数)
- 服务器版本字符串(与你在 /version 命令中看到的相同)
- ProtocolLib 的当前版本
- 在 ProtocolLib 中注册数据包监听器的所有插件的名称。
捐赠
如果 ProtocolLib 让你的生活变得轻松许多,或者你最近心情不错、比较大方,不妨考虑捐赠!这是支持我多年来为这个插件投入的大量维护工作的好方法,也能让我保持动力。如果你经济条件不允许,请不要捐赠。
我要感谢所有在 BukkitDev 上向 ProtocoLib 捐赠的每一个人。我真的非常感激大家的支持。:)
注意:如果你遇到问题,请提交一个issue。我通常不会查看 BukkitDev 上的评论。
ProtocolLib
ProtocolLib has, for the most part, moved over to Spigot! If you need support, head over there!
Certain tasks are impossible to perform with the standard Bukkit API, and may require working with and even modify Minecraft directly. A common technique is to modify incoming and outgoing packets, or inject custom packets into the stream. This is quite cumbersome to do, however, and most implementations will break as soon as a new version of Minecraft has been released, mostly due to obfuscation.
Critically, different plugins that use this approach may hook into the same classes, with unpredictable outcomes. More than often this causes plugins to crash, but it may also lead to more subtle bugs.
Links
Support
Please create a issue with as much information as possible if you experience a problem that has not already been reported. Comments with a huge stack trace will be deleted.
If you need help with the API, please use the issue tracker. If your question cannot be made public for whatever reason (including security bugs), send me a personal message instead.
For server operators
Just download ProtocolLib from the link above. It doesn't do anything on its own, it simply allows other plugins to function.
FAQ
- Why do I get FieldAccessExceptions when I try to read or write from packets?
Quote:
The reason for these exceptions is because ProtocolLib is not using the packet format as described on the Wiki, it's using the in-memory representation of these packets. Often, the in-memory representation will use integers instead of shorts and bytes, and store more complex objects (like ItemStacks) directly.
You can figure out the in-memory representation from the Minecraft source code, or just use PacketWrapper where I've done all that work for you.
Examples
Source code for a bunch of example programs that use ProtocolLib can be found at this thread on the main support forum.
You may also be interested in PacketWrapper, a library that makes it possible to modify a packet without having to decompile the Minecraft source code.
Finally, for the more advanced users who want to use ProtocolLib if present, but still fall back on their own packet listening system, I recommend taking a look at this thread. I explain where and how to inject code into CraftBukkit in order to intercept sent and received packets yourself.
Maven repository
If you're using Maven, you'll be able to automatically download the JAR, JavaDoc and associated sources from Maven Central. You can add it as a dependency like so:
<dependencies>
<dependency>
<groupId>net.dmulloy2</groupId>
<artifactId>ProtocolLib</artifactId>
<version>5.4.0</version>
</dependency>
<!-- And so on -->
</dependencies>
Commands
Protocol
Main administrative command. Supports the following sub-commands:
- config: Reload the configuration file.
- check: Check for new versions on BukkitDev.
- update: Check for new versions and automatically download the JAR. The server must be restarted for this to take effect.
- timings: Toggle measuring the amount of CPU time spent by each plugin. See here for more information.
- listeners: Display what plugins are using ProtocolLib, and the packet types they are intercepting.
All of these commands require the permission protocol.admin.
Example:
Packet
Add or remove a debug packet listener. This is useful for plugin authors who just wants to see when a packet is sent, and with what content.
Sub commands:
- add: Add a packet listener with a given packet ID.
- remove: Remove one or every packet listener with the given packet IDs.
- names: Print the name of every given packet ID.
Parameters (in order):
- Connection side: Either client or server.
- Multiple ID ranges: Can be a single packet ID like 14, or a range like 10 - 15. Defaults to 0 - 255 if not specified.
- Detailed: If TRUE, prints the full packet content.
Example:
/packet add client 10-13 true
For 3.0.0 and above, you should specify the protocol, sender and name instead:
/packet add play server chat true
In 3.4.0-SNAPSHOT and above, you can also display the packet before its modified by any packet listeners:
/packet add play server chat compare
Remove all listeners:
/packet remove client
/packet remove server
Note that this command should rarely be used on a production server. Listening to too many packets may crash the server.
Filter
The filter system (introduced in 2.4.1) uses the built in JavaScript interpreter in JVM 6 (Rhino) to extend the packet command with filtering capabilities - it is now possible to, say, only print entity metadata packet events (packet add server 40) for a given entity ID:
> packet add server 40 true
Added listener ListeningWhitelist{priority=MONITOR, packets=[40]}
> filter add entity_filter 40
Enter filter program ('}' to complete or CANCEL):
function(event, packet) {
> return packet.a == 1000;
>}
Added filter entity_filter.
This should be much more convenient than having to compile a test plugin and reload the whole server. Note that this feature is disabled by default for security reasons. To enable it, add "debug: true" to config.yml.
Configuration
A small set of configuration options are available:
Global section
| Option |
Default |
|
| auto updater.notify |
true |
Inform any player with the permission protocol.info when a new version of ProtocolLib is out. |
| auto updater.download |
true |
Automatically download and install the newest version of ProtocolLib. The installation will take effect when the server restarts. |
| auto updater.delay |
43200 |
The number of seconds between each check for a new update. |
| auto updater.last |
0 |
This simply records the last time (in seconds since 01.01.1970) an update check was performed. Set it to 0 to force a new update check. |
| metrics |
true |
If TRUE, ProtocolLib will publish anonymous usage data to mcstats.org. Set it to FALSE to opt-out. |
| background compiler |
true |
If TRUE, ProtocolLib will try and improve performance by replacing reflection with compiled code on-the-fly. |
| ignore version check |
None |
Force ProtocolLib to start for a specified Minecraft version, even if it is incompatible. |
| suppressed reports |
None |
If any error or warning report is present in this list, they will not appear in the console or the log. |
For more information, take a look at the default configuration file.
Tutorial for developers
See this page for more information.
Compatibility
One of the main goals of this project was to achieve maximum compatibility with Minecraft. And the end result is quite good, it should be resilient against future changes. It's likely that I won't have to update ProtocolLib for anything but bug and performance fixes.
How is this possible? It all comes down to reflection in the end. Essentially, no name is hard coded - every field, method and class is deduced by looking at field types, package names or parameter types. It's remarkably consistent across different versions.
(note that the below list hasn't been updated in ages and ymmv)
Plugins that appear to be compatible
Plugins known to be compatible
Plugins using ProtocolLib
Inactive projects
Please let me know if you want me to add your plugin to this list. :)
Privacy
This plugin uses BStats to generate and publish anonymous aggregate usage statistics, but you can easily opt-out by setting metrics in config.yml to false.
If enabled, the following is sent every ten minutes:
- Metrics revision version (currently 6).
- Server's GUID
- Players currently online (not max player count)
- Server version string (the same version string you see in /version)
- Current version of ProtocolLib
- The name of every plugin that registers a packet listener in ProtocolLib.
Donating
If ProtocolLib has made your life significantly easier or you're feeling particularly generous, consider donating! It's a great way to support the many hours I've spent maintaining this plugin and keeps me motivated. Don't donate if you can't afford it.
I would like to thank everyone who has donated to ProtocoLib on BukkitDev. I really appreciate it. :)
Note: Create an issue if you're having problems. I generally don't check the BukkitDev comments.
评论 0
登录后参与评分
还没有评论,来抢沙发吧