About ProtocolLib
From GitHubProvides read and write access to the Minecraft protocol with Bukkit.
ProtocolLib
Certain tasks are impossible to perform with the standard Bukkit API, and may require working with and even modifying 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.
Resources
ProtocolLib.jar is the primary Paper plugin. Spigot servers must use the compatibility artifact, ProtocolLib-Spigot.jar. The Maven artifact is the platform-neutral library shared by both distributions.
Compilation
ProtocolLib is built with Gradle. If you have it installed, just run ./gradlew build in the root project folder. Other gradle targets you may be interested in include clean, test, and shadowJar. shadowJar will create a jar with all dependencies (ByteBuddy) included for both Paper and Spigot.
A new API
__ProtocolLib__ attempts to solve this problem by providing an event API, much like Bukkit, that allows 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 this library, first add ProtocolLib.jar to your Java build path. Then, add ProtocolLib as a dependency or soft dependency to your plugin.yml file like any other plugin:
depend: [ ProtocolLib ]
You can also add ProtocolLib as a Maven dependency:
<dependencies>
<dependency>
<groupId>net.dmulloy2</groupId>
<artifactId>ProtocolLib</artifactId>
<version>5.4.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
Or use the maven dependency with gradle:
repositories {
mavenCentral()
}
dependencies {
compileOnly 'net.dmulloy2:ProtocolLib:5.4.0'
}
Snapshot builds
Snapshot builds are available for testing changes before the next release. To use 5.5.0-SNAPSHOT, add the public repository and update your dependency version.
For Maven:
<repositories>
<repository>
<id>dmulloy2-public</id>
<url>https://repo.dmulloy2.net/repository/public/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>net.dmulloy2</groupId>
<artifactId>ProtocolLib</artifactId>
<version>5.5.0-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
</dependencies>
For Gradle:
repositories {
mavenCentral()
maven {
url = uri('https://repo.dmulloy2.net/repository/public/')
}
}
dependencies {
compileOnly 'net.dmulloy2:ProtocolLib:5.5.0-SNAPSHOT'
}
Accessing the API
Then get a reference to ProtocolManager in onLoad() or onEnable() 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,
ListenerPriority.NORMAL,
PacketType.Play.Server.NAMED_SOUND_EFFECT
) {
@Override
public void onPacketSending(PacketEvent event) {
event.setCancelled(true);
}
});
It's also possible to read and modify the content of packets, including the ones sent by a client. For instance, you can censor the text players write on signs by listening for UPDATE_SIGN packets:
// Censor signs
protocolManager.addPacketListener(new PacketAdapter(
this,
ListenerPriority.NORMAL,
PacketType.Play.Client.UPDATE_SIGN
) {
@Override
public void onPacketReceiving(PacketEvent event) {
PacketContainer packet = event.getPacket();
String[] lines = packet.getStringArrays().read(0);
for (int i = 0; i < lines.length; i++) {
lines[i] = lines[i].replace("shit", "****").replace("damn", "****");
}
packet.getStringArrays().write(0, lines);
}
});
Sending packets
Normally, you might have to do something ugly like the following:
PacketPlayOutExplosion fakeExplosion = new PacketPlayOutExplosion(
player.getLocation().getX(),
player.getLocation().getY(),
player.getLocation().getZ(),
3.0F,
new ArrayList<>(),
new Vec3D(
player.getVelocity().getX() + 1,
player.getVelocity().getY() + 1,
player.getVelocity().getZ() + 1
)
);
((CraftPlayer) player).getHandle().b.a(fakeExplosion);
But with ProtocolLib, you can turn that into something more manageable:
PacketContainer fakeExplosion = new PacketContainer(PacketType.Play.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);
fakeExplosion.getBlockPositionCollectionModifier().write(0, new ArrayList<>());
fakeExplosion.getVectors().write(0, player.getVelocity().add(new Vector(1, 1, 1)));
protocolManager.sendServerPacket(player, fakeExplosion);
Compatibility
Highlights
From source dataLoaders
Runs on Paper.
Footprint
Rated a light load on a server.
License
Published under GPL-2.0.
ProtocolLib on Nxeon
From our catalogue- One-click install
- Not available. This mod isn't available as a one-click install here. Download it and upload it to your server in Files.
- Server side
- Required on the server
- Server type needed
- Paper
- Server load
- light
- Smallest plan we suggest
- Minecraft — 1.5 GB (2 GB RAM). This follows our own load rating above, not a benchmark.
- Latest build
- dev-build (beta), released 2025-08-10
Game versions by loader
| Loader | Game versions | Newest |
|---|---|---|
| Paper |
From 10 recorded builds of ProtocolLib.
Recent builds
| Build | Released | Game versions | Loaders |
|---|---|---|---|
| dev-build beta | 2025-08-10 | n/a | Paper |
| 5.4.0 | 2025-08-07 | n/a | Paper |
| 5.3.0 | 2024-10-20 | n/a | Paper |
| 5.2.0 | 2024-04-07 | n/a | Paper |
| 5.1.0 | 2023-08-05 | n/a | Paper |
| 5.0.0 | 2023-04-16 | n/a | Paper |
Run ProtocolLib on a Minecraft server
Deploy a server above, then upload the file in Files.
What kind of mod it is
From the catalogLibraries & compatibility
Foundations and fixes other mods build on. Usually installed because something else needs it.
Runs on your server
From source side supportGitHub lists ProtocolLib as required on the server. Check its GitHub page to see whether players need it too.
Compatibility
- Game
- Minecraft
- Loaders
- Paper
- Runs on
- Serverrequired on the server
- Requires
- One-click install needs a Paper server.
Verified at the source
- ✓GitHubOfficial listing, checked 2026-10-26Open ↗
- ✓Authordmulloy2, as published on GitHub
- ✓LicenseGPL-2.0Free










