Create modern Paper plugin artifact

.github/CONTRIBUTING.md

@@ -6,15 +6,17 @@ development, so keep changes focused and preserve existing behavior unless a bre
 
 ## Building ProtocolLib
 
-Use the Gradle wrapper from the repository root. The build uses the Java 25 toolchain and resolves the current Spigot
-server dependency from the CodeMC repository.
+Use the Gradle wrapper from the repository root. The root project builds the platform-neutral library published to
+Maven. The `paper` module compiles and tests it against Paper's development bundle and produces the primary plugin,
+`build/libs/ProtocolLib.jar`. The `spigot` compatibility module produces `build/libs/ProtocolLib-Spigot.jar`.
 
 ```shell
 ./gradlew test
 ./gradlew build shadowJar
 ```
 
-`shadowJar` produces `build/libs/ProtocolLib.jar` with the required Byte Buddy classes included.
+`shadowJar` builds both plugin distributions with the required Byte Buddy classes included. Neither platform provider
+nor plugin descriptor is included in the Maven core artifact.
 
 ProtocolLib uses the Java 25 toolchain to compile against the current server, but production classes target Java 17 for
 compatibility with older supported servers.
@@ -26,7 +28,7 @@ server classes. The server packet classes and codecs are authoritative when docu
 
 ### 1. Update version metadata
 
-- Update `mcVersion` in `build.gradle.kts`.
+- Update `mcVersion` in `gradle.properties`.
 - Add the release to `MinecraftVersion` and update `MinecraftVersion.LATEST`.
 - Update `ProtocolLibrary.MAXIMUM_MINECRAFT_VERSION` and `ProtocolLibrary.MINECRAFT_LAST_RELEASE_DATE`.
 - Update `MinecraftProtocolVersion` if the release changed the protocol number.
@@ -57,7 +59,7 @@ serverbound and clientbound packet classes and codecs against every protocol pha
 ### 4. Add regression coverage
 
 - Initialize the test environment with `BukkitInitialization` when tests access CraftBukkit or NMS classes.
-- Exercise the actual packet structure supplied by the current Spigot dependency.
+- Exercise the actual packet structure supplied by the current Paper dependency.
 - Cover both sides of a version guard when feasible.
 - Re-enable previously disabled tests when the underlying incompatibility is fixed.
 - Run targeted tests while developing, followed by `./gradlew test`.

.github/workflows/build.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
-          java-version: '21'
+          java-version: '25'
           cache: 'gradle'
 
       - name: Run gradle build lifecycle
@@ -27,4 +27,6 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: ProtocolLib
-          path: build/libs/ProtocolLib.jar
+          path: |
+            build/libs/ProtocolLib.jar
+            build/libs/ProtocolLib-Spigot.jar

.github/workflows/dev-build.yml

@@ -16,7 +16,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
-          java-version: '21'
+          java-version: '25'
           cache: 'gradle'
 
       - name: Run gradle build lifecycle
@@ -27,7 +27,9 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: ProtocolLib
-          path: build/libs/ProtocolLib.jar
+          path: |
+            build/libs/ProtocolLib.jar
+            build/libs/ProtocolLib-Spigot.jar
 
       - name: Create or update GitHub pre-release
         env:
@@ -41,3 +43,4 @@ jobs:
           NEW_NOTES="$RELEASE_NOTES"$'\n'"* [$SHORT_HASH] $COMMIT_MSG"
           gh release edit dev-build --notes "$NEW_NOTES" --repo ${{ github.repository }}
           gh release upload dev-build build/libs/ProtocolLib.jar#ProtocolLib.jar --clobber --repo ${{ github.repository }}
+          gh release upload dev-build build/libs/ProtocolLib-Spigot.jar#ProtocolLib-Spigot.jar --clobber --repo ${{ github.repository }}

Readme.md

