Creating a PacketEvents Instance

Do You Need a PacketEvents Instance?

Many features offered by PacketEvents are accessible through a PacketEvents instance. Depending on your setup, you may have to create your own PacketEvents instance as soon as your mod/plugin launches. If you’re bundling PacketEvents in your distribution file, then you need to create a PacketEvents instance. If you’re not bundling, then do not create an instance. The user will have to proactively install PacketEvents, and PacketEvents will create an instance for you.

If you’re not bundling, you can ignore this page.

The PacketEvents instance allows you to access functionality within our API. This instance can be created using a PacketEventsBuilder. Each platform has its own PacketEventsBuilder, and each builder carries its own implementation of the PacketEvents library.

Basic Example

The PacketEvents instance provides two methods for initialization: load and init. You must call load before calling init. PacketEvents also provides a termination method, terminate, which should be called when your plugin shuts down.

Below is an example of how to properly initialize and terminate PacketEvents in the Main class on Bukkit‑based platforms:

import com.github.retrooper.packetevents.PacketEvents;
import io.github.retrooper.packetevents.factory.spigot.SpigotPacketEventsBuilder;
import org.bukkit.plugin.java.JavaPlugin;

public class YourBukkitPlugin extends JavaPlugin {

    @Override
    public void onLoad() {
        // Building, loading, and initializing the library is necessary when bundling.
        PacketEvents.setAPI(SpigotPacketEventsBuilder.build(this));
        PacketEvents.getAPI().load();

        /*
         * MORE CODE MAY APPEAR HERE (such as registering listeners)
         */
    }

    @Override
    public void onEnable() {
        // Initialize the library!
        PacketEvents.getAPI().init();
    }

    @Override
    public void onDisable() {
        // Clean-up process
        PacketEvents.getAPI().terminate();
    }
}

Below is an example of initialization and termination of PacketEvents for a non-Bukkit-based platform, like Velocity:

import com.github.retrooper.packetevents.PacketEvents;
import com.google.common.eventbus.Subscribe;
import com.velocitypowered.api.event.proxy.ProxyInitializeEvent;
import com.velocitypowered.api.event.proxy.ProxyShutdownEvent;
import com.velocitypowered.api.plugin.Plugin;
import com.velocitypowered.api.plugin.PluginContainer;
import com.velocitypowered.api.plugin.annotation.DataDirectory;
import com.velocitypowered.api.proxy.ProxyServer;
import io.github.retrooper.packetevents.velocity.factory.VelocityPacketEventsBuilder;
import jakarta.inject.Inject;
import org.slf4j.Logger;

import java.nio.file.Path;

@Plugin(...)
public class YourVelocityPlugin {

    private final ProxyServer server;
    private final Logger logger;
    private final PluginContainer pluginContainer;
    private final Path dataDirectory;

    @Inject
    public YourVelocityPlugin(
            final ProxyServer server,
            final Logger logger,
            final PluginContainer pluginContainer,
            final @DataDirectory Path dataDirectory
    ) {
        this.server = server;
        this.logger = logger;
        this.pluginContainer = pluginContainer;
        this.dataDirectory = dataDirectory;
    }

    @Subscribe
    public void onProxyInitialize(final ProxyInitializeEvent event) {
        PacketEvents.setAPI(VelocityPacketEventsBuilder.build(this.server, this.pluginContainer, this.logger, this.dataDirectory));
        PacketEvents.getAPI().load();

        /*
         * MORE CODE MAY APPEAR HERE (such as registering listeners)
         */
        PacketEvents.getAPI().init();
    }

    @Subscribe
    public void onProxyShutdown(ProxyShutdownEvent event) {
        PacketEvents.getAPI().terminate();
    }
}