Minecraft plugin packetevents

🔌 About PacketEvents

PacketEvents is a protocol library for Minecraft Java Edition that exposes an API to intercept, inspect, cancel and send raw protocol packets. It can be used as a standalone plugin on a server/proxy or bundled as a library dependency for other plugins and mods.

🎯 Purpose

Provide a stable, multi-platform packet layer for plugin and mod developers so they can react to and manipulate Minecraft protocol packets (login, play, status, handshake, etc.) without writing low-level Netty code or maintaining many version-specific protocol implementations themselves.

⚙️ Features

• Event-driven packet interception for incoming and outgoing packets (receive/send events and protocol-level events).
• Ability to cancel or modify packets before the server/client processes them.
• API surface for sending and simulating packets programmatically.
• Clean lifecycle: create/load/init/terminate a PacketEvents instance for proper resource management.
• Multi-module support: separate builds/modules for common platforms so the same API works across different server/proxy/mod environments.
• Published Javadocs and documented developer setup for Maven/Gradle usage.

🧩 Who It Is For

• Plugin and mod developers who need protocol-level access (sending, simulating, or modifying packets).
• Server operators who install PacketEvents as a dependency for plugins that require packet interception.

🏗️ Example Use Cases

• A plugin registers a packet listener and cancels a specific incoming packet to prevent default processing.
• A mod sends synthetic packets to a client to create custom visual effects or UI without server-side entity changes.
• A proxy plugin handles login/handshake packets for custom authentication flows.

⚙️ Installation

📥 Setup (server operator)

• Download the official plugin JAR and place it in the server/proxy plugins/ (or equivalent) directory.
• Restart the server/proxy and check logs to confirm PacketEvents loaded correctly.

🛠️ For developers (build setup)

PacketEvents is distributed as platform-specific modules. The documentation shows Maven/Gradle examples; the library is intended to be added with provided/compileOnly scope. The docs use a placeholder for the module name; replace it with the target platform module (for example spigot, velocity, bungeecord, fabric, sponge) when adding a dependency.

Example (Gradle snippet shown in official docs):

// Replace INSERT_MODULE_HERE with a supported module name (spigot, velocity, bungeecord, fabric, sponge)
compileOnly("com.github.retrooper:packetevents-~~INSERT_MODULE_HERE~~:2.12.1")

Call the library lifecycle methods from your plugin/mod (load -> init) and terminate when your plugin disables.

🧠 Technical Notes

• Officially provided modules include Spigot, Velocity, BungeeCord, Fabric and Sponge.
• The project notes the Spigot module is designed to work on widely-used forks such as Paper, Purpur and Folia, and the BungeeCord module is intended to work on Waterfall.
• The project is published with source, releases and Javadocs; it is licensed under GPL-3.0.
• The library is intended to be added with provided/compileOnly scope for plugin builds when bundling is not desired; bundling instructions are documented for cases where a plugin includes PacketEvents in its distribution.

🤝 When This Plugin Is Useful

If your project requires direct control over the Minecraft protocol—for custom authentication, packet-based effects, proxy handling, or low-level integrations—PacketEvents provides a cross-platform API and lifecycle management so you can build those features without reimplementing protocol handling per server or proxy implementation.