fix: death save updating player

Bumps [org.json:json](https://github.com/douglascrockford/JSON-java) from 20231013 to 20240205.
- [Release notes](https://github.com/douglascrockford/JSON-java/releases)
- [Changelog](https://github.com/stleary/JSON-java/blob/master/docs/RELEASES.md)
- [Commits](https://github.com/douglascrockford/JSON-java/commits)

---
updated-dependencies:
- dependency-name: org.json:json
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
           java-version: '17'
           distribution: 'temurin'
       - name: 'Build with Gradle 🏗️'
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/gradle-build-action@v3
         with:
           arguments: build test publish
         env:

.github/workflows/pr_tests.yml

@@ -20,7 +20,7 @@ jobs:
           java-version: '17'
           distribution: 'temurin'
       - name: 'Build with Gradle 🏗️'
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/gradle-build-action@v3
         with:
           arguments: test
       - name: 'Publish Test Report 📊'

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
           java-version: '17'
           distribution: 'temurin'
       - name: 'Build with Gradle 🏗️'
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/gradle-build-action@v3
         with:
           arguments: build test publish
         env:

build.gradle

@@ -78,9 +78,9 @@ allprojects {
     }
 
     dependencies {
-        testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.1'
-        testImplementation 'org.junit.jupiter:junit-jupiter-params:5.10.1'
-        testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.10.1'
+        testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.2'
+        testImplementation 'org.junit.jupiter:junit-jupiter-params:5.10.2'
+        testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.10.2'
     }
 
     test {

bukkit/build.gradle

@@ -15,7 +15,7 @@ dependencies {
     compileOnly 'org.spigotmc:spigot-api:1.17.1-R0.1-SNAPSHOT'
     compileOnly 'org.projectlombok:lombok:1.18.30'
     compileOnly 'commons-io:commons-io:2.15.1'
-    compileOnly 'org.json:json:20231013'
+    compileOnly 'org.json:json:20240205'
     compileOnly 'de.themoep:minedown-adventure:1.7.2-SNAPSHOT'
     compileOnly 'com.github.Exlll.ConfigLib:configlib-yaml:v4.4.0'
     compileOnly 'com.zaxxer:HikariCP:5.1.0'

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

@@ -60,7 +60,6 @@ import net.william278.husksync.util.BukkitMapPersister;
 import net.william278.husksync.util.BukkitTask;
 import net.william278.husksync.util.LegacyConverter;
 import org.bstats.bukkit.Metrics;
-import org.bukkit.Bukkit;
 import org.bukkit.entity.Player;
 import org.bukkit.map.MapView;
 import org.bukkit.plugin.java.JavaPlugin;
@@ -229,7 +228,7 @@ public class BukkitHuskSync extends JavaPlugin implements HuskSync, BukkitTask.S
     @Override
     @NotNull
     public Set<OnlineUser> getOnlineUsers() {
-        return Bukkit.getOnlinePlayers().stream()
+        return getServer().getOnlinePlayers().stream()
                 .map(player -> BukkitUser.adapt(player, this))
                 .collect(Collectors.toSet());
     }
@@ -237,7 +236,7 @@ public class BukkitHuskSync extends JavaPlugin implements HuskSync, BukkitTask.S
     @Override
     @NotNull
     public Optional<OnlineUser> getOnlineUser(@NotNull UUID uuid) {
-        final Player player = Bukkit.getPlayer(uuid);
+        final Player player = getServer().getPlayer(uuid);
         if (player == null) {
             return Optional.empty();
         }
@@ -253,12 +252,10 @@ public class BukkitHuskSync extends JavaPlugin implements HuskSync, BukkitTask.S
     @NotNull
     @Override
     public Map<Identifier, Data> getPlayerCustomDataStore(@NotNull OnlineUser user) {
-        if (playerCustomDataStore.containsKey(user.getUuid())) {
-            return playerCustomDataStore.get(user.getUuid());
-        }
-        final Map<Identifier, Data> data = Maps.newHashMap();
-        playerCustomDataStore.put(user.getUuid(), data);
-        return data;
+        return playerCustomDataStore.compute(
+                user.getUuid(),
+                (uuid, data) -> data == null ? Maps.newHashMap() : data
+        );
     }
 
     @Override
@@ -269,7 +266,7 @@ public class BukkitHuskSync extends JavaPlugin implements HuskSync, BukkitTask.S
 
     @Override
     public boolean isDependencyLoaded(@NotNull String name) {
-        return Bukkit.getPluginManager().getPlugin(name) != null;
+        return getServer().getPluginManager().getPlugin(name) != null;
     }
 
     // Register bStats metrics
@@ -303,7 +300,7 @@ public class BukkitHuskSync extends JavaPlugin implements HuskSync, BukkitTask.S
     @NotNull
     @Override
     public Version getMinecraftVersion() {
-        return Version.fromString(Bukkit.getBukkitVersion());
+        return Version.fromString(getServer().getBukkitVersion());
     }
 
     @NotNull
@@ -347,7 +344,7 @@ public class BukkitHuskSync extends JavaPlugin implements HuskSync, BukkitTask.S
 
     @Override
     @NotNull
-    public HuskSync getPlugin() {
+    public BukkitHuskSync getPlugin() {
         return this;
     }
 

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

@@ -25,7 +25,6 @@ import org.bukkit.entity.Player;
 import org.bukkit.inventory.PlayerInventory;
 import org.jetbrains.annotations.NotNull;
 
-import java.util.Map;
 import java.util.Optional;
 
 public interface BukkitUserDataHolder extends UserDataHolder {
@@ -140,9 +139,6 @@ public interface BukkitUserDataHolder extends UserDataHolder {
     @NotNull
     Player getBukkitPlayer();
 
-    @NotNull
-    Map<Identifier, Data> getCustomDataStore();
-
     @NotNull
     default BukkitMapPersister getMapPersister() {
         return (BukkitHuskSync) getPlugin();

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

@@ -25,7 +25,7 @@ import de.tr7zw.changeme.nbtapi.iface.ReadWriteNBT;
 import de.tr7zw.changeme.nbtapi.iface.ReadableNBT;
 import net.querz.nbt.io.NBTUtil;
 import net.querz.nbt.tag.CompoundTag;
-import net.william278.husksync.HuskSync;
+import net.william278.husksync.BukkitHuskSync;
 import net.william278.mapdataapi.MapBanner;
 import net.william278.mapdataapi.MapData;
 import org.bukkit.Bukkit;
@@ -85,7 +85,7 @@ public interface BukkitMapPersister {
 
     // Perform an operation on each map in an array of ItemStacks
     @NotNull
-    private ItemStack[] forEachMap(@NotNull ItemStack[] items, @NotNull Function<ItemStack, ItemStack> function) {
+    private ItemStack[] forEachMap(ItemStack[] items, @NotNull Function<ItemStack, ItemStack> function) {
         for (int i = 0; i < items.length; i++) {
             final ItemStack item = items[i];
             if (item == null) {
@@ -148,7 +148,7 @@ public interface BukkitMapPersister {
             // Search for an existing map view
             Optional<String> world = Optional.empty();
             for (String worldUid : mapIds.getKeys()) {
-                world = Bukkit.getWorlds().stream()
+                world = getPlugin().getServer().getWorlds().stream()
                         .map(w -> w.getUID().toString()).filter(u -> u.equals(worldUid))
                         .findFirst();
                 if (world.isPresent()) {
@@ -441,6 +441,6 @@ public interface BukkitMapPersister {
 
     @ApiStatus.Internal
     @NotNull
-    HuskSync getPlugin();
+    BukkitHuskSync getPlugin();
 
 }

common/build.gradle

@@ -6,7 +6,7 @@ dependencies {
     api 'commons-io:commons-io:2.15.1'
     api 'org.apache.commons:commons-text:1.11.0'
     api 'de.themoep:minedown-adventure:1.7.2-SNAPSHOT'
-    api 'org.json:json:20231013'
+    api 'org.json:json:20240205'
     api 'com.google.code.gson:gson:2.10.1'
     api 'com.fatboyindustrial.gson-javatime-serialisers:gson-javatime-serialisers:1.1.2'
     api 'com.github.Exlll.ConfigLib:configlib-yaml:v4.4.0'

common/src/main/java/net/william278/husksync/api/HuskSyncAPI.java

@@ -31,11 +31,13 @@ import net.william278.husksync.user.OnlineUser;
 import net.william278.husksync.user.User;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
+import java.util.function.BiConsumer;
 
 /**
  * The common implementation of the HuskSync API, containing cross-platform API calls.
@@ -262,13 +264,32 @@ public class HuskSyncAPI {
      *
      * @param user     The user to save the data for
      * @param snapshot The snapshot to save
+     * @param callback A callback to run after the data has been saved (if the DataSaveEvent was not cancelled)
+     * @apiNote This will fire the {@link net.william278.husksync.event.DataSaveEvent} event, unless
+     * the save cause is {@link DataSnapshot.SaveCause#SERVER_SHUTDOWN}
+     * @since 3.3.2
+     */
+    public void addSnapshot(@NotNull User user, @NotNull DataSnapshot snapshot,
+                            @Nullable BiConsumer<User, DataSnapshot.Packed> callback) {
+        plugin.runAsync(() -> plugin.getDataSyncer().saveData(
+                user,
+                snapshot instanceof DataSnapshot.Unpacked unpacked
+                        ? unpacked.pack(plugin) : (DataSnapshot.Packed) snapshot,
+                callback
+        ));
+    }
+
+    /**
+     * Adds a data snapshot to the database
+     *
+     * @param user     The user to save the data for
+     * @param snapshot The snapshot to save
+     * @apiNote This will fire the {@link net.william278.husksync.event.DataSaveEvent} event, unless
+     * * the save cause is {@link DataSnapshot.SaveCause#SERVER_SHUTDOWN}
      * @since 3.0
      */
     public void addSnapshot(@NotNull User user, @NotNull DataSnapshot snapshot) {
-        plugin.runAsync(() -> plugin.getDatabase().addSnapshot(
-                user, snapshot instanceof DataSnapshot.Unpacked unpacked
-                        ? unpacked.pack(plugin) : (DataSnapshot.Packed) snapshot
-        ));
+        this.addSnapshot(user, snapshot, null);
     }
 
     /**

common/src/main/java/net/william278/husksync/command/EnderChestCommand.java

@@ -23,6 +23,8 @@ import de.themoep.minedown.adventure.MineDown;
 import net.william278.husksync.HuskSync;
 import net.william278.husksync.data.Data;
 import net.william278.husksync.data.DataSnapshot;
+import net.william278.husksync.redis.RedisKeyType;
+import net.william278.husksync.redis.RedisManager;
 import net.william278.husksync.user.OnlineUser;
 import net.william278.husksync.user.User;
 import org.jetbrains.annotations.NotNull;
@@ -70,8 +72,8 @@ public class EnderChestCommand extends ItemsCommand {
 
     // Creates a new snapshot with the updated enderChest
     @SuppressWarnings("DuplicatedCode")
-    private void updateItems(@NotNull OnlineUser viewer, @NotNull Data.Items.Items items, @NotNull User user) {
-        final Optional<DataSnapshot.Packed> latestData = plugin.getDatabase().getLatestSnapshot(user);
+    private void updateItems(@NotNull OnlineUser viewer, @NotNull Data.Items.Items items, @NotNull User holder) {
+        final Optional<DataSnapshot.Packed> latestData = plugin.getDatabase().getLatestSnapshot(holder);
         if (latestData.isEmpty()) {
             plugin.getLocales().getLocale("error_no_data_to_display")
                     .ifPresent(viewer::sendMessage);
@@ -87,8 +89,13 @@ public class EnderChestCommand extends ItemsCommand {
                     plugin.getSettings().getSynchronization().doAutoPin(DataSnapshot.SaveCause.ENDERCHEST_COMMAND)
             );
         });
-        plugin.getDatabase().addSnapshot(user, snapshot);
-        plugin.getRedisManager().sendUserDataUpdate(user, snapshot);
+
+        // Save data
+        final RedisManager redis = plugin.getRedisManager();
+        plugin.getDataSyncer().saveData(holder, snapshot, (user, data) -> {
+            redis.getUserData(user).ifPresent(d -> redis.setUserData(user, snapshot, RedisKeyType.TTL_1_YEAR));
+            redis.sendUserDataUpdate(user, data);
+        });
     }
 
 }

common/src/main/java/net/william278/husksync/command/InventoryCommand.java

@@ -23,6 +23,8 @@ import de.themoep.minedown.adventure.MineDown;
 import net.william278.husksync.HuskSync;
 import net.william278.husksync.data.Data;
 import net.william278.husksync.data.DataSnapshot;
+import net.william278.husksync.redis.RedisKeyType;
+import net.william278.husksync.redis.RedisManager;
 import net.william278.husksync.user.OnlineUser;
 import net.william278.husksync.user.User;
 import org.jetbrains.annotations.NotNull;
@@ -70,8 +72,8 @@ public class InventoryCommand extends ItemsCommand {
 
     // Creates a new snapshot with the updated inventory
     @SuppressWarnings("DuplicatedCode")
-    private void updateItems(@NotNull OnlineUser viewer, @NotNull Data.Items.Items items, @NotNull User user) {
-        final Optional<DataSnapshot.Packed> latestData = plugin.getDatabase().getLatestSnapshot(user);
+    private void updateItems(@NotNull OnlineUser viewer, @NotNull Data.Items.Items items, @NotNull User holder) {
+        final Optional<DataSnapshot.Packed> latestData = plugin.getDatabase().getLatestSnapshot(holder);
         if (latestData.isEmpty()) {
             plugin.getLocales().getLocale("error_no_data_to_display")
                     .ifPresent(viewer::sendMessage);
@@ -87,8 +89,13 @@ public class InventoryCommand extends ItemsCommand {
                     plugin.getSettings().getSynchronization().doAutoPin(DataSnapshot.SaveCause.INVENTORY_COMMAND)
             );
         });
-        plugin.getDatabase().addSnapshot(user, snapshot);
-        plugin.getRedisManager().sendUserDataUpdate(user, snapshot);
+
+        // Save data
+        final RedisManager redis = plugin.getRedisManager();
+        plugin.getDataSyncer().saveData(holder, snapshot, (user, data) -> {
+            redis.getUserData(user).ifPresent(d -> redis.setUserData(user, snapshot, RedisKeyType.TTL_1_YEAR));
+            redis.sendUserDataUpdate(user, data);
+        });
     }
 
 }

common/src/main/java/net/william278/husksync/command/UserDataCommand.java

@@ -21,6 +21,8 @@ package net.william278.husksync.command;
 
 import net.william278.husksync.HuskSync;
 import net.william278.husksync.data.DataSnapshot;
+import net.william278.husksync.redis.RedisKeyType;
+import net.william278.husksync.redis.RedisManager;
 import net.william278.husksync.user.CommandUser;
 import net.william278.husksync.user.User;
 import net.william278.husksync.util.DataDumper;
@@ -110,13 +112,14 @@ public class UserDataCommand extends Command implements TabProvider {
                     return;
                 }
 
-                // Delete user data by specified UUID
+                // Delete user data by specified UUID and clear their data cache
                 final UUID version = optionalUuid.get();
                 if (!plugin.getDatabase().deleteSnapshot(user, version)) {
                     plugin.getLocales().getLocale("error_invalid_version_uuid")
                             .ifPresent(executor::sendMessage);
                     return;
                 }
+                plugin.getRedisManager().clearUserData(user);
 
                 plugin.getLocales().getLocale("data_deleted",
                                 version.toString().split("-")[0],
@@ -152,11 +155,14 @@ public class UserDataCommand extends Command implements TabProvider {
                     );
                 }));
 
-                // Set the user's data and send a message
-                plugin.getDatabase().addSnapshot(user, data);
-                plugin.getRedisManager().sendUserDataUpdate(user, data);
-                plugin.getLocales().getLocale("data_restored", user.getUsername(), user.getUuid().toString(),
-                        data.getShortId(), data.getId().toString()).ifPresent(executor::sendMessage);
+                // Save data
+                final RedisManager redis = plugin.getRedisManager();
+                plugin.getDataSyncer().saveData(user, data, (u, s) -> {
+                    redis.getUserData(u).ifPresent(d -> redis.setUserData(u, s, RedisKeyType.TTL_1_YEAR));
+                    redis.sendUserDataUpdate(u, s);
+                    plugin.getLocales().getLocale("data_restored", u.getUsername(), u.getUuid().toString(),
+                            s.getShortId(), s.getId().toString()).ifPresent(executor::sendMessage);
+                });
             }
 
             case "pin" -> {

common/src/main/java/net/william278/husksync/data/DataSnapshot.java

@@ -23,10 +23,16 @@ import com.google.common.collect.Maps;
 import com.google.gson.annotations.Expose;
 import com.google.gson.annotations.SerializedName;
 import de.themoep.minedown.adventure.MineDown;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.experimental.Accessors;
 import net.william278.desertwell.util.Version;
 import net.william278.husksync.HuskSync;
 import net.william278.husksync.adapter.Adaptable;
 import net.william278.husksync.adapter.DataAdapter;
+import org.apache.commons.text.WordUtils;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -41,6 +47,7 @@ import java.util.stream.Collectors;
  *
  * @since 3.0
  */
+@NoArgsConstructor(access = AccessLevel.PRIVATE)
 public class DataSnapshot {
 
     /*
@@ -59,7 +66,7 @@ public class DataSnapshot {
     protected OffsetDateTime timestamp;
 
     @SerializedName("save_cause")
-    protected SaveCause saveCause;
+    protected String saveCause;
 
     @SerializedName("server_name")
     protected String serverName;
@@ -77,7 +84,7 @@ public class DataSnapshot {
     protected Map<String, String> data;
 
     private DataSnapshot(@NotNull UUID id, boolean pinned, @NotNull OffsetDateTime timestamp,
-                         @NotNull SaveCause saveCause, @NotNull String serverName, @NotNull Map<String, String> data,
+                         @NotNull String saveCause, @NotNull String serverName, @NotNull Map<String, String> data,
                          @NotNull Version minecraftVersion, @NotNull String platformType, int formatVersion) {
         this.id = id;
         this.pinned = pinned;
@@ -90,10 +97,6 @@ public class DataSnapshot {
         this.formatVersion = formatVersion;
     }
 
-    @SuppressWarnings("unused")
-    private DataSnapshot() {
-    }
-
     @NotNull
     @ApiStatus.Internal
     public static DataSnapshot.Builder builder(@NotNull HuskSync plugin) {
@@ -196,7 +199,7 @@ public class DataSnapshot {
      */
     @NotNull
     public SaveCause getSaveCause() {
-        return saveCause;
+        return SaveCause.of(saveCause);
     }
 
     /**
@@ -219,7 +222,7 @@ public class DataSnapshot {
      * @since 3.0
      */
     public void setSaveCause(@NotNull SaveCause saveCause) {
-        this.saveCause = saveCause;
+        this.saveCause = saveCause.name();
     }
 
     /**
@@ -270,24 +273,21 @@ public class DataSnapshot {
      *
      * @since 3.0
      */
+    @NoArgsConstructor(access = AccessLevel.PRIVATE)
     public static class Packed extends DataSnapshot implements Adaptable {
 
         protected Packed(@NotNull UUID id, boolean pinned, @NotNull OffsetDateTime timestamp,
-                         @NotNull SaveCause saveCause, @NotNull String serverName, @NotNull Map<String, String> data,
+                         @NotNull String saveCause, @NotNull String serverName, @NotNull Map<String, String> data,
                          @NotNull Version minecraftVersion, @NotNull String platformType, int formatVersion) {
             super(id, pinned, timestamp, saveCause, serverName, data, minecraftVersion, platformType, formatVersion);
         }
 
-        @SuppressWarnings("unused")
-        private Packed() {
-        }
-
         @ApiStatus.Internal
         public void edit(@NotNull HuskSync plugin, @NotNull Consumer<Unpacked> editor) {
             final Unpacked data = unpack(plugin);
             editor.accept(data);
             this.pinned = data.isPinned();
-            this.saveCause = data.getSaveCause();
+            this.saveCause = data.getSaveCause().name();
             this.data = data.serializeData(plugin);
         }
 
@@ -341,7 +341,7 @@ public class DataSnapshot {
         private final Map<Identifier, Data> deserialized;
 
         private Unpacked(@NotNull UUID id, boolean pinned, @NotNull OffsetDateTime timestamp,
-                         @NotNull SaveCause saveCause, @NotNull String serverName, @NotNull Map<String, String> data,
+                         @NotNull String saveCause, @NotNull String serverName, @NotNull Map<String, String> data,
                          @NotNull Version minecraftVersion, @NotNull String platformType, int formatVersion,
                          @NotNull HuskSync plugin) {
             super(id, pinned, timestamp, saveCause, serverName, data, minecraftVersion, platformType, formatVersion);
@@ -349,7 +349,7 @@ public class DataSnapshot {
         }
 
         private Unpacked(@NotNull UUID id, boolean pinned, @NotNull OffsetDateTime timestamp,
-                         @NotNull SaveCause saveCause, @NotNull String serverName, @NotNull Map<Identifier, Data> data,
+                         @NotNull String saveCause, @NotNull String serverName, @NotNull Map<Identifier, Data> data,
                          @NotNull Version minecraftVersion, @NotNull String platformType, int formatVersion) {
             super(id, pinned, timestamp, saveCause, serverName, Map.of(), minecraftVersion, platformType, formatVersion);
             this.deserialized = data;
@@ -719,7 +719,7 @@ public class DataSnapshot {
                     id,
                     pinned || plugin.getSettings().getSynchronization().doAutoPin(saveCause),
                     timestamp,
-                    saveCause,
+                    saveCause.name(),
                     serverName,
                     data,
                     plugin.getMinecraftVersion(),
@@ -742,138 +742,253 @@ public class DataSnapshot {
 
     }
 
+    public interface Cause {
+
+        @NotNull
+        String name();
+
+        /**
+         * Returns the capitalized display name of the cause.
+         *
+         * @return the cause display name
+         */
+        @NotNull
+        default String getDisplayName() {
+            return WordUtils.capitalizeFully(name().replaceAll("_", " "));
+        }
+
+    }
+
     /**
-     * Identifies the cause of a player data save.
-     *
-     * @implNote This enum is saved in the database.
+     * A string wrapper, for identifying the cause of a player data save.
      * </p>
      * Cause names have a max length of 32 characters.
      */
-    public enum SaveCause {
+    @Accessors(fluent = true)
+    @Getter
+    @AllArgsConstructor(access = AccessLevel.PRIVATE)
+    public static class SaveCause implements Cause {
 
         /**
          * Indicates data saved when a player disconnected from the server (either to change servers, or to log off)
          *
          * @since 2.0
          */
-        DISCONNECT,
+        public static final SaveCause DISCONNECT = of("DISCONNECT");
+
         /**
          * Indicates data saved when the world saved
          *
          * @since 2.0
          */
-        WORLD_SAVE,
+        public static final SaveCause WORLD_SAVE = of("WORLD_SAVE");
+
         /**
          * Indicates data saved when the user died
          *
          * @since 2.1
          */
-        DEATH,
+        public static final SaveCause DEATH = of("DEATH");
+
         /**
          * Indicates data saved when the server shut down
          *
          * @since 2.0
          */
-        SERVER_SHUTDOWN,
+        public static final SaveCause SERVER_SHUTDOWN = of("SERVER_SHUTDOWN");
+
         /**
          * Indicates data was saved by editing inventory contents via the {@code /inventory} command
          *
          * @since 2.0
          */
-        INVENTORY_COMMAND,
+        public static final SaveCause INVENTORY_COMMAND = of("INVENTORY_COMMAND");
+
         /**
          * Indicates data was saved by editing Ender Chest contents via the {@code /enderchest} command
          *
          * @since 2.0
          */
-        ENDERCHEST_COMMAND,
+        public static final SaveCause ENDERCHEST_COMMAND = of("ENDERCHEST_COMMAND");
+
         /**
          * Indicates data was saved by restoring it from a previous version
          *
          * @since 2.0
          */
-        BACKUP_RESTORE,
+        public static final SaveCause BACKUP_RESTORE = of("BACKUP_RESTORE");
+
         /**
          * Indicates data was saved by an API call
          *
          * @since 2.0
          */
-        API,
+        public static final SaveCause API = of("API");
+
         /**
          * Indicates data was saved from being imported from MySQLPlayerDataBridge
          *
          * @since 2.0
          */
-        MPDB_MIGRATION,
+        public static final SaveCause MPDB_MIGRATION = of("MPDB_MIGRATION");
+
         /**
          * Indicates data was saved from being imported from a legacy version (v1.x -> v2.x)
          *
          * @since 2.0
          */
-        LEGACY_MIGRATION,
+        public static final SaveCause LEGACY_MIGRATION = of("LEGACY_MIGRATION");
+
         /**
          * Indicates data was saved from being imported from a legacy version (v2.x -> v3.x)
          *
          * @since 3.0
          */
-        CONVERTED_FROM_V2;
+        public static final SaveCause CONVERTED_FROM_V2 = of("CONVERTED_FROM_V2");
 
         @NotNull
-        public String getDisplayName() {
-            return name().toLowerCase(Locale.ENGLISH);
+        private final String name;
+
+        /**
+         * Get or create a {@link SaveCause} from a name
+         *
+         * @param name the name to be displayed
+         * @return the cause
+         */
+        @NotNull
+        public static SaveCause of(@NotNull String name) {
+            return new SaveCause(name.length() > 32 ? name.substring(0, 31) : name);
         }
 
         @NotNull
         public String getLocale(@NotNull HuskSync plugin) {
-            return plugin.getLocales().getRawLocale("save_cause_" + name().toLowerCase())
+            return plugin.getLocales()
+                    .getRawLocale("save_cause_" + name().toLowerCase(Locale.ENGLISH))
                     .orElse(getDisplayName());
         }
+
+        @NotNull
+        public static SaveCause[] values() {
+            return new SaveCause[]{
+                    DISCONNECT, WORLD_SAVE, DEATH, SERVER_SHUTDOWN, INVENTORY_COMMAND, ENDERCHEST_COMMAND,
+                    BACKUP_RESTORE, API, MPDB_MIGRATION, LEGACY_MIGRATION, CONVERTED_FROM_V2
+            };
+        }
     }
 
     /**
-     * Represents the cause of a player having their data updated.
+     * A string wrapper, for identifying the cause of a player data update.
+     * </p>
+     * Cause names have a max length of 32 characters.
      */
-    public enum UpdateCause {
+    @Accessors(fluent = true)
+    @Getter
+    @AllArgsConstructor(access = AccessLevel.PRIVATE)
+    public static class UpdateCause implements Cause {
+
         /**
          * Indicates the data was updated by a synchronization process
          *
          * @since 3.0
          */
-        SYNCHRONIZED("synchronization_complete", "synchronization_failed"),
+        public static final UpdateCause SYNCHRONIZED = of("SYNCHRONIZED",
+                "synchronization_complete", "synchronization_failed"
+        );
+
         /**
          * Indicates the data was updated by a user joining the server
          *
          * @since 3.0
          */
-        NEW_USER("user_registration_complete", null),
+        public static final UpdateCause NEW_USER = of("NEW_USER",
+                "user_registration_complete", null
+        );
+
         /**
          * Indicates the data was updated by a data update process (management command, API, etc.)
          *
          * @since 3.0
          */
-        UPDATED("data_update_complete", "data_update_failed");
+        public static final UpdateCause UPDATED = of("UPDATED",
+                "data_update_complete", "data_update_failed"
+        );
 
-        private final String completedLocale;
-        private final String failureLocale;
+        /**
+         * Indicates data was saved by an API call
+         *
+         * @since 3.3.3
+         */
+        public static final UpdateCause API = of("API");
 
-        UpdateCause(@Nullable String completedLocale, @Nullable String failureLocale) {
-            this.completedLocale = completedLocale;
-            this.failureLocale = failureLocale;
+        @NotNull
+        private final String name;
+        @Nullable
+        private String completedLocale;
+        @Nullable
+        private String failureLocale;
+
+        /**
+         * Get or create a {@link UpdateCause} from a name and completed/failure locales
+         *
+         * @param name            the name to be displayed
+         * @param completedLocale the locale to be displayed on successful update,
+         *                        or {@code null} if none is to be shown
+         * @param failureLocale   the locale to be displayed on a failed update,
+         *                        or {@code null} if none is to be shown
+         * @return the cause
+         */
+        public static UpdateCause of(@NotNull String name, @Nullable String completedLocale,
+                                     @Nullable String failureLocale) {
+            return new UpdateCause(
+                    name.length() > 32 ? name.substring(0, 31) : name,
+                    completedLocale, failureLocale
+            );
         }
 
+        /**
+         * Get or create a {@link UpdateCause} from a name
+         *
+         * @param name the name to be displayed
+         * @return the cause
+         */
+        @NotNull
+        public static UpdateCause of(@NotNull String name) {
+            return of(name, null, null);
+        }
+
+        /**
+         * Get the message to be displayed when a user's data is successfully updated.
+         *
+         * @param plugin plugin instance
+         * @return the message
+         */
         public Optional<MineDown> getCompletedLocale(@NotNull HuskSync plugin) {
-            if (completedLocale != null) {
-                return plugin.getLocales().getLocale(completedLocale);
+            if (completedLocale() != null) {
+                return Optional.of(plugin.getLocales().getLocale(completedLocale())
+                        .orElse(plugin.getLocales().format(getDisplayName())));
             }
             return Optional.empty();
         }
 
+        /**
+         * Get the message to be displayed when a user's data fails to update.
+         *
+         * @param plugin plugin instance
+         * @return the message
+         */
         public Optional<MineDown> getFailedLocale(@NotNull HuskSync plugin) {
-            if (failureLocale != null) {
-                return plugin.getLocales().getLocale(failureLocale);
+            if (failureLocale() != null) {
+                return Optional.of(plugin.getLocales().getLocale(failureLocale())
+                        .orElse(plugin.getLocales().format(failureLocale())));
             }
             return Optional.empty();
         }
 
+        @NotNull
+        public static UpdateCause[] values() {
+            return new UpdateCause[]{
+                    SYNCHRONIZED, NEW_USER, UPDATED
+            };
+        }
     }
 }

common/src/main/java/net/william278/husksync/database/Database.java

@@ -23,8 +23,6 @@ import lombok.Getter;
 import net.william278.husksync.HuskSync;
 import net.william278.husksync.config.Settings;
 import net.william278.husksync.data.DataSnapshot;
-import net.william278.husksync.data.DataSnapshot.SaveCause;
-import net.william278.husksync.data.UserDataHolder;
 import net.william278.husksync.user.User;
 import org.jetbrains.annotations.Blocking;
 import org.jetbrains.annotations.NotNull;
@@ -33,6 +31,7 @@ import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.time.OffsetDateTime;
 import java.util.*;
+import java.util.function.BiConsumer;
 
 /**
  * An abstract representation of the plugin database, storing player data.
@@ -156,42 +155,23 @@ public abstract class Database {
     @Blocking
     public abstract boolean deleteSnapshot(@NotNull User user, @NotNull UUID versionUuid);
 
-    /**
-     * Save user data to the database
-     * </p>
-     * This will remove the oldest data for the user if the amount of data exceeds the limit as configured
-     *
-     * @param user     The user to add data for
-     * @param snapshot The {@link DataSnapshot} to set.
-     *                 The implementation should version it with a random UUID and the current timestamp during insertion.
-     * @see UserDataHolder#createSnapshot(SaveCause)
-     */
-    @Blocking
-    public void addSnapshot(@NotNull User user, @NotNull DataSnapshot.Packed snapshot) {
-        if (snapshot.getSaveCause() != SaveCause.SERVER_SHUTDOWN) {
-            plugin.fireEvent(
-                    plugin.getDataSaveEvent(user, snapshot),
-                    (event) -> this.addAndRotateSnapshot(user, snapshot)
-            );
-            return;
-        }
-
-        this.addAndRotateSnapshot(user, snapshot);
-    }
 
     /**
-     * <b>Internal</b> - Save user data to the database. This will:
+     * Save user data to the database, doing the following (in order):
      * <ol>
      *     <li>Delete their most recent snapshot, if it was created before the backup frequency time</li>
      *     <li>Create the snapshot</li>
      *     <li>Rotate snapshot backups</li>
      * </ol>
+     * This is an expensive blocking method and should be run off the main thread.
      *
      * @param user     The user to add data for
      * @param snapshot The {@link DataSnapshot} to set.
+     * @apiNote Prefer {@link net.william278.husksync.sync.DataSyncer#saveData(User, DataSnapshot.Packed, BiConsumer)}.
+     * </p>This method will not fire the {@link net.william278.husksync.event.DataSaveEvent}
      */
     @Blocking
-    private void addAndRotateSnapshot(@NotNull User user, @NotNull DataSnapshot.Packed snapshot) {
+    public void addSnapshot(@NotNull User user, @NotNull DataSnapshot.Packed snapshot) {
         final int backupFrequency = plugin.getSettings().getSynchronization().getSnapshotBackupFrequency();
         if (!snapshot.isPinned() && backupFrequency > 0) {
             this.rotateLatestSnapshot(user, snapshot.getTimestamp().minusHours(backupFrequency));

common/src/main/java/net/william278/husksync/listener/EventListener.java

@@ -81,7 +81,7 @@ public abstract class EventListener {
         }
         usersInWorld.stream()
                 .filter(user -> !plugin.isLocked(user.getUuid()) && !user.isNpc())
-                .forEach(user -> plugin.getDatabase().addSnapshot(
+                .forEach(user -> plugin.getDataSyncer().saveData(
                         user, user.createSnapshot(DataSnapshot.SaveCause.WORLD_SAVE)
                 ));
     }
@@ -101,7 +101,7 @@ public abstract class EventListener {
 
         final DataSnapshot.Packed snapshot = user.createSnapshot(DataSnapshot.SaveCause.DEATH);
         snapshot.edit(plugin, (data -> data.getInventory().ifPresent(inventory -> inventory.setContents(items))));
-        plugin.getDatabase().addSnapshot(user, snapshot);
+        plugin.getDataSyncer().saveData(user, snapshot);
     }
 
     /**
@@ -123,7 +123,9 @@ public abstract class EventListener {
                 .filter(user -> !plugin.isLocked(user.getUuid()) && !user.isNpc())
                 .forEach(user -> {
                     plugin.lockPlayer(user.getUuid());
-                    plugin.getDatabase().addSnapshot(user, user.createSnapshot(DataSnapshot.SaveCause.SERVER_SHUTDOWN));
+                    plugin.getDataSyncer().saveData(
+                            user, user.createSnapshot(DataSnapshot.SaveCause.SERVER_SHUTDOWN), null
+                    );
                 });
 
         // Close outstanding connections
@@ -168,7 +170,6 @@ public abstract class EventListener {
             return Map.entry(name().toLowerCase(), defaultPriority.name());
         }
 
-
         @SuppressWarnings("unchecked")
         @NotNull
         public static Map<String, String> getDefaults() {

common/src/main/java/net/william278/husksync/redis/RedisManager.java

@@ -255,6 +255,18 @@ public class RedisManager extends JedisPubSub {
         }
     }
 
+    @Blocking
+    public void clearUserData(@NotNull User user) {
+        try (Jedis jedis = jedisPool.getResource()) {
+            jedis.del(
+                    getKey(RedisKeyType.LATEST_SNAPSHOT, user.getUuid(), clusterId)
+            );
+            plugin.debug(String.format("[%s] Cleared %s on Redis", user.getUsername(), RedisKeyType.LATEST_SNAPSHOT));
+        } catch (Throwable e) {
+            plugin.log(Level.SEVERE, "An exception occurred clearing user data on Redis", e);
+        }
+    }
+
     @Blocking
     public void setUserCheckedOut(@NotNull User user, boolean checkedOut) {
         try (Jedis jedis = jedisPool.getResource()) {

common/src/main/java/net/william278/husksync/sync/DataSyncer.java

@@ -22,14 +22,20 @@ package net.william278.husksync.sync;
 import net.william278.husksync.HuskSync;
 import net.william278.husksync.api.HuskSyncAPI;
 import net.william278.husksync.data.DataSnapshot;
+import net.william278.husksync.database.Database;
+import net.william278.husksync.redis.RedisManager;
 import net.william278.husksync.user.OnlineUser;
+import net.william278.husksync.user.User;
 import net.william278.husksync.util.Task;
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Blocking;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiConsumer;
 import java.util.function.Function;
 import java.util.function.Supplier;
 
@@ -87,6 +93,58 @@ public abstract class DataSyncer {
      */
     public abstract void saveUserData(@NotNull OnlineUser user);
 
+    /**
+     * Save a {@link DataSnapshot.Packed user's data snapshot} to the database,
+     * first firing the {@link net.william278.husksync.event.DataSaveEvent}. This will not update data on Redis.
+     *
+     * @param user  the user to save the data for
+     * @param data  the data to save
+     * @param after a consumer to run after data has been saved. Will be run async (off the main thread).
+     * @apiNote Data will not be saved if the {@link net.william278.husksync.event.DataSaveEvent} is cancelled.
+     * Note that this method can also edit the data before saving it.
+     * @implNote Note that the {@link net.william278.husksync.event.DataSaveEvent} will <b>not</b> be fired if the
+     * save cause is {@link DataSnapshot.SaveCause#SERVER_SHUTDOWN}.
+     * @since 3.3.2
+     */
+    @Blocking
+    public void saveData(@NotNull User user, @NotNull DataSnapshot.Packed data,
+                         @Nullable BiConsumer<User, DataSnapshot.Packed> after) {
+        if (data.getSaveCause() == DataSnapshot.SaveCause.SERVER_SHUTDOWN) {
+            addSnapshotToDatabase(user, data, after);
+            return;
+        }
+        plugin.fireEvent(
+                plugin.getDataSaveEvent(user, data),
+                (event) -> addSnapshotToDatabase(user, data, after)
+        );
+    }
+
+    /**
+     * Save a {@link DataSnapshot.Packed user's data snapshot} to the database,
+     * first firing the {@link net.william278.husksync.event.DataSaveEvent}. This will not update data on Redis.
+     *
+     * @param user the user to save the data for
+     * @param data the data to save
+     * @apiNote Data will not be saved if the {@link net.william278.husksync.event.DataSaveEvent} is cancelled.
+     * Note that this method can also edit the data before saving it.
+     * @implNote Note that the {@link net.william278.husksync.event.DataSaveEvent} will <b>not</b> be fired if the
+     * save cause is {@link DataSnapshot.SaveCause#SERVER_SHUTDOWN}.
+     * @since 3.3.3
+     */
+    public void saveData(@NotNull User user, @NotNull DataSnapshot.Packed data) {
+        saveData(user, data, null);
+    }
+
+    // Adds a snapshot to the database and runs the after consumer
+    @Blocking
+    private void addSnapshotToDatabase(@NotNull User user, @NotNull DataSnapshot.Packed data,
+                                       @Nullable BiConsumer<User, DataSnapshot.Packed> after) {
+        getDatabase().addSnapshot(user, data);
+        if (after != null) {
+            after.accept(user, data);
+        }
+    }
+
     // Calculates the max attempts the system should listen for user data for based on the latency value
     private long getMaxListenAttempts() {
         return BASE_LISTEN_ATTEMPTS + (
@@ -98,7 +156,7 @@ public abstract class DataSyncer {
     // Set a user's data from the database, or set them as a new user
     @ApiStatus.Internal
     protected void setUserFromDatabase(@NotNull OnlineUser user) {
-        plugin.getDatabase().getLatestSnapshot(user).ifPresentOrElse(
+        getDatabase().getLatestSnapshot(user).ifPresentOrElse(
                 snapshot -> user.applySnapshot(snapshot, DataSnapshot.UpdateCause.SYNCHRONIZED),
                 () -> user.completeSync(true, DataSnapshot.UpdateCause.NEW_USER, plugin)
         );
@@ -139,6 +197,16 @@ public abstract class DataSyncer {
         task.get().run();
     }
 
+    @NotNull
+    protected RedisManager getRedis() {
+        return plugin.getRedisManager();
+    }
+
+    @NotNull
+    protected Database getDatabase() {
+        return plugin.getDatabase();
+    }
+
     /**
      * Represents the different available default modes of {@link DataSyncer}
      *

common/src/main/java/net/william278/husksync/sync/DelayDataSyncer.java

@@ -39,7 +39,7 @@ public class DelayDataSyncer extends DataSyncer {
         plugin.runAsyncDelayed(
                 () -> {
                     // Fetch from the database if the user isn't changing servers
-                    if (!plugin.getRedisManager().getUserServerSwitch(user)) {
+                    if (!getRedis().getUserServerSwitch(user)) {
                         this.setUserFromDatabase(user);
                         return;
                     }
@@ -47,7 +47,7 @@ public class DelayDataSyncer extends DataSyncer {
                     // Listen for the data to be updated
                     this.listenForRedisData(
                             user,
-                            () -> plugin.getRedisManager().getUserData(user).map(data -> {
+                            () -> getRedis().getUserData(user).map(data -> {
                                 user.applySnapshot(data, DataSnapshot.UpdateCause.SYNCHRONIZED);
                                 return true;
                             }).orElse(false)
@@ -58,12 +58,13 @@ public class DelayDataSyncer extends DataSyncer {
     }
 
     @Override
-    public void saveUserData(@NotNull OnlineUser user) {
+    public void saveUserData(@NotNull OnlineUser onlineUser) {
         plugin.runAsync(() -> {
-            plugin.getRedisManager().setUserServerSwitch(user);
-            final DataSnapshot.Packed data = user.createSnapshot(DataSnapshot.SaveCause.DISCONNECT);
-            plugin.getRedisManager().setUserData(user, data, RedisKeyType.TTL_10_SECONDS);
-            plugin.getDatabase().addSnapshot(user, data);
+            getRedis().setUserServerSwitch(onlineUser);
+            saveData(
+                    onlineUser, onlineUser.createSnapshot(DataSnapshot.SaveCause.DISCONNECT),
+                    (user, data) -> getRedis().setUserData(user, data, RedisKeyType.TTL_10_SECONDS)
+            );
         });
     }
 

common/src/main/java/net/william278/husksync/sync/LockstepDataSyncer.java

@@ -33,21 +33,21 @@ public class LockstepDataSyncer extends DataSyncer {
 
     @Override
     public void initialize() {
-        plugin.getRedisManager().clearUsersCheckedOutOnServer();
+        getRedis().clearUsersCheckedOutOnServer();
     }
 
     @Override
     public void terminate() {
-        plugin.getRedisManager().clearUsersCheckedOutOnServer();
+        getRedis().clearUsersCheckedOutOnServer();
     }
 
     // Consume their data when they are checked in
     @Override
     public void setUserData(@NotNull OnlineUser user) {
         this.listenForRedisData(user, () -> {
-            if (plugin.getRedisManager().getUserCheckedOut(user).isEmpty()) {
-                plugin.getRedisManager().setUserCheckedOut(user, true);
-                plugin.getRedisManager().getUserData(user).ifPresentOrElse(
+            if (getRedis().getUserCheckedOut(user).isEmpty()) {
+                getRedis().setUserCheckedOut(user, true);
+                getRedis().getUserData(user).ifPresentOrElse(
                         data -> user.applySnapshot(data, DataSnapshot.UpdateCause.SYNCHRONIZED),
                         () -> this.setUserFromDatabase(user)
                 );
@@ -58,12 +58,16 @@ public class LockstepDataSyncer extends DataSyncer {
     }
 
     @Override
-    public void saveUserData(@NotNull OnlineUser user) {
+    public void saveUserData(@NotNull OnlineUser onlineUser) {
         plugin.runAsync(() -> {
-            final DataSnapshot.Packed data = user.createSnapshot(DataSnapshot.SaveCause.DISCONNECT);
-            plugin.getRedisManager().setUserData(user, data, RedisKeyType.TTL_1_YEAR);
-            plugin.getRedisManager().setUserCheckedOut(user, false);
-            plugin.getDatabase().addSnapshot(user, data);
+            getRedis().setUserServerSwitch(onlineUser);
+            saveData(
+                    onlineUser, onlineUser.createSnapshot(DataSnapshot.SaveCause.DISCONNECT),
+                    (user, data) -> {
+                        getRedis().setUserData(user, data, RedisKeyType.TTL_1_YEAR);
+                        getRedis().setUserCheckedOut(user, false);
+                    }
+            );
         });
     }
 

docs/FAQs.md

@@ -46,23 +46,26 @@ This approach is able to dramatically improve both synchronization performance a
 
 This is a very common request, but there's a good reason why HuskSync does not support this.
 
-The Vault API is designed to be a central "Vault" for storing user data. It's the role of economy plugins that *implement* vault to handle the data storage -- and, by extension, synchronization cross-server. Plugins that *hook into* Vault then expect to be able to use the Vault API to get the player's latest economy balance and data.
+Vault is a plugin that provides a common API for developers to do two things:
 
-Plugins such as MySQLPlayerDataBridge that support synchronizing Vault *hook into* Vault and as a result can violate this expectation—plugins that expect Vault to return the latest user data no longer can. As a result, plugins like MySQLPlayerDataBridge have to provide lots of manual hooks and tweaks for individual plugins to ensure compatibility. 
+1. Developers can _implement_ Vault to create economy plugins
+2. Developers can _target_ Vault to modify and check economy balances without having to write code to hook into individual economy plugins
 
-This causes all sorts of compatibility issues with unsupported plugins and increases plugin size and update workload.
+In essence, Vault is beneficial as it allows developers to write less code. A developer only needs to write code that targets the Vault API when you need to do stuff with player economy balances.
 
-As a result, I recommend using an economy plugin (that directly *implements* the Vault API), that works cross-server. XConomy is a popular choice for this, which I have personally had a good experience with in the past.
+_Vault itself, however, is not an Economy plugin_. The developers of Economy plugins that _implement_ are responsible for writing the implementation code and database systems for creating player economy accounts and updating balances. By extension, this also means it is the responsibility of Economy plugin developers to implement Vault's API in a way that allows that data to be synchronized cross-server; Vault itself does not contain API for doing so.
 
+Most Economy plugins do not support doing this, however, as cross-server support isn't (and historically hasn't) been a priority. _MySQLPlayerDataBridge_ allows you to workaround this and synchronize Vault balances — but as detailed above, since Vault itself is not an economy plugin, the way this works is MySQLPlayerDataBridge has to provide and continually maintain a bespoke laundry list of manual, individual hooks and tweaks for both Economy plugins that _implement_ Vault and other plugins that _target_ Vault.
+
+Implementing a similar system in HuskSync would considerably increase the size of the codebase, lengthen update times, and decrease overall system stability. The much better solution is to use an Economy plugin that _implements_ Vault in a way that works cross-server.
+
+Indeed, there exist economy plugins — such as [XConomy](https://github.com/YiC200333/XConomy) and [RedisEconomy](https://github.com/Emibergo02/RedisEconomy) which do just this, and this is my recommended solution. Need to move from an incompatible Economy plugin? Vault provides methods for transferring balances between Economy plugins (`/vault-convert`).
 </details>
 
 <details>
 <summary>&nbsp;<b>Is this better than MySQLPlayerDataBridge?</b></summary>
 
-I can't provide a fair answer to this question! What I can say is that your mileage may vary. The performance improvements offered by HuskSync's synchronization method will depend on your network environment and the economies of scale that come with your player count.
+I can't provide a fair answer to this question! What I can say is that your mileage will of course vary. 
 
-With that said, servers running plugins or mods that make use of custom items (such as MMOItems, SlimeFun) are not supported by HuskSync and so MySQLPlayerDataBridge may be a better choice for you.
-
-A migrator from MPDB is built-in to HuskSync.
-
-</details>
+The performance improvements offered by HuskSync's synchronization method will depend on your network environment and the economies of scale that come with your player count. In terms of featureset, HuskSync does feature greater rollback and snapshot backup/management features if this is something you are looking for.
+</details>

gradle.properties

@@ -3,7 +3,7 @@ org.gradle.jvmargs='-Dfile.encoding=UTF-8'
 org.gradle.daemon=true
 javaVersion=17
 
-plugin_version=3.3
+plugin_version=3.3.3
 plugin_archive=husksync
 plugin_description=A modern, cross-server player data synchronization system
 

paper/src/main/java/net/william278/husksync/listener/PaperEventListener.java

@@ -19,14 +19,17 @@
 
 package net.william278.husksync.listener;
 
+import com.google.common.collect.Lists;
 import net.william278.husksync.BukkitHuskSync;
 import net.william278.husksync.data.BukkitData;
 import net.william278.husksync.user.BukkitUser;
 import net.william278.husksync.user.OnlineUser;
 import org.bukkit.event.entity.PlayerDeathEvent;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
 import org.jetbrains.annotations.NotNull;
 
+import java.util.Iterator;
 import java.util.List;
 
 import static net.william278.husksync.config.Settings.SynchronizationSettings.SaveOnDeathSettings;
@@ -57,7 +60,7 @@ public class PaperEventListener extends BukkitEventListener {
         final int maxInventorySize = BukkitData.Items.Inventory.INVENTORY_SLOT_COUNT;
         final List<ItemStack> itemsToSave = switch (settings.getItemsToSave()) {
             case DROPS -> event.getDrops();
-            case ITEMS_TO_KEEP -> event.getItemsToKeep();
+            case ITEMS_TO_KEEP -> preserveOrder(event.getEntity().getInventory(), event.getItemsToKeep());
         };
         if (itemsToSave.size() > maxInventorySize) {
             itemsToSave.subList(maxInventorySize, itemsToSave.size()).clear();
@@ -65,4 +68,22 @@ public class PaperEventListener extends BukkitEventListener {
         super.saveOnPlayerDeath(user, BukkitData.Items.ItemArray.adapt(itemsToSave));
     }
 
+    @NotNull
+    private List<ItemStack> preserveOrder(@NotNull PlayerInventory inventory, @NotNull List<ItemStack> toKeep) {
+        final List<ItemStack> preserved = Lists.newArrayList();
+        final List<ItemStack> items = Lists.newArrayList(inventory.getContents());
+        for (ItemStack item : toKeep) {
+            final Iterator<ItemStack> iterator = items.iterator();
+            while (iterator.hasNext()) {
+                final ItemStack originalItem = iterator.next();
+                if (originalItem != null && originalItem.equals(item)) {
+                    preserved.add(originalItem);
+                    iterator.remove();
+                    break;
+                }
+            }
+        }
+        return preserved;
+    }
+
 }