@@ -18,12 +18,15 @@ lead to more subtle bugs.
 * [JavaDoc](https://dmulloy2.net/ProtocolLib/javadoc/)
 * [Protocol Wiki](https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol)
 
+`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](https://gradle.org/). 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.
+(ByteBuddy) included for both Paper and Spigot.
 
 ### A new API
 

build.gradle.kts

@@ -1,18 +1,15 @@
-import org.gradle.api.tasks.testing.logging.TestExceptionFormat
-
 plugins {
     `java-library`
     `maven-publish`
     signing
-    id("com.gradleup.shadow") version "9.4.0"
     id("io.github.patrick.remapper") version "1.4.3"
     id("com.vanniktech.maven.publish") version "0.36.0"
 }
 
 group = "net.dmulloy2"
 description = "Provides access to the Minecraft protocol"
 
-val mcVersion = "26.2"
+val mcVersion: String by project
 val isSnapshot = version.toString().endsWith("-SNAPSHOT")
 val isJitPack = System.getenv("JITPACK")?.equals("true", ignoreCase = true) ?: false
 val commitHash = System.getenv("COMMIT_SHA") ?: ""
@@ -46,20 +43,11 @@ repositories {
 dependencies {
     implementation("net.bytebuddy:byte-buddy:1.18.2")
     compileOnly("org.spigotmc:spigot-api:${mcVersion}-R0.1-SNAPSHOT")
-    compileOnly("org.spigotmc:spigot:${mcVersion}-R0.1-SNAPSHOT")//:remapped-mojang")
+    compileOnly("org.spigotmc:spigot:${mcVersion}-R0.1-SNAPSHOT")
     compileOnly("io.netty:netty-all:4.2.8.Final")
     compileOnly("net.kyori:adventure-text-serializer-gson:4.25.0")
     compileOnly("com.googlecode.json-simple:json-simple:1.1.1")
-
-    testImplementation("org.junit.jupiter:junit-jupiter-engine:6.0.1")
-    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:6.0.1")
-    testRuntimeOnly("org.junit.platform:junit-platform-launcher:6.0.1")
-    testImplementation("org.mockito:mockito-core:5.21.0")
-    testImplementation("io.netty:netty-common:4.2.8.Final")
-    testImplementation("io.netty:netty-transport:4.2.8.Final")
-    testImplementation("org.spigotmc:spigot:${mcVersion}-R0.1-SNAPSHOT")//:remapped-mojang")
-    testImplementation("net.kyori:adventure-text-serializer-gson:4.25.0")
-    testImplementation("net.kyori:adventure-text-serializer-plain:4.25.0")
+    compileOnly("commons-lang:commons-lang:2.6")
 }
 
 java {
@@ -68,49 +56,22 @@ java {
     }
 }
 
-tasks {
-    processResources {
-        val fullVersion = if (isSnapshot && isCI) "${version}-${commitHash.take(7)}" else version
-
-        eachFile {
-            expand("version" to fullVersion)
-        }
-    }
-
+sourceSets {
     test {
-        useJUnitPlatform()
-        testLogging {
-            exceptionFormat = TestExceptionFormat.FULL
-        }
+        java.setSrcDirs(emptyList<String>())
+        resources.setSrcDirs(emptyList<String>())
     }
+}
 
-    shadowJar {
-        dependencies {
-            include(dependency("net.bytebuddy:byte-buddy:.*"))
-        }
-        relocate("net.bytebuddy", "com.comphenix.net.bytebuddy")
-
-        manifest {
-            attributes(
-                "paperweight-mappings-namespace" to "mojang"
-            )
-        }
-
-        archiveFileName = "ProtocolLib.jar"
+tasks {
+    test {
+        dependsOn(":paper:test")
     }
 
-    /*remap {
-        dependsOn("shadowJar")
-
-        inputTask.set(getByName<ShadowJar>("shadowJar"))
-        version.set(mcVersion)
-        action.set(RemapTask.Action.MOJANG_TO_SPIGOT)
+    check {
+        dependsOn(":paper:check", ":spigot:check")
     }
 
-    assemble {
-        dependsOn("remap")
-    }*/
-
     javadoc {
         options.encoding = "UTF-8"
     }
@@ -121,6 +82,12 @@ tasks {
     }
 }
 
+tasks.register("shadowJar") {
+    group = "build"
+    description = "Builds the Paper and Spigot plugin distributions."
+    dependsOn(":paper:shadowJar", ":spigot:shadowJar")
+}
+
 mavenPublishing {
     publishToMavenCentral()
     if (!isSnapshot && !isJitPack) {

gradle.properties

@@ -1,4 +1,5 @@
 version=5.5.0-SNAPSHOT
+mcVersion=26.2
 mavenCentralUsername=
 mavenCentralPassword=
 signing.keyId=

paper/build.gradle.kts

@@ -0,0 +1,93 @@
+import org.gradle.api.tasks.testing.logging.TestExceptionFormat
+
+plugins {
+    `java-library`
+    id("com.gradleup.shadow") version "9.4.0"
+    id("io.papermc.paperweight.userdev") version "2.0.0-beta.21"
+}
+
+group = "net.dmulloy2"
+version = rootProject.version
+
+val mcVersion: String by project
+val isSnapshot = version.toString().endsWith("-SNAPSHOT")
+val commitHash = System.getenv("COMMIT_SHA") ?: ""
+val isCI = commitHash.isNotEmpty()
+
+repositories {
+    mavenLocal()
+    mavenCentral()
+    maven("https://repo.papermc.io/repository/maven-public/")
+    maven("https://repo.codemc.io/repository/nms/")
+    maven("https://hub.spigotmc.org/nexus/content/groups/public/")
+    maven("https://libraries.minecraft.net/") {
+        metadataSources {
+            mavenPom()
+            artifact()
+            ignoreGradleMetadataRedirection()
+        }
+    }
+}
+
+dependencies {
+    implementation(project(":"))
+    paperweight.paperDevBundle("$mcVersion.build.+")
+
+    compileOnly("io.netty:netty-all:4.2.8.Final")
+    compileOnly("net.kyori:adventure-text-serializer-gson:4.25.0")
+    compileOnly("commons-lang:commons-lang:2.6")
+
+    testImplementation("org.junit.jupiter:junit-jupiter-engine:6.0.1")
+    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:6.0.1")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher:6.0.1")
+    testImplementation("org.mockito:mockito-core:5.21.0")
+    testImplementation("io.netty:netty-common:4.2.8.Final")
+    testImplementation("io.netty:netty-transport:4.2.8.Final")
+    testImplementation("net.kyori:adventure-text-serializer-gson:4.25.0")
+    testImplementation("net.kyori:adventure-text-serializer-plain:4.25.0")
+    testImplementation("commons-lang:commons-lang:2.6")
+}
+
+paperweight.reobfArtifactConfiguration =
+    io.papermc.paperweight.userdev.ReobfArtifactConfiguration.MOJANG_PRODUCTION
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(25))
+    }
+}
+
+sourceSets {
+    test {
+        java.srcDir(rootProject.file("src/test/java"))
+        resources.srcDir(rootProject.file("src/test/resources"))
+    }
+}
+
+tasks {
+    processResources {
+        val fullVersion = if (isSnapshot && isCI) "${version}-${commitHash.take(7)}" else version
+
+        eachFile {
+            expand("version" to fullVersion)
+        }
+    }
+
+    test {
+        useJUnitPlatform()
+        testLogging {
+            exceptionFormat = TestExceptionFormat.FULL
+        }
+    }
+
+    shadowJar {
+        relocate("net.bytebuddy", "com.comphenix.net.bytebuddy")
+
+        manifest {
+            attributes("paperweight-mappings-namespace" to "mojang")
+        }
+
+        destinationDirectory.set(rootProject.layout.buildDirectory.dir("libs"))
+        archiveFileName.set("ProtocolLib.jar")
+    }
+}