ProtocolLib

ProtocolLib

Use 2.4.3 for Minecraft 1.4.7/1.5.2. Note that this version is also backwards compatible with CraftBukkit 1.4.5, 1.4.2, 1.3.2, 1.2.5 and older.

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.

Up-to-date developer builds of this project can be acquired at my FTP server or Jenkins server. These builds have not been approved by the BukkitDev staff. Use them at your own risk.

Support

Please create a ticket 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 developer support forum. 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.

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.

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>comphenix-rep</id>
    <name>Comphenix Repository</name>
    <url>http://repo.comphenix.net/content/groups/public</url>
  </repository>
<!-- And so on -->
</repositories>

This repository contains ProtocolLib, TagHelper and BlockPatcher. You can add any of them as a dependency like so:

<dependencies>
  <dependency>
    <groupId>com.comphenix.protocol</groupId>
    <artifactId>ProtocolLib</artifactId>
    <version>2.4.3</version>
  </dependency>
</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.

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):

  1. Connection side: Either client or server.
  2. Multiple ID ranges: Can be a single packet ID like 14, or a range like 10 - 15. Defaults to 0 - 255 if not specified.
  3. Detailed: If TRUE, prints the full packet content.

Example:

/packet add client 10-13 true

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

OptionDefault

Description

auto updater.notifytrueInform any player with the permission protocol.info when a new version of ProtocolLib is out.
auto updater.downloadtrueAutomatically download and install the newest version of ProtocolLib. The installation will take effect when the server restarts.
auto updater.delay43200The number of seconds between each check for a new update.
auto updater.last0This 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.
metricstrueIf TRUE, ProtocolLib will publish anonymous usage data to mcstats.org. Set it to FALSE to opt-out.
background compilertrueIf TRUE, ProtocolLib will try and improve performance by replacing reflection with compiled code on-the-fly.
ignore version checkNoneForce ProtocolLib to start for a specified Minecraft version, even if it is incompatible.
suppressed reportsNoneIf 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.

A new API

ProtocolLib attempts to solve this problem by providing a event API, much like Bukkit, that allow plugins to monitor, modify or cancel packets sent and received. But more importantly, the API also hides all the gritty, obfuscated classes with a simple index based read/write system. You no longer have to reference CraftBukkit!

Using ProtocolLib

To use the library, first add ProtocolLib.jar to your Java build path. Then, add ProtocolLib as a dependency (or soft-dependency, if you can live without it) to your plugin.yml file: Code:

depend: [ProtocolLib]

In Eclipse, you can add the online JavaDoc documentation by right-clicking the JAR file in Project Explorer. Choose Properties, and from the left pane choose JavaDoc Location. Finally enter the following URL:

http://aadnk.github.com/ProtocolLib/Javadoc/

The first thing you need, is a reference to ProtocolManager. Just add the following in onLoad() and you're good to go.

private ProtocolManager protocolManager;
  
public void onLoad() {
    protocolManager = ProtocolLibrary.getProtocolManager();
}

To listen for packets sent by the server to a client, add a server-side listener:

// Disable all sound effects
protocolManager.addPacketListener(
  new PacketAdapter(this, ConnectionSide.SERVER_SIDE, 
  ListenerPriority.NORMAL, Packets.Server.NAMED_SOUND_EFFECT) {
    @Override
    public void onPacketSending(PacketEvent event) {
        // Item packets
        switch (event.getPacketID()) {
        case Packets.Server.NAMED_SOUND_EFFECT: // 0x3E
            event.setCancelled(true);
            break;
        }
    }
});

It's also possible to read and modify the content of these packets. For instance, you can create a global censor by listening for Packet3Chat events:

// Censor
protocolManager.addPacketListener(new PacketAdapter(this,
        ConnectionSide.CLIENT_SIDE, ListenerPriority.NORMAL, 
        Packets.Client.CHAT) {
    @Override
    public void onPacketReceiving(PacketEvent event) {
        if (event.getPacketID() == Packets.Client.CHAT) {
            PacketContainer packet = event.getPacket();
            String message = packet.getStrings().read(0);

            if (message.contains("shit")
                    || message.contains("damn")) {
                event.setCancelled(true);
                event.getPlayer().sendMessage("Bad manners!");
            }
        }
    }
});

Sending packets

Normally, you might have to do something ugly like the following:

Packet60Explosion fakeExplosion = new Packet60Explosion();
 
fakeExplosion.a = player.getLocation().getX();
fakeExplosion.b = player.getLocation().getY();
fakeExplosion.c = player.getLocation().getZ();
fakeExplosion.d = 3.0F;
fakeExplosion.e = new ArrayList<Object>();
 
((CraftPlayer) player).getHandle().
    netServerHandler.sendPacket(fakeExplosion);

