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.
Do there exist any list with what number is what on a packet. For example when you send the ENTITY_EQUIPMENT packet, how do you know what 1 mean in getPacket().getIntegers().read(1) (PS: I know that 1 is the slot, but this was just an example)
@libraryaddict for what i want protocol lib to do this doesnt work, need help with ucars mariokarts and protocol lib
i cant get ucars or mariokarts to work with spigot for 1.7.9, is this an issue with Protocol lib maybe ? if soo whats the best build version i should use for 1.7.9? can someone please help me =[
@killyouslow
We need a way to mark these kind of posts as funny.
This supports it already.
Protocol Lib for minecraft 1.7.9 ?
@CommodoreAlpha
It turns out that MCPC doesn't quite support Java 8 - it had nothing to do with ProtocolLib itself. So, there's no need for the MCPC developers to collaborate with plugin authors directly.
@wesley272
Yes, I've seen this error countless times over the past couple of months.
It's usually caused when TagAPI, for some reason, is downgraded to an earlier version that doesn't support Minecraft 1.7.2. You can fix this by redownloading it from BukkitDev, though I don't know if it's a permanent fix. If it should happen again, I'd recommend contacting mbaxter (the developer of TagAPI).
Getting these warnings in the console, any fix ideas? http://pastebin.com/vnCiu0Ln Running the latest dev build of ProtocolLib, #247. Running the latest dev build of spigot, #1459
@aadnk
Concerning MCPC+, do you think there's any possibility of actually getting their developers to work with you to produce "more compatible" builds in the future?
@Sabrucayore
I managed to create a simple compatibility patch for MCPC-Plus. :)
It's live on my Jenkins server.
@libraryaddict
I just want to mention that I've added most of the features you've requested - first, the ability to read/write tile entities, and second, a way to compare the state of a packet before its passed to the packet listeners and when its sent. They should be in build #246.
@Sabrucayore
Unfortunately, it's not a simple task that can be done in a short amount of time. The trouble is that MCPC-Plus itself is incompatible with ProtocolLib, not just the other way around. The plugin remapper crashes while remapping the main plugin class, and although I've managed to extract the stack trace, I have yet to find a solution.
I'm busy this week (and the next week) with exams, but I may have time to take a proper look at this issue during the weekend starting on the 9th of May. Though, there's really no way to know if I'll succeed.
Are there no really no alternative shop plugins that doesn't depend on ProtocolLib?
hello Aadnk !
I want to ask you when you are going to support mcpc 1.7.2 in ProtocolLib ?
It's really important for a lot of persons because without it we can't make our shop on and so without money, we can't pay our servers, so please can you do it ?
(Sorry for my english, i'm from belgium, so i speak frensh).
@gronnmann
You're missing a semi-colon at line 35 (see the corresponding line in my example).
@libraryaddict
The idea behind supporting both formats was to ease the transition into the new PacketType format - considering just how many people memorized and relied on the old packet IDs. It's a bit like the situation we will have with the upcoming removal of block ID, only on a much smaller scale.
I do agree that the current parsing rules are complex, though this should only affect error handling and discovery of the new format. I could probably do better on that front, but I don't think it's necessary to throw out the old syntax either.
As for the debug output - I believe it displays the packet type already, which contains the old and new packet ID, along with the class name. You can also use the packet name (with underscores) when adding/removing packet debug listeners.
I've uploaded the latest build of ProtocolLib on the repo now. I have to do it manually, so I often wait until a new version is released on BukkitDev. But you can get the very latest snapshot build on my Jenkins server.
Finally, for your "display modifications" idea - I think this could be solved by registering two packet listeners instead of just one, but at different priorities. One would be set two MONITOR, like the current debug listener, and the other would be registered with LOWEST. Then I would lookup the "old" packet version using PacketEvent as key (since ProtocolLib will reuse the same PacketEvent instance for each non-asynchronous listener).
@libraryaddict
Hm, no, not currently. Perhaps I could add a read/write method to NbtFactory that accepts a BlockState:
As for printing the entire world instance - yes, that's a huge mistake. I'll add a special case so that it only prints the world name (or ignores the field entirely). Thanks for the tip.
@gronnmann
http://hastebin.com/
Hmm. Btw.
There is no method for ProtocolLib to do the work with fetching the Tile Entity's packets is there.
Also when doing debug output on bulk map chunk. It starts looping into the World..
Then all the stuff in the world..
See a problem? It is going to print off everything in the MC server.
The huge byte arrays are bad enough
I have a problem with FakeEquipment. In my plugin class, I get an error. The error is on the onEnable(). My onEnable I get error on the new FakeEquipment(this) and on the bracket that "closes" it. The FakeEquipment class is like your with edited packet name. EDIT: Added the code to bukkit pastes instead of in the post.
@aadnk
I must have misunderstood you then.
When using the /packet commands, I don't think it should be defaulting to old/outdated packets as no one should be using those now. The command usage seems slightly more complex than it needs to be. I'm aware that the old packetadapters will remain in use as some plugins have not updated. But none of them should be using the command /packet
Secondly, if we could look up packet types from a ID and packets from a packet type using commands, it would be nice. For the most part its extremely easy to find out what packet is what. But when doing debug output. I would really rather prefer to see the PacketTypes instead of the packets as its more useful/readable. I still sometimes use the packet names however.
Thirdly, I noticed when trying to use your repo I didn't get the latest snapshot build which is on your jenkins. A rather minor problem which should resolve itself.
Fourthly, this is kind of a stupid idea. But still. A idea.
When you add debug output to the packet. If it was modified. It prints off the old packet.
And the new packet.
Not by cloning the packet. But by storing the string of what it would print normally, then modifying it and printing both strings if the second string doesn't match.
It would give people a idea of what modifications their plugin made, incase they don't know exactly what they are doing to packets.
@libraryaddict
Hm - you should be able to set that value using a PacketPostAdapter though. It will be executed almost right after the packet in the packet event has been sent.
Funny..
I suddenly have a case where I need to set a value straight after the packet is sent.
So the scheduled packets is somewhat useless for me there.
However. I've found that sending the packets to myself and to the server by using the 'bypass filter' option works.
Its not perfect, but it works.
@aadnk
Thanks!
@blablubbabc
It depends - by default, onPacketSending() is set to always execute on the main thread, but it is possible to override this (though only LOGIN/STATUS packets).
Conversley, onPacketReceiving() is always executed asynchronously. There, you have to use the scheduler in order to call Bukkit API (or use another synchronization method, like a shared collection).
@aadnk
Hey, very quick question: Are the packet handlers called in the server's main thread or async? Thanks in advance :)