Add Minecraft 1.8.8–1.20.6 legacy compatibility

.github/workflows/compatibility.yml

@@ -0,0 +1,60 @@
+name: Compatibility Matrix
+
+on:
+  push:
+    paths:
+      - "pom.xml"
+      - "headdb-api/**"
+      - "headdb-core/**"
+      - "headdb-legacy/**"
+      - ".github/workflows/compatibility.yml"
+  pull_request:
+    paths:
+      - "pom.xml"
+      - "headdb-api/**"
+      - "headdb-core/**"
+      - "headdb-legacy/**"
+      - ".github/workflows/compatibility.yml"
+  workflow_dispatch:
+
+jobs:
+  modern:
+    name: Modern Paper API ${{ matrix.paper }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - paper: 1.21-R0.1-SNAPSHOT
+            java: "21"
+          - paper: 26.2.build.112-stable
+            java: "25"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: maven
+      - run: mvn -B -ntp -pl headdb-core -am clean verify -Dpaper.version=${{ matrix.paper }}
+
+  legacy:
+    name: Legacy Spigot API ${{ matrix.spigot }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        spigot:
+          - 1.8.8-R0.1-SNAPSHOT
+          - 1.13.2-R0.1-SNAPSHOT
+          - 1.16.5-R0.1-SNAPSHOT
+          - 1.18.2-R0.1-SNAPSHOT
+          - 1.20.6-R0.1-SNAPSHOT
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: maven
+      - run: mvn -B -ntp -pl headdb-legacy -am clean verify -Dspigot.version=${{ matrix.spigot }}

.github/workflows/release.yml

@@ -9,7 +9,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Tag to release (example: v6.0.2)"
+        description: "Tag to release (example: v6.0.3)"
         required: true
         type: string
 
@@ -108,6 +108,7 @@ jobs:
           body_path: ${{ steps.metadata.outputs.changelog_file }}
           files: |
             headdb-core/target/HeadDB-*.jar
+            headdb-legacy/target/HeadDB-*-legacy.jar
           fail_on_unmatched_files: true
 
       - name: Create release with generated notes
@@ -119,4 +120,5 @@ jobs:
           generate_release_notes: true
           files: |
             headdb-core/target/HeadDB-*.jar
+            headdb-legacy/target/HeadDB-*-legacy.jar
           fail_on_unmatched_files: true

README.md

@@ -35,11 +35,31 @@
 
 ## 🚀 Download & Installation
 
-HeadDB 6.0.2 targets Minecraft/Paper 26.2 and requires Java 25. Use the regular
-`HeadDB-6.0.2.jar` on Paper. The separately named `-Spigot.jar` artifact bundles
-the compatibility libraries needed by Spigot; Paper remains the recommended
-server platform. Folia is not currently supported because the bundled menu
-framework is not region-thread safe.
+HeadDB 6.0.3 is distributed as two server-specific jars. Install exactly one:
+
+| File | Server versions | Java | Purpose |
+|---|---|---|---|
+| `HeadDB-6.0.3.jar` | Paper 1.21.0 and newer | Java 21+ | The full modern plugin and the recommended download. |
+| `HeadDB-6.0.3-legacy.jar` | Bukkit-compatible 1.8.8-1.20.6 | Java 8 bytecode* | The isolated implementation for servers before 1.21. |
+
+\* Use the Java version required by the Minecraft server. The legacy plugin
+itself is Java 8-compatible, but later Minecraft releases require newer Java
+runtimes (for example, Java 17 or Java 21).
+
+Do not install both jars on the same server. The old `-Spigot.jar` classifier no
+longer exists: the modern artifact uses Paper APIs, while the legacy artifact is
+compiled against the 1.8.8 Spigot API, is compatibility-tested through the
+1.20.6 API, and does not contain `api-version` or a modern library-loader
+declaration. The modern artifact is compiled against Paper 1.21 and declares
+`api-version: 1.21`, allowing it to run on later Paper releases.
+
+The legacy jar includes the normal HeadDB browsing, search, favorites, local
+heads, custom-category, purchase, player-storage, API, localization, sound,
+update-checking, metrics, and database-refresh features. Its menus are implemented
+with Bukkit inventories so they work before Paper's modern menu APIs. Purchase
+amounts use inventory presets, and advanced MiniMessage effects are simplified
+on older clients. Folia is not currently supported because the bundled modern
+menu framework is not region-thread safe.
 
 HeadDB checks GitHub Releases for updates on startup and every 24 hours by
 default. Console notifications and player notifications can be configured under
@@ -246,6 +266,19 @@ you agree to the [Minecraft EULA](https://aka.ms/MinecraftEULA).
 
 ---
 
+## Building both release jars
+
+Run `mvn clean package` from the repository root. The release files are written
+to:
+
+- `headdb-core/target/HeadDB-6.0.3.jar`
+- `headdb-legacy/target/HeadDB-6.0.3-legacy.jar`
+
+The legacy module uses `--release 8`; the modern module uses `--release 21`.
+Maven may run on a newer JDK when building both artifacts together.
+
+---
+
 ## 🤗 Contributing
 
 1. Fork the repository  

changelog/6.0.3.md

@@ -0,0 +1,34 @@
+# HeadDB 6.0.3 Changelog
+
+## Separate modern and legacy artifacts
+
+- `HeadDB-6.0.3.jar` is the Java 21 modern artifact for Paper 1.21.0 and newer.
+- `HeadDB-6.0.3-legacy.jar` is the Java 8-bytecode artifact for Bukkit-compatible
+  servers from 1.8.8 through 1.20.6.
+- Legacy material and player-profile operations are selected at runtime across
+  the pre- and post-flattening server APIs.
+- The previous `-Spigot.jar` classifier has been removed.
+- The public `headdb-api` module now targets Java 8 so integrations can use the
+  same service interfaces with either server artifact.
+
+## Legacy feature coverage
+
+The legacy module includes asynchronous database loading and fallback sources,
+indexed and structured searches, public API service registration, legacy
+textured-skull creation, browsing and purchase menus, favorites, local heads,
+custom categories, persistent player settings, Vault economy integration,
+configurable messages and sounds, update notifications, metrics, scheduled
+database refreshes, and the `info`, `search`, `give`, `open`, and `sounds`
+commands. It uses the same configuration and data schema as the modern jar so
+servers can switch artifacts without rebuilding their HeadDB data.
+
+Legacy menus use Bukkit inventories rather than the modern Paper menu framework.
+Interactive purchase quantities are provided as inventory presets, and advanced
+MiniMessage effects are simplified to formatting supported by older clients.
+
+Runtime smoke tests passed on every historical Paper release published across
+the supported range: 1.8.8, 1.9.4, 1.10.2, 1.11.2, 1.12-1.12.2,
+1.13-1.13.2, 1.14-1.14.4, 1.15-1.15.2, 1.16.1-1.16.5,
+1.17-1.17.1, 1.18-1.18.2, 1.19-1.19.4, and the published Paper releases
+from 1.20 through 1.20.6. Each test reached server-ready state, enabled HeadDB,
+and loaded the complete 86,248-head database without a HeadDB startup error.

headdb-api/pom.xml

@@ -6,19 +6,19 @@
     <parent>
         <groupId>com.bitworksmc</groupId>
         <artifactId>HeadDB</artifactId>
-        <version>6.0.2</version>
+        <version>6.0.3</version>
     </parent>
 
     <artifactId>headdb-api</artifactId>
 
     <properties>
-        <maven.compiler.release>25</maven.compiler.release>
+        <maven.compiler.release>8</maven.compiler.release>
     </properties>
 
     <repositories>
         <repository>
-            <id>papermc</id>
-            <url>https://repo.papermc.io/repository/maven-public/</url>
+            <id>spigotmc-snapshots</id>
+            <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
         </repository>
     </repositories>
 
@@ -43,10 +43,16 @@
             <scope>provided</scope>
         </dependency>
         <dependency>
-            <groupId>io.papermc.paper</groupId>
-            <artifactId>paper-api</artifactId>
-            <version>${paper.version}</version>
+            <groupId>org.spigotmc</groupId>
+            <artifactId>spigot-api</artifactId>
+            <version>${spigot.version}</version>
             <scope>provided</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>net.md-5</groupId>
+                    <artifactId>bungeecord-chat</artifactId>
+                </exclusion>
+            </exclusions>
         </dependency>
     </dependencies>
 

headdb-api/src/main/java/com/github/thesilentpro/headdb/api/HeadAPI.java

@@ -15,7 +15,7 @@
  *
  * @deprecated Use {@link com.bitworksmc.headdb.api.HeadAPI} instead.
  */
-@Deprecated(forRemoval = true, since = "6.0.0")
+@Deprecated
 public interface HeadAPI {
 
     /**

headdb-api/src/main/java/com/github/thesilentpro/headdb/api/HeadDatabase.java

@@ -8,7 +8,7 @@
 /**
  * @deprecated Use {@link com.bitworksmc.headdb.api.HeadDatabase} instead.
  */
-@Deprecated(forRemoval = true, since = "6.0.0")
+@Deprecated
 public interface HeadDatabase {
 
     CompletableFuture<List<Head>> update();

headdb-api/src/main/java/com/github/thesilentpro/headdb/api/model/Head.java

@@ -7,7 +7,7 @@
 /**
  * @deprecated Use {@link com.bitworksmc.headdb.api.model.Head} instead.
  */
-@Deprecated(forRemoval = true, since = "6.0.0")
+@Deprecated
 public interface Head {
 
     int getId();

headdb-core/pom.xml

@@ -6,16 +6,16 @@
     <parent>
         <groupId>com.bitworksmc</groupId>
         <artifactId>HeadDB</artifactId>
-        <version>6.0.2</version>
+        <version>6.0.3</version>
     </parent>
 
     <artifactId>headdb-core</artifactId>
 
     <description>Head Database</description>
-    <version>6.0.2</version>
+    <version>6.0.3</version>
 
     <properties>
-        <maven.compiler.release>25</maven.compiler.release>
+        <maven.compiler.release>21</maven.compiler.release>
     </properties>
 
 
@@ -46,7 +46,7 @@
         <dependency>
             <groupId>com.bitworksmc</groupId>
             <artifactId>headdb-api</artifactId>
-            <version>6.0.2</version>
+            <version>6.0.3</version>
         </dependency>
 
         <!-- Hard Dependencies (Provided) -->
@@ -113,7 +113,7 @@
             <scope>provided</scope>
         </dependency>
 
-        <!-- Adventure API (shaded and relocated only in the Spigot artifact) -->
+        <!-- Adventure API is supplied by Paper in the modern artifact. -->
         <dependency>
             <groupId>net.kyori</groupId>
             <artifactId>adventure-api</artifactId>
@@ -167,14 +167,14 @@
                 <version>3.5.4</version>
             </plugin>
 
-            <!-- Shade Plugin: two executions in one mvn run -->
+            <!-- Build the modern Paper artifact. Legacy Bukkit has its own module. -->
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-shade-plugin</artifactId>
                 <version>3.6.2</version>
                 <executions>
 
-                    <!-- 1) Paper jar (main artifact): shade only other libs -->
+                    <!-- Paper jar (main artifact): shade only other libs -->
                     <execution>
                         <id>shade-paper</id>
                         <phase>package</phase>
@@ -228,57 +228,6 @@
                         </configuration>
                     </execution>
 
-                    <!-- 2) Spigot jar (attached): shade Adventure + other libs -->
-                    <execution>
-                        <id>shade-spigot</id>
-                        <phase>package</phase>
-                        <goals><goal>shade</goal></goals>
-                        <configuration>
-                            <!-- attach as additional artifact -->
-                            <shadedArtifactAttached>true</shadedArtifactAttached>
-                            <shadedClassifierName>spigot</shadedClassifierName>
-                            <finalName>HeadDB-${project.version}-Spigot</finalName>
-
-                            <!-- relocate Adventure -->
-                            <relocations>
-                                <relocation>
-                                    <pattern>net.kyori.adventure</pattern>
-                                    <shadedPattern>com.bitworksmc.libs.adventure</shadedPattern>
-                                </relocation>
-                                <relocation>
-                                    <pattern>com.github.thesilentpro.grim</pattern>
-                                    <shadedPattern>com.bitworksmc.libs.grim</shadedPattern>
-                                </relocation>
-                                <relocation>
-                                    <pattern>com.github.thesilentpro.localization</pattern>
-                                    <shadedPattern>com.bitworksmc.libs.localization</shadedPattern>
-                                </relocation>
-                                <relocation>
-                                    <pattern>com.github.thesilentpro.inputs</pattern>
-                                    <shadedPattern>com.bitworksmc.libs.inputs</shadedPattern>
-                                </relocation>
-                            </relocations>
-
-                            <filters>
-                                <filter>
-                                    <artifact>com.github.thesilentpro.localization:localization-paper</artifact>
-                                    <excludes>
-                                        <!-- Paper-only logger linkage; HeadDB supplies a Bukkit-safe adapter. -->
-                                        <exclude>com/github/thesilentpro/localization/paper/PaperLocalization*.class</exclude>
-                                    </excludes>
-                                </filter>
-                            </filters>
-
-                            <transformers>
-                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
-                                    <mainClass>com.bitworksmc.headdb.core.HeadDB</mainClass>
-                                </transformer>
-                            </transformers>
-
-                            <minimizeJar>true</minimizeJar>
-                        </configuration>
-                    </execution>
-
                 </executions>
             </plugin>
         </plugins>
@@ -339,6 +288,8 @@
                                     <arguments>
                                         <argument>-Xms${dev.server.xms}</argument>
                                         <argument>-Xmx${dev.server.xmx}</argument>
+                                        <!-- JOML 1.10.8 otherwise uses sun.misc.Unsafe, which is deprecated on Java 26. -->
+                                        <argument>-Djoml.nounsafe=true</argument>
                                         <argument>-jar</argument>
                                         <argument>paper.jar</argument>
                                         <argument>--nogui</argument>

headdb-core/src/main/resources/plugin.yml

@@ -8,7 +8,7 @@ softdepend: [
   #"PlaceholderAPI",
   "Vault"
 ]
-api-version: '26.2'
+api-version: '1.21'
 libraries:
   - "org.xerial:sqlite-jdbc:${sqlite.version}"