But with ProtocolLib, you can turn that into something more manageable. Notice that you don't have to create an ArrayList this version:

PacketContainer fakeExplosion = protocolManager.createPacket(
    Packets.Server.EXPLOSION);
 
fakeExplosion.getDoubles().
    write(0, player.getLocation().getX()).
    write(1, player.getLocation().getY()).
    write(2, player.getLocation().getZ());
fakeExplosion.getFloat().
    write(0, 3.0F);
 
protocolManager.sendServerPacket(player, fakeExplosion);

If you use PacketWrapper, you can get an even easier version. This is especially useful if you're trying to send a entity spawn packet:

Packet3CExplosion fakeExplosion = new Packet3CExplosion();
 
fakeExplosion.setX(player.getLocation().getX());
fakeExplosion.setY(player.getLocation().getY());
fakeExplosion.setZ(player.getLocation().getZ());
fakeExplosion.setRadius(3);

protocolManager.sendServerPacket(player, fakeExplosion.getHandle());

Compatibility

One of the main goals of this project was to achieve maximum compatibility with CraftBukkit. And the end result is quite good - in tests I successfully ran an unmodified ProtocolLib on CraftBukkit 1.8.0, and 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.

Plugins that appear to be compatible

Plugins known to be compatible

Plugins using ProtocolLib

Plugins not hosted on BukkitDev

Note that these plugins have not been reviewed by a trusted party such as BukkitDev. Use at your own risk!

Please let me know if you want me to add your plugin to this list. :)

Acknowledgements

I would like to thank everyone who has donated to ProtocoLib. I really appreciate it. :)

Donate

Statistics

ProtocolLib Statistics

Note: Create a ticket if you're having problems. Don't post stack traces in the comments.

