feat(events): migrate distribution to Java 25 and Purpur

BREAKING CHANGE: New releases require Java 25/Purpur 26.2 and use purpur-event-producer-<version>.jar. Runtime SpigotEventProducer identity, server UUID, SQLite outbox and CloudEvent delivery contracts remain unchanged. Replace the old JAR rather than installing both distributions.

.gitea/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 17
+          java-version: 25
           cache: gradle
 
       - name: Validate conventional commits
@@ -32,15 +32,9 @@ jobs:
       - name: Build and test
         run: ./gradlew clean check jar
 
-      - name: Name development artifact
-        run: |
-          short_sha=$(printf '%s' "$GITHUB_SHA" | cut -c1-7)
-          cp build/libs/spigot-event-producer-0.1.0-SNAPSHOT.jar \
-            "build/libs/spigot-event-producer-dev-${short_sha}.jar"
-
       - name: Upload development artifact
         uses: actions/upload-artifact@v3
         with:
-          name: spigot-event-producer-${{ github.sha }}
+          name: purpur-event-producer-${{ github.sha }}
-          path: build/libs/spigot-event-producer-dev-*.jar
+          path: build/libs/*.jar
           if-no-files-found: error

.gitea/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 17
+          java-version: 25
           cache: gradle
 
       - name: Set up Node.js
@@ -46,9 +46,9 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
         run: |
           npx -y \
-            -p semantic-release \
+            -p semantic-release@24.2.9 \
-            -p @semantic-release/commit-analyzer \
+            -p @semantic-release/commit-analyzer@13.0.1 \
-            -p @semantic-release/release-notes-generator \
+            -p @semantic-release/release-notes-generator@14.1.0 \
             semantic-release \
             --branches main \
             --plugins @semantic-release/commit-analyzer,@semantic-release/release-notes-generator
@@ -86,8 +86,8 @@ jobs:
         if: steps.release.outputs.created == 'true'
         uses: actions/upload-artifact@v3
         with:
-          name: spigot-event-producer-${{ steps.release.outputs.version }}
+          name: purpur-event-producer-${{ steps.release.outputs.version }}
-          path: build/libs/spigot-event-producer-${{ steps.release.outputs.version }}.jar
+          path: build/libs/purpur-event-producer-${{ steps.release.outputs.version }}.jar
           if-no-files-found: error
 
       - name: Create Gitea release and upload plugin
@@ -101,7 +101,7 @@ jobs:
           PREVIOUS_TAG: ${{ steps.previous_tag.outputs.value }}
         run: |
           api_url="${GITEA_SERVER_URL}/api/v1"
-          jar="build/libs/spigot-event-producer-${VERSION}.jar"
+          jar="build/libs/purpur-event-producer-${VERSION}.jar"
           export RELEASE_BODY
           if [ -n "$PREVIOUS_TAG" ]; then
             RELEASE_BODY=$(git log --pretty='format:- %s (%h)' "${PREVIOUS_TAG}..HEAD")
@@ -138,4 +138,4 @@ jobs:
             -H "Authorization: token ${GITEA_TOKEN}" \
             -H "Content-Type: application/octet-stream" \
             --data-binary "@${jar}" \
-            "${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=spigot-event-producer-${VERSION}.jar"
+            "${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=purpur-event-producer-${VERSION}.jar"

AGENTS.md

@@ -0,0 +1,9 @@
+# purpur-event-producer agent entrypoint
+
+The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md).
+
+Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/purpur-event-producer/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/purpur-event-producer/` stories. Also follow the parent workspace `AGENTS.md` when present.
+
+For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/purpur-event-producer/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access.
+
+Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push.

README.md

@@ -1,18 +1,20 @@
-# Spigot Event Producer
+# Purpur Event Producer
 
-A Spigot 26.2 plugin that records Minecraft activity as CloudEvents 1.0, persists it in a local SQLite outbox, and sends newline-delimited batches to `game-ingest-server`.
+A Purpur 26.2 plugin that records Minecraft activity as CloudEvents 1.0, persists it in a local SQLite outbox, and sends newline-delimited batches to `game-ingest-server`.
 
 ## Requirements
 
-- Spigot 26.2
+- Purpur 26.2 build 2618
-- Java 17 or newer
+- Java 25
 - Network access to the ingest endpoint
 
+The repository, checkout and new artifacts use `purpur-event-producer`. Runtime `SpigotEventProducer`, Java entrypoint/packages, existing configuration/server UUID and `plugins/SpigotEventProducer/event-outbox.sqlite3` remain unchanged, as do CloudEvent types/source/payloads and delivery semantics. The SQLite driver stays bundled. Replace the old JAR rather than installing both distributions. Old tags/assets remain available; new releases no longer support Java 17.
+
 ## Build and install
 
 ```bash
-./gradlew clean test jar
+./gradlew clean check jar
-cp build/libs/spigot-event-producer-0.1.0-SNAPSHOT.jar /path/to/server/plugins/
+cp build/libs/purpur-event-producer-0.1.0-SNAPSHOT.jar /path/to/server/plugins/
 ```
 
 Start the Minecraft server once to create `plugins/SpigotEventProducer/config.yml`. Set a meaningful, stable `server-name`. When `server-id` is empty, the plugin generates and persists a UUID. Do not reuse that generated UUID on another server.
@@ -52,7 +54,7 @@ Public chat events contain the complete message text.
 
 Private-message events recognize `/msg`, `/message`, `/tell`, `/w`, `/whisper`, `/pm`, `/reply`, and `/r`, including namespaced variants such as `/minecraft:tell`. Explicit commands contain the destination token. Reply commands set `reply: true` and omit the recipient so downstream processing can infer it from earlier ordered events. The event also reports whether the command was cancelled.
 
-Spigot has no universal private-message event. Commands implemented with unrelated aliases or entirely custom plugin logic will not be recognized until their syntax is added. A recognized command event reports observation of the command, not guaranteed delivery to its recipient.
+The Bukkit-compatible server API has no universal private-message event. Commands implemented with unrelated aliases or entirely custom plugin logic will not be recognized until their syntax is added. A recognized command event reports observation of the command, not guaranteed delivery to its recipient.
 
 ### Location snapshots
 
@@ -114,7 +116,7 @@ Gitea Actions runs the Gradle checks for every push and pull request and stores
 - `feat:` creates a minor release;
 - a breaking-change footer or `!` creates a major release.
 
-A successful release creates a `vX.Y.Z` tag and attaches `spigot-event-producer-X.Y.Z.jar` permanently to the corresponding Gitea Release. The release workflow requires a repository secret named `RELEASE_TOKEN` with repository contents write permission.
+A successful release creates a `vX.Y.Z` tag and attaches `purpur-event-producer-X.Y.Z.jar` permanently to the corresponding Gitea Release. The release workflow requires a repository secret named `RELEASE_TOKEN` with repository contents write permission.
 
 For a local versioned build:
 

build.gradle.kts

@@ -9,12 +9,12 @@ version = providers.gradleProperty("releaseVersion")
 
 repositories {
     mavenCentral()
-    maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/")
+    maven("https://repo.purpurmc.org/snapshots/")
 }
 
 java {
     toolchain {
-        languageVersion = JavaLanguageVersion.of(17)
+        languageVersion = JavaLanguageVersion.of(25)
     }
 }
 
@@ -23,10 +23,10 @@ tasks.withType<JavaCompile>().configureEach {
 }
 
 dependencies {
-    compileOnly("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
+    compileOnly("org.purpurmc.purpur:purpur-api:26.2.build.2618-stable")
     implementation("org.xerial:sqlite-jdbc:3.50.3.0")
 
-    testImplementation("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
+    testImplementation("org.purpurmc.purpur:purpur-api:26.2.build.2618-stable")
     testImplementation(platform("org.junit:junit-bom:5.13.4"))
     testImplementation("org.junit.jupiter:junit-jupiter")
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
@@ -34,6 +34,9 @@ dependencies {
 
 tasks.test {
     useJUnitPlatform()
+    dependsOn(tasks.jar)
+    systemProperty("distribution.jar", tasks.jar.get().archiveFile.get().asFile.absolutePath)
+    systemProperty("distribution.version", project.version.toString())
 }
 
 val pluginVersion = version

settings.gradle.kts

@@ -1 +1 @@
-rootProject.name = "spigot-event-producer"
+rootProject.name = "purpur-event-producer"

src/main/java/games/dmg/spigotevents/stats/BukkitRegistryKeys.java

@@ -0,0 +1,21 @@
+package games.dmg.spigotevents.stats;
+
+import org.bukkit.Keyed;
+import org.bukkit.NamespacedKey;
+
+final class BukkitRegistryKeys {
+    private BukkitRegistryKeys() {}
+
+    static NamespacedKey get(Keyed value) {
+        try {
+            return value.getKey();
+        } catch (IllegalArgumentException ignored) {
+            return null;
+        }
+    }
+
+    static String format(Keyed value, String fallback) {
+        NamespacedKey key = get(value);
+        return key == null ? fallback : key.toString();
+    }
+}

src/main/java/games/dmg/spigotevents/stats/PlayerSnapshotCollector.java

@@ -44,8 +44,7 @@ public final class PlayerSnapshotCollector {
         data.put("pitch", location.getPitch());
         data.put("game_mode", player.getGameMode().name().toLowerCase());
         var biome = location.getBlock().getBiome();
-        var biomeKey = biome.getKeyOrNull();
+        data.put("biome", BukkitRegistryKeys.format(biome, biome.toString()));
-        data.put("biome", biomeKey == null ? biome.toString() : biomeKey.toString());
         publish("player.location", identity(player), data);
     }
 
@@ -157,9 +156,13 @@ public final class PlayerSnapshotCollector {
                 if ((blocksOnly && !material.isBlock()) || (!blocksOnly && !material.isItem())) {
                     continue;
                 }
+                var materialKey = BukkitRegistryKeys.get(material);
+                if (materialKey == null) {
+                    continue;
+                }
                 try {
                     target.put(
-                            statistic.getKey() + "/" + material.getKeyOrThrow(),
+                            statistic.getKey() + "/" + materialKey,
                             currentPlayer.getStatistic(statistic, material));
                 } catch (IllegalArgumentException ignored) {
                     // Bukkit rejects combinations not represented by the game.
@@ -180,9 +183,13 @@ public final class PlayerSnapshotCollector {
             while (operations < budget && subtypeIndex < ENTITY_TYPES.length) {
                 EntityType entityType = ENTITY_TYPES[subtypeIndex++];
                 operations++;
+                var entityTypeKey = BukkitRegistryKeys.get(entityType);
+                if (entityTypeKey == null) {
+                    continue;
+                }
                 try {
                     target.put(
-                            statistic.getKey() + "/" + entityType.getKeyOrThrow(),
+                            statistic.getKey() + "/" + entityTypeKey,
                             currentPlayer.getStatistic(statistic, entityType));
                 } catch (IllegalArgumentException ignored) {
                     // Bukkit rejects unsupported entity types.

src/test/java/games/dmg/spigotevents/PurpurDistributionTest.java

@@ -0,0 +1,57 @@
+package games.dmg.spigotevents;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.DataInputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.jar.JarFile;
+import org.junit.jupiter.api.Test;
+import org.yaml.snakeyaml.Yaml;
+
+class PurpurDistributionTest {
+    @Test
+    void packagesNewNameWithoutChangingRuntimeIdentityOrBundlingTheApi() throws Exception {
+        Path artifact = Path.of(System.getProperty("distribution.jar"));
+        String version = System.getProperty("distribution.version");
+        assertEquals("purpur-event-producer-" + version + ".jar", artifact.getFileName().toString());
+        try (var jar = new JarFile(artifact.toFile())) {
+            Map<?, ?> metadata = new Yaml().load(jar.getInputStream(jar.getJarEntry("plugin.yml")));
+            assertEquals(version, metadata.get("version"));
+            assertEquals("SpigotEventProducer", metadata.get("name"), "Retain the data directory and persistent namespace");
+            assertEquals("games.dmg.spigotevents.SpigotEventProducerPlugin", metadata.get("main"));
+            assertFalse(metadata.containsKey("permissions"));
+            assertFalse(metadata.containsKey("commands"));
+            assertNotNull(jar.getJarEntry("org/sqlite/JDBC.class"), "The SQLite driver must remain bundled");
+            assertNotNull(jar.getJarEntry("META-INF/services/java.sql.Driver"));
+            assertEquals("true", jar.getManifest().getMainAttributes().getValue("Multi-Release"));
+            assertFalse(jar.stream().anyMatch(entry -> entry.getName().startsWith("org/bukkit/")
+                || entry.getName().startsWith("org/purpurmc/") || entry.getName().endsWith("Test.class")));
+        }
+    }
+
+    @Test
+    void pluginBytecodeTargetsJava25() throws Exception {
+        try (var jar = new JarFile(System.getProperty("distribution.jar"));
+             var bytecode = new DataInputStream(jar.getInputStream(
+                 jar.getJarEntry("games/dmg/spigotevents/SpigotEventProducerPlugin.class")))) {
+            assertEquals(0xCAFEBABE, bytecode.readInt());
+            bytecode.readUnsignedShort();
+            assertEquals(69, bytecode.readUnsignedShort());
+        }
+    }
+
+    @Test
+    void releaseAndCiAgreeWithThePurpurDistributionNameAndToolchain() throws Exception {
+        String build = Files.readString(Path.of("build.gradle.kts"));
+        assertTrue(build.contains("purpur-api:26.2.build.2618-stable"));
+        assertFalse(build.contains("org.spigotmc:spigot-api"));
+        for (String workflow : new String[] {"ci.yml", "release.yml"}) {
+            String content = Files.readString(Path.of(".gitea/workflows", workflow));
+            assertTrue(content.contains("java-version: 25"));
+            assertTrue(content.contains("purpur-event-producer-"), workflow);
+            assertFalse(content.contains("spigot-event-producer-"), workflow);
+        }
+    }
+}

src/test/java/games/dmg/spigotevents/stats/BukkitRegistryKeysTest.java

@@ -0,0 +1,33 @@
+package games.dmg.spigotevents.stats;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import org.bukkit.NamespacedKey;
+import org.bukkit.Keyed;
+import org.junit.jupiter.api.Test;
+
+class BukkitRegistryKeysTest {
+    @Test
+    void formatsARegisteredKey() {
+        Keyed keyed = () -> NamespacedKey.minecraft("plains");
+
+        assertEquals("minecraft:plains", BukkitRegistryKeys.format(keyed, "fallback"));
+    }
+
+    @Test
+    void reportsAnUnavailableKey() {
+        Keyed keyed = () -> null;
+
+        assertNull(BukkitRegistryKeys.get(keyed));
+    }
+
+    @Test
+    void reportsAKeyThatBukkitRejectsAsUnavailable() {
+        Keyed keyed = () -> {
+            throw new IllegalArgumentException("Registry entry does not have a key");
+        };
+
+        assertNull(BukkitRegistryKeys.get(keyed));
+    }
+}