feat: introduce new versioning & Minecraft compatibility system

.github/workflows/release.yml

@@ -31,23 +31,3 @@ jobs:
         if: success() || failure() # Continue on failure
         with:
           report_paths: '**/build/test-results/test/TEST-*.xml'
-      - name: 'Publish to William278.net 🚀'
-        uses: WiIIiam278/bones-publish-action@v1
-        with:
-          api-key: ${{ secrets.BONES_API_KEY }}
-          project: 'husksync'
-          channel: 'release'
-          version: ${{ github.event.release.tag_name }}
-          changelog: ${{ github.event.release.body }}
-          distro-names: |
-            paper
-            fabric-1.20.1
-          distro-groups: |
-            paper
-            fabric
-          distro-descriptions: |
-            Paper
-            Fabric 1.20.1
-          files: |
-            target/HuskSync-Paper-${{ github.event.release.tag_name }}.jar
-            target/HuskSync-Fabric-${{ github.event.release.tag_name }}+mc.1.20.1.jar

README.md

@@ -43,8 +43,27 @@
 
 **Ready?** [It's syncing time!](https://william278.net/docs/husksync/setup)
 
+## Compatibility
+HuskSync supports the following [compatible versions](https://william278.net/docs/husksync/compatibility) of Minecraft. Since v3.7, you must download the correct version of HuskSync for your server:
+
+|    Minecraft     | Latest HuskSync | Java Version | Platforms     | Support Ends              |
+|:----------------:|:---------------:|:------------:|:--------------|:--------------------------|
+|      1.21.1      |    _latest_     |      21      | Paper, Fabric | ✅ **Active Release**      |
+|      1.20.6      |      3.6.8      |      17      | Paper         | ✅ **November 2024**       |
+|      1.20.4      |      3.6.8      |      17      | Paper         | ❌ _July 2024_             |
+|      1.20.1      |    _latest_     |      17      | Paper, Fabric | ✅ **November 2025** (LTS) |
+| 1.17.1 - 1.19.4  |      3.6.8      |      17      | Paper         | ❌ _Support ended_         |
+|      1.16.5      |      3.2.1      |      16      | Paper         | ❌ _Support ended_         |
+
+HuskSync is primarily developed against the latest release. Old Minecraft versions are allocated support channels based on popularity, mod support, etc:
+
+* Long Term Support (LTS) – Supported for up to 12-18 months
+* Standard Release Support (SRS) – Supported for 3-6 months
+
+Verify your purchase on Discord and [Download HuskSync](https://william278.net/project/husksync#download) for your server.
+
 ## Setup
-Requires a MySQL/Mongo/PostgreSQL database, a Redis (v5.0+) server and a network of Spigot (1.17.1+) or Fabric (1.20.1) Minecraft servers, running Java 17+.
+Requires a MySQL/Mongo/PostgreSQL database, a Redis (v5.0+) server and a network of Spigot or Fabric Minecraft servers, running Java 17+.
 
 1. Place the plugin jar file in the `/plugins` or `/mods` directory of each Spigot/Fabric server. You do not need to install HuskSync as a proxy plugin.
 2. Start, then stop every server to let HuskSync generate the config file.

build.gradle

@@ -18,6 +18,7 @@ ext {
     set 'version', version.toString()
     set 'description', description.toString()
 
+    set 'minecraft_version', minecraft_version.toString()
     set 'jedis_version', jedis_version.toString()
     set 'mysql_driver_version', mysql_driver_version.toString()
     set 'mariadb_driver_version', mariadb_driver_version.toString()
@@ -63,7 +64,7 @@ allprojects {
     apply plugin: 'java'
 
     compileJava.options.encoding = 'UTF-8'
-    compileJava.options.release.set 17
+    compileJava.options.release.set Integer.parseInt(rootProject.ext.javaVersion)
     javadoc.options.encoding = 'UTF-8'
     javadoc.options.addStringOption('Xdoclint:none', '-quiet')
 
@@ -125,9 +126,9 @@ subprojects {
         archiveClassifier.set('')
     }
 
-    // Append the Minecraft to the version for Fabric projects
+    // Append the compatible Minecraft version to the version
-    if (project.name == 'fabric') {
+    if (['bukkit', 'paper', 'fabric'].contains(project.name)) {
-        version += "+mc.${fabric_minecraft_version}"
+        version += "+mc.${minecraft_version}"
     }
 
     // API publishing
@@ -163,7 +164,7 @@ subprojects {
                     mavenJavaBukkit(MavenPublication) {
                         groupId = 'net.william278.husksync'
                         artifactId = 'husksync-bukkit'
-                        version = "$rootProject.version"
+                        version = "$rootProject.version+${minecraft_version}"
                         artifact shadowJar
                         artifact sourcesJar
                         artifact javadocJar
@@ -176,7 +177,7 @@ subprojects {
                     mavenJavaFabric(MavenPublication) {
                         groupId = 'net.william278.husksync'
                         artifactId = 'husksync-fabric'
-                        version = "$rootProject.version+${fabric_minecraft_version}"
+                        version = "$rootProject.version+${minecraft_version}"
                         artifact remapJar
                         artifact sourcesJar
                         artifact javadocJar
@@ -190,7 +191,7 @@ subprojects {
     clean.delete "$rootDir/target"
 }
 
-logger.lifecycle("Building HuskSync ${version} by William278")
+logger.lifecycle("Building HuskSync ${version} by William278 for Minecraft ${minecraft_version}")
 
 @SuppressWarnings('GrMethodMayBeStatic')
 def versionMetadata() {

bukkit/build.gradle

@@ -11,7 +11,7 @@ dependencies {
     implementation 'space.arim.morepaperlib:morepaperlib:0.4.4'
     implementation 'de.tr7zw:item-nbt-api:2.13.2'
 
-    compileOnly 'org.spigotmc:spigot-api:1.17.1-R0.1-SNAPSHOT'
+    compileOnly "org.spigotmc:spigot-api:${bukkit_spigot_api}"
     compileOnly 'com.github.retrooper.packetevents:spigot:2.3.0'
     compileOnly 'com.comphenix.protocol:ProtocolLib:5.1.0'
     compileOnly 'org.projectlombok:lombok:1.18.34'

bukkit/src/main/java/net/william278/husksync/BukkitHuskSync.java

@@ -137,6 +137,9 @@ public class BukkitHuskSync extends JavaPlugin implements HuskSync, BukkitTask.S
     public void onEnable() {
         this.audiences = BukkitAudiences.create(this);
 
+        // Check compatibility
+        checkCompatibility();
+
         // Register commands
         initialize("commands", (plugin) -> getUniform().register(PluginCommand.Type.create(this)));
 

bukkit/src/main/java/net/william278/husksync/data/BukkitData.java

@@ -157,21 +157,18 @@ public abstract class BukkitData implements Data {
                 this.clearInventoryCraftingSlots(player);
                 player.setItemOnCursor(null);
                 player.getInventory().setContents(plugin.setMapViews(getContents()));
-                player.updateInventory();
                 player.getInventory().setHeldItemSlot(heldItemSlot);
+                //noinspection UnstableApiUsage
+                player.updateInventory();
             }
 
             private void clearInventoryCraftingSlots(@NotNull Player player) {
-                try {
                 final org.bukkit.inventory.Inventory inventory = player.getOpenInventory().getTopInventory();
                 if (inventory.getType() == InventoryType.CRAFTING) {
                     for (int slot = 0; slot < 5; slot++) {
                         inventory.setItem(slot, null);
                     }
                 }
-                } catch (Throwable e) {
-                    // Ignore any exceptions
-                }
             }
 
         }

bukkit/src/main/java/net/william278/husksync/util/BukkitMapPersister.java

@@ -308,7 +308,7 @@ public interface BukkitMapPersister {
             // We set the pixels in this order to avoid the map being rendered upside down
             for (int i = 0; i < 128; i++) {
                 for (int j = 0; j < 128; j++) {
-                    canvas.setPixel(j, i, (byte) canvasData.getColorAt(i, j));
+                    canvas.setPixelColor(j, i, canvasData.getMapColorAt(i, j));
                 }
             }
 
@@ -383,20 +383,40 @@ public interface BukkitMapPersister {
         }
 
         @Override
+        @Deprecated
         public void setPixel(int x, int y, byte color) {
             pixels[x][y] = color;
         }
 
         @Override
+        @Deprecated
         public byte getPixel(int x, int y) {
             return (byte) pixels[x][y];
         }
 
         @Override
+        @Deprecated
         public byte getBasePixel(int x, int y) {
             return getPixel(x, y);
         }
 
+        @Override
+        public void setPixelColor(int i, int i1, @Nullable Color color) {
+            pixels[i][i1] = color == null ? 0 : color.getRGB();
+        }
+
+        @Nullable
+        @Override
+        public Color getPixelColor(int x, int y) {
+            return getBasePixelColor(x, y);
+        }
+
+        @NotNull
+        @Override
+        public Color getBasePixelColor(int x, int y) {
+            return new Color(pixels[x][y]);
+        }
+
         @Override
         public void drawImage(int x, int y, @NotNull Image image) {
             // Not implemented
@@ -424,7 +444,6 @@ public interface BukkitMapPersister {
         @NotNull
         private MapData extractMapData() {
             final List<MapBanner> banners = Lists.newArrayList();
-            try {
             final String BANNER_PREFIX = "banner_";
             for (int i = 0; i < getCursors().size(); i++) {
                 final MapCursor cursor = getCursors().getCursor(i);
@@ -440,8 +459,6 @@ public interface BukkitMapPersister {
                 }
 
             }
-            } catch (Throwable ignored) {
-            }
             return MapData.fromPixels(pixels, getDimension(), (byte) 2, banners, List.of());
         }
     }

common/src/main/java/net/william278/husksync/HuskSync.java

@@ -39,6 +39,7 @@ import net.william278.husksync.redis.RedisManager;
 import net.william278.husksync.sync.DataSyncer;
 import net.william278.husksync.user.ConsoleUser;
 import net.william278.husksync.user.OnlineUser;
+import net.william278.husksync.util.CompatibilityChecker;
 import net.william278.husksync.util.LegacyConverter;
 import net.william278.husksync.util.Task;
 import net.william278.uniform.Uniform;
@@ -52,7 +53,8 @@ import java.util.logging.Level;
 /**
  * Abstract implementation of the HuskSync plugin.
  */
-public interface HuskSync extends Task.Supplier, EventDispatcher, ConfigProvider, SerializerRegistry {
+public interface HuskSync extends Task.Supplier, EventDispatcher, ConfigProvider, SerializerRegistry,
+        CompatibilityChecker {
 
     int SPIGOT_RESOURCE_ID = 97144;
 
@@ -338,7 +340,11 @@ public interface HuskSync extends Task.Supplier, EventDispatcher, ConfigProvider
                 
                 Caused by: %s""";
 
-        FailedToLoadException(@NotNull String message, @NotNull Throwable cause) {
+        public FailedToLoadException(@NotNull String message) {
+            super(String.format(FORMAT, message));
+        }
+
+        public FailedToLoadException(@NotNull String message, @NotNull Throwable cause) {
             super(String.format(FORMAT, message), cause);
         }
 

common/src/main/java/net/william278/husksync/util/CompatibilityChecker.java

@@ -0,0 +1,76 @@
+/*
+ * This file is part of HuskSync, licensed under the Apache License 2.0.
+ *
+ *  Copyright (c) William278 <will27528@gmail.com>
+ *  Copyright (c) contributors
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package net.william278.husksync.util;
+
+import de.exlll.configlib.Configuration;
+import de.exlll.configlib.YamlConfigurationProperties;
+import de.exlll.configlib.YamlConfigurationStore;
+import net.william278.desertwell.util.Version;
+import net.william278.husksync.HuskSync;
+import org.jetbrains.annotations.NotNull;
+
+import java.io.InputStream;
+import java.util.Objects;
+import java.util.logging.Level;
+
+import static net.william278.husksync.config.ConfigProvider.YAML_CONFIGURATION_PROPERTIES;
+
+public interface CompatibilityChecker {
+
+    String COMPATIBILITY_FILE = "compatibility.yml";
+
+    default void checkCompatibility() throws HuskSync.FailedToLoadException {
+        final YamlConfigurationProperties p = YAML_CONFIGURATION_PROPERTIES.build();
+        final Version compatible;
+
+        // Load compatibility file
+        try (InputStream input = getResource(COMPATIBILITY_FILE)) {
+            final CompatibilityConfig compat = new YamlConfigurationStore<>(CompatibilityConfig.class, p).read(input);
+            compatible = Objects.requireNonNull(compat.getCompatibleWith());
+        } catch (Throwable e) {
+            getPlugin().log(Level.WARNING, "Failed to load compatibility config, skipping check.", e);
+            return;
+        }
+
+        // Check compatibility
+        if (!compatible.equals(getPlugin().getMinecraftVersion())) {
+            throw new HuskSync.FailedToLoadException("""
+                    Incompatible Minecraft version. This version of HuskSync is designed for Minecraft %s.
+                    Please download the correct version of HuskSync for your server's Minecraft version (%s)."""
+                    .formatted(compatible.toString(), getPlugin().getMinecraftVersion().toString()));
+        }
+    }
+
+    InputStream getResource(@NotNull String name);
+
+    @NotNull
+    HuskSync getPlugin();
+
+    @Configuration
+    record CompatibilityConfig(@NotNull String compatibleMinecraftVersion) {
+
+        @NotNull
+        public Version getCompatibleWith() {
+            return Version.fromString(compatibleMinecraftVersion);
+        }
+
+    }
+
+}

common/src/main/resources/compatibility.yml

@@ -0,0 +1,2 @@
+# File used for checking Minecraft server compatibility with this version of HuskSync
+minecraft_version: '${minecraft_version}'

docs/API.md

@@ -53,12 +53,12 @@ Add the repository to your `pom.xml` as per below. You can alternatively specify
     </repository>
 </repositories>
 ```
-Add the dependency to your `pom.xml` as per below. Replace `VERSION` with the latest version of HuskSync (without the v): ![Latest version](https://img.shields.io/github/v/tag/WiIIiam278/HuskSync?color=%23282828&label=%20&style=flat-square). Note for Fabric you must append the target Minecraft version to the version number (e.g. `3.6.1+1.20.1`).
+Add the dependency to your `pom.xml` as per below. Replace `HUSKSYNC_VERSION` with the latest version of HuskSync (without the v): ![Latest version](https://img.shields.io/github/v/tag/WiIIiam278/HuskSync?color=%23282828&label=%20&style=flat-square). and `MINECRAFT_VERSION` with the version of Minecraft you want to target (e.g. `1.20.1`). A correctly formed version target should look like: `3.7+1.20.1`. Omit the plus symbol and Minecraft version if you are targeting the `common` platform.
 ```xml
 <dependency>
     <groupId>net.william278.husksync</groupId>
     <artifactId>husksync-PLATFORM</artifactId>
-    <version>VERSION</version>
+    <version>HUSKSYNC_VERSION+MINECRAFT_VERSION</version>
     <scope>provided</scope>
 </dependency>
 ```
@@ -76,11 +76,11 @@ allprojects {
 	}
 }
 ```
-Add the dependency as per below. Replace `VERSION` with the latest version of HuskSync (without the v): ![Latest version](https://img.shields.io/github/v/tag/WiIIiam278/HuskSync?color=%23282828&label=%20&style=flat-square). Note for Fabric you must append the target Minecraft version to the version number (e.g. `3.6.1+1.20.1`).
+Add the dependency as per below. Replace `HUSKSYNC_VERSION` with the latest version of HuskSync (without the v): ![Latest version](https://img.shields.io/github/v/tag/WiIIiam278/HuskSync?color=%23282828&label=%20&style=flat-square). and `MINECRAFT_VERSION` with the version of Minecraft you want to target (e.g. `1.20.1`). A correctly formed version target should look like: `3.7+1.20.1`. Omit the plus symbol and Minecraft version if you are targeting the `common` platform.
 
 ```groovy
 dependencies {
-    compileOnly 'net.william278.husksync:husksync-PLATFORM:VERSION'
+    compileOnly 'net.william278.husksync:husksync-PLATFORM:HUSKSYNC_VERSION+MINECRAFT_VERSION'
 }
 ```
 </details>

docs/Compatibility.md

@@ -0,0 +1,22 @@
+HuskSync supports the following versions of Minecraft. Since v3.7, you must download the correct version of HuskSync for your server:
+
+|    Minecraft     | Latest HuskSync | Java Version | Platforms     | Support Ends              |
+|:----------------:|:---------------:|:------------:|:--------------|:--------------------------|
+|      1.21.1      |    _latest_     |      21      | Paper, Fabric | ✅ **Active Release**      |
+|      1.20.6      |      3.6.8      |      17      | Paper         | ✅ **November 2024**       |
+|      1.20.4      |      3.6.8      |      17      | Paper         | ❌ _July 2024_             |
+|      1.20.1      |    _latest_     |      17      | Paper, Fabric | ✅ **November 2025** (LTS) |
+| 1.17.1 - 1.19.4  |      3.6.8      |      17      | Paper         | ❌ _Support ended_         |
+|      1.16.5      |      3.2.1      |      16      | Paper         | ❌ _Support ended_         |
+
+## Incompatible 
+This plugin does not support the following software-Minecraft version combinations. The plugin will fail to load if you attempt to run it with these versions. Apologies for the inconvenience.
+
+| Minecraft         | Server Software                           | Notes                                  |
+|-------------------|-------------------------------------------|----------------------------------------|
+| 1.19.4            | Only: `Purpur, Pufferfish`†        | Older Paper builds also not supported. |
+| 1.19.3            | Only: `Paper, Purpur, Pufferfish`† | Upgrade to 1.19.4 or use Spigot        |
+| 1.16.5            | _All_                                     | Please use v3.3.1 or lower             |
+| below 1.16.5      | _All_                                     | Upgrade to Minecraft 1.16.5            |
+
+†Further downstream forks of this server software are also affected.

docs/Setup.md

@@ -1,17 +1,18 @@
-> **Warning:** Fabric support is currently in beta and is not production ready yet. Customers can get in touch on Discord to request the Fabric build, or you can self-compile.
+> **Warning:** Fabric support is currently in beta and is not production ready yet.
+
+This will walk you through installing HuskSync on your network of Spigot or Fabric servers. Please check your server's [[Compatibility]] and download the correct version of HuskSync for your server.
 
-This will walk you through installing HuskSync on your network of Spigot or Fabric servers.
 
 ## Requirements
 > **Warning:** Mixing and matching Fabric/Spigot servers is not supported, and all servers must be running the same Minecraft version.
 
-> **Note:** Please also note some specific legacy Paper/Purpur versions are [not compatible](Unsupported-Versions) with HuskSync.
+> **Note:** Please also note some specific legacy Paper/Purpur versions are [not compatible](Compatibility) with HuskSync.
 
 * A MySQL Database (v8.0+)
   * **OR** a MariaDB, PostrgreSQL or MongoDB database, which are also supported
 * A Redis Database (v5.0+) — see [[FAQs]] for more details.
-* Any number of Spigot servers, connected by a BungeeCord or Velocity-based proxy (Minecraft v1.17.1+, running Java 17+)
+* Any number of Spigot servers, connected by a BungeeCord or Velocity-based proxy (see [[Compatibility]])
-  * **OR** a network of Fabric servers, connected by a Fabric proxy (Minecraft v1.20.1, running Java 17+)
+  * **OR** a network of Fabric servers, connected by a Velocity-based proxy
 
 ## Setup Instructions
 ### 1. Install the jar

docs/Unsupported-Versions.md

@@ -1,11 +0,0 @@
-This plugin does not support the following software-Minecraft version combinations. The plugin will fail to load if you attempt to run it with these versions. Apologies for the inconvenience.
-
-## Incompatibility table
-| Minecraft Versions | Server Software                           | Notes                                  |
-|--------------------|-------------------------------------------|----------------------------------------|
-| 1.19.4             | Only: `Purpur, Pufferfish`†        | Older Paper builds also not supported. |
-| 1.19.3             | Only: `Paper, Purpur, Pufferfish`† | Upgrade to 1.19.4 or use Spigot        |
-| 1.16.5             | _All_                                     | Please use v3.3.1 or lower             |
-| below 1.16.5       | _All_                                     | Upgrade Minecraft 1.16.5               |
-
-†Further downstream forks of this server software are also affected.

fabric/build.gradle

@@ -11,13 +11,13 @@ repositories {
 }
 
 dependencies {
-    minecraft "com.mojang:minecraft:${fabric_minecraft_version}"
+    minecraft "com.mojang:minecraft:${minecraft_version}"
     mappings "net.fabricmc:yarn:${fabric_yarn_mappings}:v2"
     modImplementation "net.fabricmc:fabric-loader:${fabric_loader_version}"
 
-    modImplementation include("net.kyori:adventure-platform-fabric:${adventure_platform_fabric_version}")
+    modImplementation include("net.kyori:adventure-platform-fabric:${fabric_adventure_platform_version}")
     modImplementation include("me.lucko:fabric-permissions-api:${fabric_permissions_api_version}")
-    modImplementation include("eu.pb4:sgui:${sgui_version}")
+    modImplementation include("eu.pb4:sgui:${fabric_sgui_version}")
     modImplementation include('net.william278.uniform:uniform-fabric:1.2.1+1.20.1')
     modCompileOnly "net.fabricmc.fabric-api:fabric-api:${fabric_api_version}"
 

fabric/src/main/java/net/william278/husksync/FabricHuskSync.java

@@ -120,6 +120,9 @@ public class FabricHuskSync implements DedicatedServerModInitializer, HuskSync,
         this.disabling = false;
         this.gson = createGson();
 
+        // Check compatibility
+        checkCompatibility();
+
         // Load settings and locales
         initialize("plugin config & locale files", (plugin) -> {
             loadSettings();

fabric/src/main/resources/fabric.mod.json

@@ -40,7 +40,7 @@
   },
   "depends": {
     "fabricloader": ">=${fabric_loader_version}",
-    "minecraft": ">=${fabric_minecraft_version}",
+    "minecraft": ">=${minecraft_version}",
     "fabric-api": "*"
   },
   "suggests": {

gradle.properties

@@ -1,12 +1,15 @@
+# Gradle settings
 org.gradle.jvmargs='-Dfile.encoding=UTF-8'
-
 org.gradle.daemon=true
 javaVersion=17
 
-plugin_version=3.6.8
+# Plugin settings
+plugin_version=3.7
+minecraft_version=1.20.1
 plugin_archive=husksync
 plugin_description=A modern, cross-server player data synchronization system
 
+# Drivers
 jedis_version=5.1.4
 mysql_driver_version=9.0.0
 mariadb_driver_version=3.4.1
@@ -14,10 +17,14 @@ postgres_driver_version=42.7.3
 mongodb_driver_version=5.1.2
 snappy_version=1.1.10.6
 
-fabric_minecraft_version=1.20.1
+# Spigot/Paper build settings
+bukkit_spigot_api=1.20.1-R0.1-SNAPSHOT
+bukkit_paper_api=1.20.1-R0.1-SNAPSHOT
+
+# Fabric build settings
 fabric_loader_version=0.15.11
 fabric_yarn_mappings=1.20.1+build.10
 fabric_api_version=0.92.2+1.20.1
-adventure_platform_fabric_version=5.9.0
+fabric_adventure_platform_version=5.9.0
 fabric_permissions_api_version=0.2-SNAPSHOT
-sgui_version=1.2.2+1.20
+fabric_sgui_version=1.2.2+1.20

paper/build.gradle

@@ -8,7 +8,7 @@ dependencies {
 
     implementation 'net.william278.uniform:uniform-paper:1.2.1'
 
-    compileOnly 'io.papermc.paper:paper-api:1.19.4-R0.1-SNAPSHOT'
+    compileOnly "io.papermc.paper:paper-api:${bukkit_paper_api}"
     compileOnly 'org.jetbrains:annotations:24.1.0'
     compileOnly 'org.projectlombok:lombok:1.18.34'