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.
@MutinyCraft
Ah, yes, you posted this on the ProtocolLib forums as well.
I'm sorry, but I haven't really had much spare time this week. I've been working overtime, and I just moved to a different apartment.
Now, I don't even know if this is possible with the 1.7.2 client. Wasn't smooth teleporting first introduced as a new new feature in one of the 1.8.0 snapshots?
But have you tried teleporting the player in smaller increments, using a scheduled task?
It's not as smooth as actually moving the cursor, though. But it's a step in the right direction.
By the way, I couldn't get the ProtocolLib approach to work. Are you sure you're not also updating the player location?
I'm having some issues with adjusting a player's view. What I'm trying to do is adjust the pitch of the player. Originally, I tried to do this without ProtocolLib by create a Location object with only the pitch modified and teleporting the player to that location. This works, but it is fairly noticeable to the client that they are being "jerked" to a new location. The adjustment in pitch was only about -4 degrees. I then tried to use ProtocolLib and I was able to get the desired end result, but when the client receives the new packet with the updated pitch the screen flashes to the new position. It is almost worse than just teleporting the player. I will include both ways below and I would really appreciate any advice or suggestions.
Teleport Method:
ProtocolLib Method:
@Rothendras
That was only for laying the ground work for 1.7.2 support.
You still need to use the special build under job ProtocolLib - MCPC 1.7.2.
I will not open a ticket for that, so just a question...
I search the Mcpc+ 1.7.2 build of Protocollib.
This is it there? -> http://assets.comphenix.net/job/ProtocolLib/247/
I must be mistaken because this snapshot '247' don't work on mcpc+ 1.7.2 :/
@aadnk
I see ok thanks for your reply i'll hunt down some of the plugins that require protocollib now :P
@ravand
This is probably caused by plugins that incorrectly access the Minecraft world from a thread other than the main thread.
No, I don't believe that is ProtocolLib. It doesn't modify any world data at all, and I'm always careful when I access Bukkit API in other threads.
Of course, it is possible that some plugin is using ProtocolLib incorrectly, and is accessing the Minecraft world from a different thread. In that case the problem might disappear if you disable ProtocolLib, but that still doesn't mean ProtocolLib is the actual cause of the problem.
1 of our servers keeps crashing with a ConcurrentModifcationException. After a little bit of research some people mention ProtocolLib being the cause of this:
Here a log:
http://puu.sh/8RRak.txt
Can you confirm this? Or is this related to something else?
EDIT: Also here another log from a crash that looks similiar
http://puu.sh/8RRkL.txt
@Squawkers13
It's up now. :)
Ended up moving it to the Jenkins server after all.
@aadnk
Thanks. :)
@Squawkers13
Ah, yeah, sorry - I'm moving, so my website/Maven server is down. But you can use the Maven server on Jenkins in the meantime.
I may end up moving my Maven repository to the Jenkins server as well.
The Maven repository seems to be offline?
@seanschilling
It works with 1.7.9.
Does the latest version work with 1.7.9 or will you have an updated version that does soon?
@xDizasterCYx
Hm - strange. Perhaps you're using late-binding or BungeCoord?
I could try work around this by automatically constructing the server connection if its missing. Try version #249 on my Jenkins server and see if it works in your case.
how can i fix that?
[10:57:12] [Server thread/INFO]: [ProtocolLib] Enabling ProtocolLib v3.3.1 [10:57:12] [Server thread/INFO]: [ProtocolLib] Started structure compiler thread. [10:57:12] [Server thread/ERROR]: [ProtocolLib] INTERNAL ERROR: Cannot enable ProtocolLib. If this problem hasn't already been reported, please open a ticket at http://dev.bukkit.org/server-mods/protocollib/ with the following data:
STACK TRACE
java.lang.RuntimeException: Unable to inject channel futures. at com.comphenix.protocol.injector.netty.NettyProtocolInjector.inject(NettyProtocolInjector.java:164) at com.comphenix.protocol.injector.PacketFilterManager.registerEvents(PacketFilterManager.java:955) at com.comphenix.protocol.ProtocolLibrary.onEnable(ProtocolLibrary.java:400) at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:250) at org.bukkit.plugin.java.JavaPluginLoader.enablePlugin(JavaPluginLoader.java:324) at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:405) at org.bukkit.craftbukkit.v1_7_R3.CraftServer.loadPlugin(CraftServer.java:467) at org.bukkit.craftbukkit.v1_7_R3.CraftServer.enablePlugins(CraftServer.java:385) at net.minecraft.server.v1_7_R3.DedicatedServer.init(DedicatedServer.java:136) at net.minecraft.server.v1_7_R3.MinecraftServer.run(MinecraftServer.java:450) at net.minecraft.server.v1_7_R3.ThreadServerApplication.run(SourceFile:628) Caused by: java.lang.NullPointerException at com.comphenix.protocol.reflect.FuzzyReflection.fromObject(FuzzyReflection.java:91) at com.comphenix.protocol.injector.netty.NettyProtocolInjector.inject(NettyProtocolInjector.java:143) ... 10 more
DUMP
manager: com.comphenix.protocol.injector.PacketFilterManager@31d5dc5f[ unhookTask=com.comphenix.protocol.injector.DelayedSingleTask@4f76fa88 packetListeners=[] packetInjector=com.comphenix.protocol.injector.netty.NettyProtocolInjector$5@3be888db playerInjection=com.comphenix.protocol.injector.netty.NettyProtocolInjector$4@1f710097 interceptWritePacket=com.comphenix.protocol.injector.packet.InterceptWritePacket@33ddc9a1 inputBufferedPackets=[] recievedListeners=com.comphenix.protocol.injector.SortedPacketListenerList@25e083a1 sendingListeners=com.comphenix.protocol.injector.SortedPacketListenerList@36e1d274 hasClosed=false classLoader=org.bukkit.plugin.java.PluginClassLoader@78e524cc reporter=com.comphenix.protocol.ProtocolLibrary$1@23bfd9d2 server=CraftServer{serverName=CraftBukkit,serverVersion=git-Spigot-1465,minecraftVersion=1.7.9} asyncFilterManager=com.comphenix.protocol.async.AsyncFilterManager@59357322 knowsServerPackets=true knowsClientPackets=true phaseLoginCount=0 phasePlayingCount=0 packetCreation=false spigotInjector=<null> nettyInjector=com.comphenix.protocol.injector.netty.NettyProtocolInjector@681ee1ce pluginVerifier=com.comphenix.protocol.injector.PluginVerifier@437ad0c9 hasRecycleDistance=true minecraftVersion=(MC: 1.7.9) loginPackets=com.comphenix.protocol.injector.LoginPackets@34215ebb debug=false ] Sender: com.comphenix.protocol.ProtocolLibrary@7bd11efd[ statistisc=<null> backgroundCompiler=com.comphenix.protocol.reflect.compiler.BackgroundCompiler@62c712a packetTask=-1 tickCounter=0 unhookTask=com.comphenix.protocol.injector.DelayedSingleTask@4f76fa88 configExpectedMod=-1 updater=com.comphenix.protocol.metrics.Updater@4fb97f90 logger=org.bukkit.plugin.PluginLogger@1b65efd4 redirectHandler=com.comphenix.protocol.ProtocolLibrary$2@41645559 commandProtocol=com.comphenix.protocol.CommandProtocol@221f6799 commandPacket=com.comphenix.protocol.CommandPacket@3bca7f4f commandFilter=com.comphenix.protocol.CommandFilter@6b6c3a33 skipDisable=false isEnabled=true loader=org.bukkit.plugin.java.JavaPluginLoader@e61215e server=CraftServer{serverName=CraftBukkit,serverVersion=git-Spigot-1465,minecraftVersion=1.7.9} file=plugins\ProtocolLib-3.3.1.jar description=org.bukkit.plugin.PluginDescriptionFile@ad5a9b2 dataFolder=plugins\ProtocolLib classLoader=org.bukkit.plugin.java.PluginClassLoader@78e524cc naggable=true ebean=<null> newConfig=YamlConfiguration[path='', root='YamlConfiguration'] configFile=plugins\ProtocolLib\config.yml logger=org.bukkit.plugin.PluginLogger@1b65efd4 ] Version: ProtocolLib v3.3.1 Server: git-Spigot-1465 (MC: 1.7.9)
[10:57:12] [Server thread/INFO]: [ProtocolLib] Disabling ProtocolLib v3.3.1
@TheUltimativeLink
Hm - or you're using a too recent version of TagAPI. It depends on your CraftBukkit version.
But this comment section is really only for ProtocolLib. If you need help with TagAPI, you should go to the forum thread or IRC instead.
@aadnk
I have the newest Version should i test a dev Version?
@TheUltimativeLink
Looks like your version of TagAPI is outdated - try redownloading it from BukkitDev.
I get this Exeption and i dont know why, pls help me
[20:56:53] [Server thread/WARN]: ... 29 more [20:56:53] [Server thread/WARN]: com.comphenix.protocol.reflect.FieldAccessException: Field index must be within 0 - count [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.reflect.StructureModifier.read(StructureModifier.java:191) [20:56:53] [Server thread/WARN]: at org.kitteh.tag.handler.ProtocolLibHandler$1.onPacketSending(ProtocolLibHandler.java:54) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.SortedPacketListenerList.invokeSendingListener(SortedPacketListenerList.java:195) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.SortedPacketListenerList.invokePacketSending(SortedPacketListenerList.java:149) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.PacketFilterManager.handlePacket(PacketFilterManager.java:612) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.PacketFilterManager.invokePacketSending(PacketFilterManager.java:588) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.NettyProtocolInjector.packetQueued(NettyProtocolInjector.java:267) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.NettyProtocolInjector.onPacketSending(NettyProtocolInjector.java:235) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.ChannelInjector.processSending(ChannelInjector.java:260) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.ChannelInjector.access$300(ChannelInjector.java:51) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.ChannelInjector$3.handleScheduled(ChannelInjector.java:236) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.ChannelInjector$3.onMessageScheduled(ChannelInjector.java:213) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.ChannelProxy$2.schedulingRunnable(ChannelProxy.java:100) [20:56:53] [Server thread/WARN]: at com.comphenix.protocol.injector.netty.EventLoopProxy.execute(EventLoopProxy.java:76) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.NetworkManager.b(NetworkManager.java:112) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.NetworkManager.handle(NetworkManager.java:90) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.PlayerConnection.sendPacket(PlayerConnection.java:737) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.EntityTrackerEntry.updatePlayer(EntityTrackerEntry.java:322) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.EntityTracker.a(EntityTracker.java:207) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.EntityPlayer.h(EntityPlayer.java:233) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.World.entityJoinedWorld(World.java:1345) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.World.playerJoinedWorld(World.java:1326) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.World.tickEntities(World.java:1214) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.WorldServer.tickEntities(WorldServer.java:480) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.MinecraftServer.v(MinecraftServer.java:639) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.DedicatedServer.v(DedicatedServer.java:250) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.MinecraftServer.u(MinecraftServer.java:548) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.MinecraftServer.run(MinecraftServer.java:459) [20:56:53] [Server thread/WARN]: at net.minecraft.server.v1_7_R2.ThreadServerApplication.run(SourceFile:618) [20:56:53] [Server thread/WARN]: Caused by: java.lang.IndexOutOfBoundsException: Out of bounds [20:56:53] [Server thread/WARN]: ... 29 more
-Link
@killyouslow
You need to be a bit more specific than that - do you get any error messages in the console? Stack traces?
ProtocolLib 3.3.1 should be fully compatible with both CraftBukkit 1.7.8 and 1.7.9. If you're still having problems, I suggest upgrading ucars to the latest development version.
@gronnmann
The closest is PacketWrapper, which contains wrapper classes that does all of that for you. But you could just look at the source code, and find the indices that way.
This is much easier than doing it manually yourself.