ProtocolLib

ProtocolLib

Use 3.4.0 for Minecraft 1.7.9/.7.2/1.6.4/1.6.2/1.5.2/1.4.7 and older

Users of MCPC-Plus 1.7.2 and above should look for a special build (ProtocolLib - MCPC 1.7.2) on my Jenkins server. Cauldron users should download ProtocolLib - Cauldron.

Users of the new 1.8 build of Spigot should download "ProtocolLib - Spigot Hack 1.8" on my Jenkins server.

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

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

  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

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

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.

Tutorial for developers

See this page for more information.

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

  • SpoutPlugin

Plugins using ProtocolLib

Inactive projects

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

Privacy

This plugin uses MCStats 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.

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 joserobjr joserobjr Sep 20, 2014 at 19:42 UTC - 0 likes

    I need a little help...

    I'm using PacketWrapper to send PlayerInfo packets but it stopped working after I updated to ProtocolLib-Spigot-3.6.0-SNAPSHOT...

    com.comphenix.protocol.reflect.FieldAccessException: Field index must be within 0 - count
           at com.comphenix.protocol.reflect.StructureModifier.write(StructureModifier.java:285)
           at com.comphenix.packetwrapper.WrapperPlayServerPlayerInfo.setOnline(WrapperPlayServerPlayerInfo.java:68)
           at br.com.gamemods.mini.sabotage.player.SabotageTeam.leave(SabotageTeam.java:249)
           at br.com.gamemods.mini.sabotage.player.SabotageTeam.kill(SabotageTeam.java:307)
           at br.com.gamemods.mini.sabotage.game.SabotageRoom.onLeave(SabotageRoom.java:332)
           at br.com.gamemods.mini.platform.game.GameRoom.leave(GameRoom.java:473)
           at br.com.gamemods.mini.EventListener.onDisconnect(EventListener.java:572)
           at br.com.gamemods.mini.EventListener.onMonitor(EventListener.java:559)
           at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
           at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
           at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
           at java.lang.reflect.Method.invoke(Unknown Source)
           at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:298)
           at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:62)
           at org.bukkit.plugin.SimplePluginManager.fireEvent(SimplePluginManager.java:509)
           at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:494)
           at net.minecraft.server.v1_7_R4.PlayerList.disconnect(PlayerList.java:321)
           at net.minecraft.server.v1_7_R4.PlayerConnection.a(PlayerConnection.java:738)
           at net.minecraft.server.v1_7_R4.ServerConnection.c(ServerConnection.java:77)
           at net.minecraft.server.v1_7_R4.MinecraftServer.v(MinecraftServer.java:734)
           at net.minecraft.server.v1_7_R4.DedicatedServer.v(DedicatedServer.java:289)
           at net.minecraft.server.v1_7_R4.MinecraftServer.u(MinecraftServer.java:584)
           at net.minecraft.server.v1_7_R4.MinecraftServer.run(MinecraftServer.java:490)
           at net.minecraft.server.v1_7_R4.ThreadServerApplication.run(SourceFile:628)
    Caused by: java.lang.IndexOutOfBoundsException: Out of bounds
           ... 24 more
    

    That section:

    WrapperPlayServerPlayerInfo sabViewPacket = new WrapperPlayServerPlayerInfo();
    sabViewPacket.setPlayerName(listName);
    sabViewPacket.setOnline(false);
    sabViewPacket.sendPacket(player);
    
  • Avatar of libraryaddict libraryaddict Sep 15, 2014 at 00:06 UTC - 0 likes

    @xBlueXFoxx: Go

    You mean disappearing render side?

    1.8 bug. You can't resend a entity while its visible, or send a despawn packet and a spawn packet within 2 ticks without making the entity invisible.

    BFAK:libraryaddict,75154,c9bc87ad599337d3271d3cb02958adc594ab27bb05cc09136881ff0723c8fcb4

  • Avatar of likaos likaos Sep 13, 2014 at 09:32 UTC - 0 likes

    @aadnk Here is the only packet I can see when a player use a potion http://puu.sh/bx2E4/80e9927004.png

    Using the cheat, flood the server with [11:29:08] [Netty IO #1/INFO]: [ProtocolLib] Received PacketPlayInFlying[3, legacy: 10] from Likaos: { x = 0.0, y = 0.0, z = 0.0, stance = 0.0, yaw = 0.0, pitch = 0.0, g = true, hasPos = false, hasLook = false }

    I should check for it to detect the antipotion hack, thanks ;)

    Ps: The cheat Mod is obsfucated :/

  • Avatar of xBlueXFoxx xBlueXFoxx Sep 12, 2014 at 07:53 UTC - 0 likes

    Seem to be getting an issue where horses are disappearing, I've sat here isolating plugins for the past half hour to figure out it's Protocollib or a plugin that's using it, will edit with more detail if I get some.

    Only happens on 1.8 client (it doesn't delete the horse, only makes them invisible upon getting on them.) Recreated on ProtocolLib 3.4.0 (latest) Latest Spigot 1.8 protocol hack.

    Last edited Sep 12, 2014 by xBlueXFoxx
  • Avatar of rourke750 rourke750 Sep 11, 2014 at 21:12 UTC - 0 likes

    Hey so I have this class https://github.com/Civcraft/AttrHider/blob/master/src/com/civpvp/attrhider/AttrHider.java and what is meant to happen is it changes the packets that clients shouldnt be able to see like health, potion effects, armor, ect and it works correctly. The problem is when groups of players get near each other this error is thrown: https://github.com/Civcraft/AttrHider/issues/2

  • Avatar of aadnk aadnk Sep 11, 2014 at 00:01 UTC - 0 likes

    @likaos: Go

    Thanks for the donation. :)

    Sorry for being so absent, but I have a lot going on right now at work and school, and not to mention that 1.8 was just released.

    Have you tried intercepting and printing every client packet?

    /packet add play client 1-100 true
    

    You can remove irrelevant packets like so:

    /packet remove play client 1
    

    Alternatively, you could look into decompiling the cheat mod (JD-GUI).

  • Avatar of likaos likaos Sep 08, 2014 at 22:22 UTC - 0 likes

    Hello, sorry for posting it here but I have a question about protocollib client packet listener, I'm trying to catch a special case of cheat (called AntiPotion) here is the link http://dev.bukkit.org/bukkit-plugins/protocollib/forum/70347-anti-potion-hack/?unread

    I dont know how I can catch this client packet, I've tried all listener without any succes, is there a way to found it ?

    Does protocollib listen ALL clients packets or some are missing ?

    Thanks for your hard work, gave you a coffee :p

  • Avatar of aadnk aadnk Sep 07, 2014 at 19:31 UTC - 0 likes

    @libraryaddict: Go

    Ah, I see. Well, I can add a new ListenerOption for skipping this verifier.

    ProtocolLibrary.getProtocolManager().addPacketListener(
            new PacketAdapter(plugin, ListenerPriority.NORMAL, 
                    Arrays.asList(PacketType.Play.Server.CHAT), ListenerOptions.SKIP_PLUGIN_VERIFIER) {
        @Override
        public void onPacketSending(PacketEvent event) {
            super.onPacketSending(event);
        }
    });
    

    Alternatively, I could have added your plugin to the exception list. But it's probably better if plugins can elect to disable the verifier at any time.

  • Avatar of libraryaddict libraryaddict Sep 07, 2014 at 15:23 UTC - 0 likes

    @aadnk: Go

    That the plugin adding the packetlistener doesn't have ProtocolLib in depend: in its plugin.yml

  • Avatar of aadnk aadnk Sep 07, 2014 at 11:17 UTC - 0 likes

    @libraryaddict: Go

    Hm, what message is printed to the console? A plugin verifier error, perhaps?

Facts

Date created
Oct 05, 2012
Category
Last update
Jun 15, 2014
Development stage
Release
Language
  • enUS
License
GNU General Public License version 2 (GPLv2)
Curse link
ProtocolLib
Downloads
1,063,604
Recent files

Authors