ProtocolLib

ProtocolLib

Use 2.2.0 for Minecraft 1.4.6/1.4.7. Note that this version is also backwards compatible with 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.

Links

• Download ProtocolLib 2.2.0
• JavaDoc for API
• Source Code
• Forum Thread
• Usage Statistics

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.

Examples

Source code for a bunch of example programs that use ProtocolLib:

• Source code for modifying every packet in Minecraft
• ItemDisguise 1.0.0 - Hide visible enchantments
• BlockPatcher 1.3.1 - Convert every block ID on the map to another ID for the client
• TagHelper 1.0.0 - Alternative TagAPI implementation
• TagExample 1.0.0 - Simple example user of TagHelper
• HideChestOpening 1.0.0 - Hide the chest opening/closing animation.
• OverrideEnchanting 1.0.0 - Display fake enchanting levels.

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.

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.2.0</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:

/protocolupdate

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:

/packetaddclient 10-13 true

Remove all listeners:

/packetremoveclient/packetremoveserver

Note that this command should rarely be used on a production server. Listening to too many packets may crash the server.

Configuration

A small set of configuration options are available:

Global section

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.

privateProtocolManagerprotocolManager;publicvoidonLoad(){protocolManager=ProtocolLibrary.getProtocolManager();}

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

// Disable all sound effectsprotocolManager.addPacketListener(newPacketAdapter(this,ConnectionSide.SERVER_SIDE,ListenerPriority.NORMAL,Packets.Server.NAMED_SOUND_EFFECT){@OverridepublicvoidonPacketSending(PacketEventevent){// Item packetsswitch(event.getPacketID()){casePackets.Server.NAMED_SOUND_EFFECT:// 0x3Eevent.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:

// CensorprotocolManager.addPacketListener(newPacketAdapter(this,ConnectionSide.CLIENT_SIDE,ListenerPriority.NORMAL,Packets.Client.CHAT){@OverridepublicvoidonPacketReceiving(PacketEventevent){if(event.getPacketID()==Packets.Client.CHAT){PacketContainerpacket=event.getPacket();Stringmessage=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:

Packet60ExplosionfakeExplosion=newPacket60Explosion();fakeExplosion.a=player.getLocation().getX();fakeExplosion.b=player.getLocation().getY();fakeExplosion.c=player.getLocation().getZ();fakeExplosion.d=3.0F;fakeExplosion.e=newArrayList<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:

PacketContainerfakeExplosion=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);

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

• NoLagg
• NoCheatPlus

Plugins known to be compatible

• SpoutPlugin

Plugins using ProtocolLib

• Orebfuscator
• TagAPI
• DisguiseCraft
• VanishNoPacket
• CraftBook
• Scavenger
• Individual-Signs
• ItemRenamer
• PacketSneak
• InvisibilityViewer
• RandomCoords
• AntiCommandTab
• DwDSigns
• Sneaky
• Spy
• Statues

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