ProtocolLib
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
Development builds of ProtocolLib can be found here: https://ci.dmulloy2.net/job/ProtocolLib/
These builds have not been approved by the BukkitDev staff. Use them at your own risk.
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 the following repository:
<repositories> <repository> <id>dmulloy2-repo</id> <url>https://repo.dmulloy2.net/content/groups/public/</url> </repository> <!-- And so on --> </repositories>
You can add it as a dependency like so:
<dependencies> <dependency> <groupId>com.comphenix.protocol</groupId> <artifactId>ProtocolLib</artifactId> <version>4.5.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:
/protocol update
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 |
Description |
---|---|---|
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
- SpoutPlugin
Plugins using ProtocolLib
- Orebfuscator
- TagAPI
- DisguiseCraft
- VanishNoPacket (v3.18.5 and earlier)
- BkCommonLib
- CraftBook
- ChairsReloaded (3.0.2 and earlier)
- Scavenger
- TabAPI
- Individual-Signs
- ItemRenamer
- RandomCoords
- AntiCommandTab
- Sneaky
- Spy
- Statues
- Seasons
- Safe Command Block
- PlayerHider
- Phantasma Chat Filter
- Ghost Hunt
- ReMap
- AttributeHider
- uCars
- uPlanes
- PropHunt
- Portable-Horses
- ClickEdit
- RageBan
- ReChat
- PlayEffect
- FakePlayers
- PlayerCountMessage
- Vampire
- Murder
- NoSpy
- PingNachricht
- NoCheatPlus
- ScoreboardStats
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.
Hi, ive got a packet listener for NamedEntitySpawn. It works fine but i get the error below ocassionally, and then all the players crash and the server cpu usage goes down to 2%
INFO java.nio.channels.ClosedChannelException 28.04 10:33:18 [Server] WARN An exceptionCaught() event was fired, and it reached at the tail of the pipeline. It usually means the last handler in the pipeline did not handle the exception.
@sync667
You can't assume packets are stored in memory exactly as they are transmitted over the wire, often Minecraft will parse the input and keep it in a more complex object. In other words, this page is not a documentation for ProtocolLib. It's a useful guide when you need to know which packets to intercept or send, and the format may be very close to the data in memory. But ultimately, you have to look in the source code to verify it.
In this case, the packet actually stores the initial byte array in a java.security.PublicKey (see the source code), while throwing away the explicit array lengths as they're not needed.
Alternatively, you could use one of the wrapper classes in PacketWrapper if you don't want to read the decompiled source code. Then it's a simple matter of copying in the right class, and using it in your packet listener:
With this:
I get FieldAccessException: Field index must be within 0 - count. Can you correct me what happend? and how to fix it? I try to find problem with many ways, but without success. I'm sending Server.ENCRYPTION_BEGIN packet with data that i found on protocol info page. Thanks
@aadnk
Thanks! I guess I am allowed to do edits like package name to the FakeEquipent class. If not, just say it.
@gronnmann
Oh yeah, I forgot to release it under a permissive license. As it stands, you'd actually be breaking copyright if you'd just copy it into your project.
I think the MIT license should suffice. Then you only have to preserve my copyright notice, and you'll be able to modify and distribute the code with no restrictions.
So - the answer is yes, if you copy the version on my Gist.
@aadnk
Thanks! So I can just copy the FakeEquipment class?
@gronnmann
Sure - I've created a new example for 1.7.2 and made it easier to correctly modify armor as well as held items. I've also fixed a problem that would had made it difficult to alter the held item depending on the observed player.
Just add the FakeEquipment class to your project, and extend it like so:
Please remember to return TRUE if you've modified anything in onEquipmentSending(). Also remember that onEntitySpawn() is necessary if you want to change an empty slot into a slot that contains an item.
Is it possible to make fake item in hand with a method like this? I have did it succesfully with armor but fail with the item in hand.
@libraryaddict
Sure, I can add something like that - it's not that far off from PacketOutputHandler in terms of the implementation either.
And here's an example of it in use:
And, on top of this system, I could also add a "delayed packets" list in PacketEvent, which would allow other plugins to inspect (and modify) the list of packets that gets sent in addition (or in place) of the existing packet.
Though it might not be necessary.
Hmm.
Regarding something we talked about a while ago.
Sending more packets straight after a packet is sent.
Not a tick after
I still need that.
Was thinking that you could add a runnable call when the event finishes and the packet is sent.
Possibly with the ability to add more than one runnable.
PacketEvent.addCallback(runnable) removeCallback(runnable) getCallbacks()
Unlike normal plugin programming, packets depend a lot on the order they are sent and when. So a tick difference does make.
Only use case I have currently is that I want to send more packets if a certain packet is caught. And a tick delay makes things look ugly
@gronnmann
You can send/"receive" a packet from a command, if that's what you're talking about. If you just want a command to affect incoming or outgoing packets, then you should store any such modification in a HashMap and look it up in the packet listener.
And yes, you can add/remove packet listeners at any point in your plugin, not just onEnable().
How to make a packet changed when you type a command?? Edit: I also wonder if it is possible to make a packet listener on other places than the onEnable.
@TNTUP
It's compiled on my Jenkins server, however, I haven't added the necessary feature yet. I figured I'd wait until I knew you'd be able to run it.
I'll see if I can't add it soon.
@aadnk
Mhm.. will try but atm im very busy on my server (25-30 per day) and I have less time to do tests :C, and that detetctCME needs to be compiled I guess :P
EDIT: I did a second /protocol listeners, and heres the newer one: http://pastebin.com/CUDw1SKJ
@TNTUP
Well, the error doesn't actually occur in ProtocolLib, the only reason it shows up in the call stack is because I have to "intercept" packet writing in order to implement PacketOutputHandler.
Even if I knew what caused this, I wouldn't be able to fix it in ProtocolLib. The code (likely in some plugin) that is modifying the NBT tag when Minecraft is iterating over its keys is to blame here.
So, I still recommend disabling plugins until the problem no longer presents itself (try disabling half of your plugins at a time, if you have many). But this can be difficult, especially if the error only occurs rarely and requires multiple players online, which would limit the usefulness of a test server.
Perhaps you could try DetectCME instead? I can modify it to also detect cross-thread modification of the NBT tags in PacketPlayOutTileEntityData, if you're interested. Then all you have to do is run this detection plugin, and wait for the error to be triggered.
@libraryaddict
I've added this to build #242 (3.4.0-SNAPSHOT) on the Jenkins server. WrappedGameProfile now contains the getter "getProperties()", along with the useful static function WrappedGameProfile.fromPlayer(Player), which allows you to retrieve a game profile from an online player.
@aadnk
I have updated ProtocolLib to 3.3.1, I was on 3.2.0... I'll give out news if its occurs again
EDIT: Still occurs, maybe its a minecraft bug itself or the plugin, but I can't be sure.
@libraryaddict
I suppose I could simply expose it as a WrappedSignedProperty, or someting like that.
I'll see if I can't implement it tomorrow, when I get back from my vacation.
Would it be possible to have WrappedGameProfile support getting/setting skin blobs?
@aadnk
Well, players are getting that kind of error while playing ColorShuffle... The developer didn't answers my PM so I could try PM that error, asking him using ProtocolLib...
@PillageCraft
It's not an error though - it's just an exception that gets thrown when a client forcefully disconnects from the server.
@TNTUP
Hm, then the plugin causing this is not actually using ProtocolLib. It might be using TinyProtocol, a drop-in replacement for ProtocolLib, or some equivalent method. Or not - it's very difficult to debug ConcurrentModificationExceptions, especially when you can't reproduce it yourself.
Do you get this exception almost immediately? If so, try disabling plugins until you no longer get the exception. That should give a clue as to which plugin is causing problems.