A Beginner's Guide to Bundling

So, you’ve decided you want to bundle PacketEvents in your distribution file. If you do not wish to bundle, please skip this section. There are a few things you need to do to avoid running into issues when bundling. Here’s a summary of the steps:

A note about Fabric

Please use fabric jar-in-jar mods for including the PacketEvents mod. This is not covered by this documentation page in its current state.

1. Setup Maven/Gradle

   You will need to set up Maven/Gradle in a particular way if you desire to bundle PacketEvents.

2. Add Necessary Soft Dependencies

   You must configure your plugin in such a way that it loads after a certain set of plugins. This way, you avoid running into issues when bundling.

3. Relocate PacketEvents

   You need to relocate PacketEvents’ packages to avoid version conflicts. Do not assume that you’re the only one bundling.

4. Minimize PacketEvents (not recommended)

   You may optionally minimize PacketEvents to reduce the size of your project. This process will remove classes within PacketEvents that are unused.

1. Setup Maven/Gradle for Bundling

Maven

pom.xml

<repositories>
    <repository>
        <id>codemc-releases</id>
        <url>https://repo.codemc.io/repository/maven-releases/</url>
    </repository>
    <repository>
        <id>codemc-snapshots</id>
        <url>https://repo.codemc.io/repository/maven-snapshots/</url>
    </repository>
    <!-- your other repositories... -->
</repositories>
    <!-- ... -->
<dependencies>
<dependency>
    <groupId>com.github.retrooper</groupId>
    <artifactId>packetevents-INSERT_MODULE_HERE</artifactId>
    <version>2.11.2</version>
    <scope>compile</scope>
</dependency>
<!-- your other dependencies... -->
</dependencies>

Gradle

build.gradle[.kts]

repositories {
    maven { url = uri("https://repo.codemc.io/repository/maven-releases/") }
    maven { url = uri("https://repo.codemc.io/repository/maven-snapshots/") }
    // your other repositories...
}

dependencies {
    implementation("com.github.retrooper:packetevents-INSERT_MODULE_HERE:2.11.2")
    // your other dependencies...
}

Warning

The Maven/Gradle code sections above include the placeholder ‘INSERT_MODULE_HERE’; please replace it with one of the supported modules.

2. Add Necessary Soft Dependencies

If you’re developing for Bukkit-based platforms, this section was written for you. It’s very important that you configure your plugin.yml in such a way that it has the following plugins as soft dependencies:

plugin.yml

softdepend:
- ProtocolLib
- ProtocolSupport
- ViaVersion
- ViaBackwards
- ViaRewind
- Geyser-Spigot

The reason we’re adding these plugins as soft dependencies is so that your plugin loads after these plugins are loaded (if present on the server). The PacketEvents injector requires these plugins to be loaded before it starts the network injection process. Failure to add these soft dependencies can lead to exceptions and software malfunctions.

3. Relocate PacketEvents

We need to relocate PacketEvents’ packages. This step is required so that we can avoid any version conflicts. It’s possible that PacketEvents is already present on your server; thus, we must account for version conflicts. This can be achieved by configuring the Maven Shade Plugin for Apache Maven or Shadow Plugin for Gradle.

Maven

pom.xml

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.6.1</version>
        <executions>
            <execution>
                <phase>package</phase>
                <goals>
                    <goal>shade</goal>
                </goals>
                <configuration>
                    <minimizeJar>false</minimizeJar>
                    <createDependencyReducedPom>false</createDependencyReducedPom>
                    <relocations>
                        <relocation>
                            <pattern>com.github.retrooper</pattern>
                            <shadedPattern>my.domain.myplugin.libs.packetevents</shadedPattern>
                        </relocation>
                        <relocation>
                            <pattern>io.github.retrooper</pattern>
                            <shadedPattern>my.domain.myplugin.libs.packetevents</shadedPattern>
                        </relocation>
                        <relocation>
                            <pattern>net.kyori</pattern>
                            <shadedPattern>my.domain.myplugin.libs.kyori</shadedPattern>
                        </relocation>
                        <relocation>
                            <pattern>com.google.gson</pattern>
                            <shadedPattern>my.domain.myplugin.libs.gson</shadedPattern>
                        </relocation>
                    </relocations>
                </configuration>
            </execution>
        </executions>
    </plugin>
    <!-- your other plugins... -->
</plugins>

Gradle

build.gradle[.kts]

plugins {
    id("com.gradleup.shadow") version "9.3.1"
    // your other plugins...
}

tasks.shadowJar {
    relocate("com.github.retrooper", "my.domain.myplugin.libs.packetevents")
    relocate("io.github.retrooper", "my.domain.myplugin.libs.packetevents")
    relocate("net.kyori", "my.domain.myplugin.libs.kyori")
    relocate("com.google.gson", "my.domain.myplugin.libs.gson")
}

4. Minimize PacketEvents (optional)

Last but not least, you can minimize PacketEvents. Unused PacketEvents classes will be discarded from your distribution file, allowing you to save a little space. Please note that this is not recommended and sometimes cause some classloading issues to occur.

Maven

pom.xml

    <goal>shade</goal>
</goals>
<configuration>
    <minimizeJar>false</minimizeJar>
    <minimizeJar>true</minimizeJar>
    <createDependencyReducedPom>false</createDependencyReducedPom>
    <relocations>
        <relocation>

Gradle

build.gradle.kts

tasks.shadowJar {
    minimize()
}

Testing

Now, you’ve hopefully successfully relocated PacketEvents. Please ensure that your output or distribution file contains PacketEvents packages, which contain ‘com.github.retrooper’ and ‘io.github.retrooper’. The package containing ‘com.github.retrooper’ refers to the PacketEvents cross-platform API. These are API features that work on every platform. The package that contains ‘io.github.retrooper’ refers to the implementation of PacketEvents. Without an implementation, PacketEvents cannot function.