You must login to post a comment. Don't have an account? Register to get one!

  • Avatar of aadnk aadnk Jun 19, 2013 at 00:11 UTC - 0 likes

    @Stevenpcc: Go

    I don't seem to be able to reproduce it myself, perhaps you could make that Barebone plugin if possible?

    I installed DisguiseCraft, ItemRenamer and TagAPI (with ProtocoLib 2.4.3) just to be on the safe side, and used Multiverse 2 to generate two extra worlds (test1 and test2) on my test server. After attaching JProfiler, I started using these plugins on all three worlds, and returned to the default world (world). At this stage I verified that the worlds were in memory by creating a heap dump and looking at the biggest objects.

    However, after unload test1 and test2, they were nowhere to be found in the heap dump. It didn't leak, as far as I can make out.

  • Avatar of Stevenpcc Stevenpcc Jun 18, 2013 at 14:47 UTC - 0 likes

    ProtocolLib Memory leak

    I run a mini game server that loads and unloads worlds to reset them. It suffers from a memory leak, where the world stays loaded in memory, even after I unloaded it. I did lots of testing, narrowing down where the leak was occurring, using jprofiler etc. It seems it only occurs when I use ProtocolLib and a plugin that supports it.

    With TagAPI I was able reproduce the leak every time a world was unloaded, simply by having the plugin loaded at startup. With disguisecraft it happened almost every time, with the number of users online seeming to have an impact (a few didn't make it happen, 15 or more it would happen every time). The one thing they have in common is they use protocollib.

    I've been going through the ProtocolLib code seeing if I could spot anything that would cause a leak. So far there's nothing obvious. I was just wondering if you'd have any ideas on where to look?

    Also, if I were to put together a barebones plugin to reproduce the leak, would this be useful to you?

  • Avatar of aadnk aadnk Jun 17, 2013 at 11:18 UTC - 1 like

    @ikwerner1: Go

    Yeah, it's only used for the "packet filter" command, which should be disabled unless you're running in debug mode.

    I'll make ProtocolLib load the engine on demand instead. That way, you won't have to bother with fixing JavaScript support unless you actually need it. Here's the updated development version.

  • Avatar of ikwerner1 ikwerner1 Jun 17, 2013 at 08:05 UTC - 0 likes

    Hi,

    I am running the latest recommended build 1.5.2-R1.0 on freebsd. Protocollib higher than 2.3.0 will trow the following error:

    2013-06-17 09:53:51 [INFO] [ProtocolLib] Loading ProtocolLib v2.4.3
    2013-06-17 09:53:51 [WARNING] [ProtocolLib] [CommandFilter] Unable to initialize packages for JavaScript engine.
    javax.script.ScriptException: A JavaScript engine could not be found.
    	at com.comphenix.protocol.CommandFilter.initalizeScript(CommandFilter.java:240)
    	at com.comphenix.protocol.CommandFilter.<init>(CommandFilter.java:230)
    	at com.comphenix.protocol.ProtocolLibrary.onLoad(ProtocolLibrary.java:191)
    	at org.bukkit.craftbukkit.v1_5_R3.CraftServer.loadPlugins(CraftServer.java:244)
    	at org.bukkit.craftbukkit.v1_5_R3.CraftServer.<init>(CraftServer.java:217)
    	at net.minecraft.server.v1_5_R3.PlayerList.<init>(PlayerList.java:55)
    	at net.minecraft.server.v1_5_R3.DedicatedPlayerList.<init>(SourceFile:11)
    	at net.minecraft.server.v1_5_R3.DedicatedServer.init(DedicatedServer.java:106)
    	at net.minecraft.server.v1_5_R3.MinecraftServer.run(MinecraftServer.java:382)
    	at net.minecraft.server.v1_5_R3.ThreadServerApplication.run(SourceFile:573)
    

    Before i installed Rhino this error would be followed by something in the lines of: A javascript engine could not be found falling back to Rhino. Rhino not found.

    Can i ignore this warning?

    Regards Werner

  • Avatar of aadnk aadnk Jun 13, 2013 at 02:57 UTC - 0 likes

    @romeomax: Go

    To quote the main page:

    Quote:

    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.

    Certain plugins need ProtocolLib to implement features that are otherwise not possible in Bukkit. It's also used to ensure that such plugins don't conflict with each other, as they would otherwise have to patch code on runtime and thus "overwrite" each others patches.

  • Avatar of romeomax romeomax Jun 13, 2013 at 02:52 UTC - 0 likes

    Okay, whats the main point of this plugin?? I have it but i don't remember downloading it. What does this do!?

  • Avatar of aadnk aadnk Jun 09, 2013 at 20:45 UTC - 0 likes

    @Terraquis: Go

    I assume you've based your code on this documentation. Unfortunately, this doesn't really apply for ProtocolLib, as you're modifying or reading the internal copy of each packet, not how that packet is compressed and sent through the wire (where integers are often converted to bytes and so on). Instead, you must look at the actual relevant source code, and compare that with the unofficial protocol documentation. I've explained this in more detail here.

    However, there's an easier way. Just use PacketWrapper. I've already done what I described above for all the classes, and you can simply copy and paste the classes you need for your project. Use bed in PacketWrapper is here - you'll also need AbstractPacket. Or, you can just look at the source code in PacketWrapper to get a general idea of how to write your code correctly.

    EDIT: I forgot to mention, the NullPointException you got is caused by the "null" you've used in line 8. Null is not the same as 0. It's the default value of reference types, and represents nothing or no reference at all (more). You can't store it in a primitive type such as a byte, unlike 0 (zero), which is just a number. But of course, there's no byte variables in the packet in the first place, so it wouldn't have worked even if you passed in 0 as you should have.

    Last edited Jun 09, 2013 by aadnk
  • Avatar of Terraquis Terraquis Jun 09, 2013 at 20:34 UTC - 0 likes

    I have the following problem; it may be a legitimate issue or just a noobish mistake. When I use the following code to send a bed packet to the player, I get a nullPointerException. Here is the code:

    						PacketContainer bedInterface = protocolManager.createPacket(Packets.Server.BED);
    						bedInterface.getIntegers().
    							write(0, player.getEntityId()).
    							write(2, cpuX).
    							write(3, cpuY).
    							write(4, cpuZ);
    						bedInterface.getBytes().
    							write(1, null);
    						
    						try {
    							protocolManager.sendServerPacket(player, bedInterface);
    						} catch (InvocationTargetException e) {
    							// TODO Auto-generated catch block
    							e.printStackTrace();
    						}
    
  • Avatar of cuddyier cuddyier Jun 07, 2013 at 13:21 UTC - 1 like

    @aadnk: Go

    I just downloaded Protocol Lib directly on my ssh and it seems to work fine now, FTP must have been messing with it.

  • Avatar of aadnk aadnk Jun 06, 2013 at 18:24 UTC - 0 likes

    @cuddyier: Go

    Can you verify the MD5 checksum of the file (md5sum on GNU/Linux, FileVerifier++ on Windows)? It should be 9e418972e0608a55ea3a82d585d3efa8. If not, I'd check if you haven't accidentally used text mode instead of binary mode on your FTP server, assuming you're using FTP. You should also try transferring the JAR file with a different method. Remember to delete the updates folder inside /plugins too.

    But I'd recommend you reinstall your JVM version. That might do the trick.

    @robmcdonald5: Go

    It seems to work fine for me. Are you using Libigot - Heroes is not compatible with your standard CraftBukkit.

Facts

Date created
Oct 05, 2012
Category
Last update
May 13, 2013
Development stage
Release
Language
  • enUS
License
GNU General Public License version 2 (GPLv2)
Curse link
ProtocolLib
Downloads
214,321
Recent files

Authors