feat(equipment): pack and restore native shulker contents

README.md

@@ -29,7 +29,15 @@ The file adapter uses safe YAML construction, duplicate-key rejection, bounded r
 
 `TailBooks` creates vanilla `WRITTEN_BOOK` items with static pages. The full character name remains in display/pages; the native title is bounded to vanilla's 32 UTF-16 units without splitting a surrogate pair. `fantasystick:tail_version`, `character_id` and `death_id` identify the saved record. Pages/title are never read as authoritative stats or revival eligibility. Plugin absence does not remove the vanilla written-book contents. The factory does not yet deliver books from a death event.
 
-File-level atomic replacement is **not** atomicity with Minecraft inventory/player saves. This checkpoint does not implement cross-save reconciliation, an administrator lock, automatic overflow drops or equipment/session persistence. Ordinary equipment must still be implemented as actual native shulker contents, never an external-only reconstruction receipt.
+File-level atomic replacement is **not** atomicity with Minecraft inventory/player saves. This checkpoint does not implement cross-save reconciliation, an administrator lock, automatic overflow drops or player/session persistence.
+
+## Native equipment adapter
+
+`EquipmentStorage` preflights and moves nine hotbar/four armor slots into an actual named shulker in one free main-inventory slot. Item counts, metadata/damage/enchantments and legal nested contents remain native item data, accessible without this plugin. Eligibility is tested against the real vanilla shulker slot for every nonlegacy native item material; a main-inventory shulker does not prevent entry. Oversized or ineligible equipment and missing space produce unchanged refusals.
+
+Version-1 box metadata uses `fantasystick:storage_version`, `storage_owner_id`, `storage_session_id` and `storage_slots`. Box positions 0–8 contain original hotbar slots 0–8; positions 9–12 contain boots, leggings, chest and head from player slots 36–39. These metadata fields are for identity/restoration, not the only copy of the items. Restoration searches main slots 9–35, so sorting relocation does not lose the box. Repeated requests, wrong identity, duplicate/malformed boxes, unexpected extra contents or occupied restoration slots do not overwrite/delete items. These are adapter error results, not a persistent administrator lock or completed recovery policy.
+
+The caller must remove authenticated fantasy controls before restoration. One new head stack uses the slot freed by removing the box, even with a full main inventory; there is no drop fallback. The adapter does not yet route sheet/cursor events, emit entry warnings, manage character/player snapshots or register a playable session. Native tests use real player-slot storage with only the absent network recipient stubbed; client packets and live gameplay remain unverified.
 
 ## CI and publication
 

src/main/java/games/dmg/fantasystick/items/EquipmentStorage.java

@@ -0,0 +1,111 @@
+package games.dmg.fantasystick.items;
+
+import java.util.Arrays;
+import java.util.Objects;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.block.ShulkerBox;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.bukkit.inventory.meta.BlockStateMeta;
+import org.bukkit.persistence.PersistentDataType;
+
+/** Server-thread inventory operations; session eligibility and event routing belong to the caller. */
+public final class EquipmentStorage {
+    public enum PackResult { PACKED, NO_SPACE, INELIGIBLE_EQUIPMENT, ALREADY_PACKED }
+
+    private static final int[] EQUIPMENT_SLOTS = {0, 1, 2, 3, 4, 5, 6, 7, 8, 36, 37, 38, 39};
+    private static final NamespacedKey VERSION = key("storage_version");
+    private static final NamespacedKey OWNER = key("storage_owner_id");
+    private static final NamespacedKey SESSION = key("storage_session_id");
+    private static final NamespacedKey SLOTS = key("storage_slots");
+
+    public PackResult pack(PlayerInventory inventory, UUID owner, UUID session) {
+        Objects.requireNonNull(owner);
+        Objects.requireNonNull(session);
+        for (int slot = 9; slot < 36; slot++) {
+            if (matches(inventory.getItem(slot), owner, session)) return PackResult.ALREADY_PACKED;
+        }
+        for (int slot : EQUIPMENT_SLOTS) {
+            var item = inventory.getItem(slot);
+            if (!empty(item) && item.getType().name().endsWith("SHULKER_BOX")) return PackResult.INELIGIBLE_EQUIPMENT;
+        }
+        int available = -1;
+        for (int slot = 9; slot < 36; slot++) {
+            if (empty(inventory.getItem(slot))) { available = slot; break; }
+        }
+        if (available == -1) return PackResult.NO_SPACE;
+        var item = new ItemStack(Material.SHULKER_BOX);
+        var meta = (BlockStateMeta) item.getItemMeta();
+        var box = (ShulkerBox) meta.getBlockState();
+        var contents = box.getInventory();
+        for (int i = 0; i < EQUIPMENT_SLOTS.length; i++) {
+            var equipment = inventory.getItem(EQUIPMENT_SLOTS[i]);
+            if (!empty(equipment) && equipment.getAmount() > Math.min(equipment.getMaxStackSize(), contents.getMaxStackSize())) {
+                return PackResult.INELIGIBLE_EQUIPMENT;
+            }
+            contents.setItem(i, equipment);
+        }
+        meta.setBlockState(box);
+        meta.displayName(Component.text("Fantasy Storage Box"));
+        var data = meta.getPersistentDataContainer();
+        data.set(VERSION, PersistentDataType.INTEGER, 1);
+        data.set(OWNER, PersistentDataType.STRING, owner.toString());
+        data.set(SESSION, PersistentDataType.STRING, session.toString());
+        data.set(SLOTS, PersistentDataType.INTEGER_ARRAY, EQUIPMENT_SLOTS.clone());
+        item.setItemMeta(meta);
+        for (int slot : EQUIPMENT_SLOTS) inventory.setItem(slot, null);
+        inventory.setItem(available, item);
+        return PackResult.PACKED;
+    }
+
+    public enum RestoreResult { RESTORED, NOT_FOUND, AMBIGUOUS, INVALID_BOX, OCCUPIED_SLOT }
+
+    /** Caller removes validated fantasy controls first. Unexpected slot occupants are never overwritten. */
+    public RestoreResult restore(PlayerInventory inventory, UUID owner, UUID session) {
+        Objects.requireNonNull(owner);
+        Objects.requireNonNull(session);
+        int found = -1;
+        for (int slot = 9; slot < 36; slot++) {
+            if (matches(inventory.getItem(slot), owner, session)) {
+                if (found != -1) return RestoreResult.AMBIGUOUS;
+                found = slot;
+            }
+        }
+        if (found == -1) return RestoreResult.NOT_FOUND;
+        var item = inventory.getItem(found);
+        if (item.getAmount() != 1 || !(item.getItemMeta() instanceof BlockStateMeta meta)
+                || !(meta.getBlockState() instanceof ShulkerBox box)) return RestoreResult.INVALID_BOX;
+        var data = meta.getPersistentDataContainer();
+        if (!data.has(VERSION, PersistentDataType.INTEGER) || data.get(VERSION, PersistentDataType.INTEGER) != 1
+                || !data.has(SLOTS, PersistentDataType.INTEGER_ARRAY)
+                || !Arrays.equals(EQUIPMENT_SLOTS, data.get(SLOTS, PersistentDataType.INTEGER_ARRAY))) {
+            return RestoreResult.INVALID_BOX;
+        }
+        var contents = box.getInventory();
+        for (int slot = EQUIPMENT_SLOTS.length; slot < contents.getSize(); slot++) {
+            if (!empty(contents.getItem(slot))) return RestoreResult.INVALID_BOX;
+        }
+        for (int slot : EQUIPMENT_SLOTS) {
+            if (slot != 39 && !empty(inventory.getItem(slot))) return RestoreResult.OCCUPIED_SLOT;
+        }
+        var currentHead = inventory.getItem(39);
+        var displacedHead = empty(currentHead) ? null : currentHead.clone();
+        for (int i = 0; i < EQUIPMENT_SLOTS.length; i++) inventory.setItem(EQUIPMENT_SLOTS[i], contents.getItem(i));
+        inventory.setItem(found, displacedHead);
+        return RestoreResult.RESTORED;
+    }
+
+    private static boolean matches(ItemStack item, UUID owner, UUID session) {
+        if (empty(item)) return false;
+        var data = item.getItemMeta().getPersistentDataContainer();
+        return data.has(OWNER, PersistentDataType.STRING) && data.has(SESSION, PersistentDataType.STRING)
+            && owner.toString().equals(data.get(OWNER, PersistentDataType.STRING))
+            && session.toString().equals(data.get(SESSION, PersistentDataType.STRING));
+    }
+
+    private static NamespacedKey key(String name) { return new NamespacedKey("fantasystick", name); }
+    private static boolean empty(ItemStack item) { return item == null || item.isEmpty(); }
+}

src/nativeTest/java/games/dmg/fantasystick/EquipmentStorageNativeTest.java

@@ -0,0 +1,274 @@
+package games.dmg.fantasystick;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import games.dmg.fantasystick.items.EquipmentStorage;
+import java.util.Arrays;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import net.minecraft.core.NonNullList;
+import net.minecraft.core.component.DataComponents;
+import net.minecraft.nbt.NbtOps;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.world.entity.EntityEquipment;
+import net.minecraft.world.entity.player.Inventory;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataType;
+import org.bukkit.block.ShulkerBox;
+import org.bukkit.craftbukkit.CraftRegistry;
+import org.bukkit.craftbukkit.inventory.CraftInventoryPlayer;
+import org.bukkit.craftbukkit.inventory.CraftItemStack;
+import org.bukkit.enchantments.Enchantment;
+import org.bukkit.inventory.InventoryHolder;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.BlockStateMeta;
+import org.bukkit.inventory.meta.Damageable;
+import org.bukkit.inventory.meta.BundleMeta;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class EquipmentStorageNativeTest {
+    @BeforeAll static void bootstrap() throws Exception { NativeRuntime.bootstrap(); }
+
+    private static CraftInventoryPlayer inventory() {
+        // Real native player slot/equipment storage. Only the absent network recipient is stubbed.
+        return new CraftInventoryPlayer(new Inventory(null, new EntityEquipment()) {
+            @Override public InventoryHolder getOwner() { return null; }
+        });
+    }
+
+    @Test
+    void malformedAmbiguousAndOccupiedRestorationPathsLeaveAllItemsUntouched() {
+        for (int variant = 0; variant < 6; variant++) {
+            var inventory = inventory();
+            var owner = UUID.randomUUID();
+            var session = UUID.randomUUID();
+            var storage = new EquipmentStorage();
+            inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+            assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+            var item = inventory.getItem(9);
+            var meta = item.getItemMeta();
+            var expected = EquipmentStorage.RestoreResult.INVALID_BOX;
+            switch (variant) {
+                case 0 -> {
+                    meta.getPersistentDataContainer().set(new NamespacedKey("fantasystick", "storage_version"), PersistentDataType.INTEGER, 2);
+                    item.setItemMeta(meta);
+                }
+                case 1 -> {
+                    meta.getPersistentDataContainer().set(new NamespacedKey("fantasystick", "storage_slots"), PersistentDataType.INTEGER_ARRAY, new int[]{35, 35});
+                    item.setItemMeta(meta);
+                }
+                case 2 -> {
+                    inventory.setItem(0, new ItemStack(Material.EMERALD));
+                    expected = EquipmentStorage.RestoreResult.OCCUPIED_SLOT;
+                }
+                case 3 -> {
+                    inventory.setItem(10, item.clone());
+                    expected = EquipmentStorage.RestoreResult.AMBIGUOUS;
+                }
+                case 4 -> item.setAmount(2);
+                case 5 -> {
+                    var impostor = new ItemStack(Material.SHULKER_BOX);
+                    var impostorMeta = impostor.getItemMeta();
+                    impostorMeta.displayName(Component.text("Fantasy Storage Box"));
+                    impostor.setItemMeta(impostorMeta);
+                    inventory.setItem(9, impostor);
+                    expected = EquipmentStorage.RestoreResult.NOT_FOUND;
+                }
+                default -> throw new AssertionError();
+            }
+            var before = snapshot(inventory);
+            assertEquals(expected, storage.restore(inventory, owner, session), "variant " + variant);
+            assertArrayEquals(before, inventory.getContents(), "variant " + variant);
+        }
+    }
+
+    @Test
+    void eligibilityMatchesTheActualVanillaShulkerSlotForEveryNativeItemMaterial() {
+        var nativeSlot = new net.minecraft.world.inventory.ShulkerBoxSlot(new net.minecraft.world.SimpleContainer(27), 0, 0, 0);
+        var storage = new EquipmentStorage();
+        for (Material material : Material.values()) {
+            if (material.isLegacy() || !material.isItem() || material.isAir()) continue;
+            var item = new ItemStack(material);
+            boolean allowed = nativeSlot.mayPlace(CraftItemStack.asNMSCopy(item));
+            var inventory = inventory();
+            inventory.setItem(0, item);
+            assertEquals(allowed ? EquipmentStorage.PackResult.PACKED : EquipmentStorage.PackResult.INELIGIBLE_EQUIPMENT,
+                storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()), material.name());
+        }
+    }
+
+    @Test
+    void rejectsOversizedStacksBeforeAnyEquipmentMoves() {
+        var inventory = inventory();
+        inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+        inventory.setItem(8, new ItemStack(Material.ARROW, 65));
+        var before = snapshot(inventory);
+        assertEquals(EquipmentStorage.PackResult.INELIGIBLE_EQUIPMENT,
+            new EquipmentStorage().pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        assertArrayEquals(before, inventory.getContents());
+    }
+
+    @Test
+    void fullMainInventoryRefusesUnchangedAndOnlyAMainSlotCountsAsSpace() {
+        var inventory = inventory();
+        for (int slot = 9; slot < 36; slot++) inventory.setItem(slot, new ItemStack(Material.STONE, 64));
+        inventory.setItem(0, new ItemStack(Material.DIAMOND, 12));
+        inventory.setItemInOffHand(new ItemStack(Material.PAPER));
+        var before = snapshot(inventory);
+        var storage = new EquipmentStorage();
+        assertEquals(EquipmentStorage.PackResult.NO_SPACE, storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        assertArrayEquals(before, inventory.getContents());
+        inventory.setItem(35, null);
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        assertEquals(Material.SHULKER_BOX, inventory.getItem(35).getType());
+    }
+
+    @Test
+    void refusesUnexpectedBoxContentsInsteadOfDeletingThemOnRestoration() {
+        var inventory = inventory();
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        var item = inventory.getItem(9);
+        var meta = (BlockStateMeta) item.getItemMeta();
+        var box = (ShulkerBox) meta.getBlockState();
+        box.getInventory().setItem(26, new ItemStack(Material.EMERALD, 64));
+        meta.setBlockState(box);
+        item.setItemMeta(meta);
+        var before = snapshot(inventory);
+        assertEquals(EquipmentStorage.RestoreResult.INVALID_BOX, storage.restore(inventory, owner, session));
+        assertArrayEquals(before, inventory.getContents());
+    }
+
+    @Test
+    void repeatedPackingAndWrongOwnerOrSessionCannotDuplicateOrRestoreEquipment() {
+        var inventory = inventory();
+        inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        var packed = snapshot(inventory);
+        assertEquals(EquipmentStorage.PackResult.ALREADY_PACKED, storage.pack(inventory, owner, session));
+        assertArrayEquals(packed, inventory.getContents());
+        assertEquals(EquipmentStorage.RestoreResult.NOT_FOUND, storage.restore(inventory, UUID.randomUUID(), session));
+        assertEquals(EquipmentStorage.RestoreResult.NOT_FOUND, storage.restore(inventory, owner, UUID.randomUUID()));
+        assertArrayEquals(packed, inventory.getContents());
+    }
+
+    @Test
+    void keepsNewHeadInTheFreedBoxSlotEvenWhenMainInventoryIsFull() {
+        var inventory = inventory();
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        var helmet = new ItemStack(Material.DIAMOND_HELMET);
+        var meta = (Damageable) helmet.getItemMeta();
+        meta.setDamage(93);
+        meta.addEnchant(Enchantment.PROTECTION, 4, true);
+        helmet.setItemMeta(meta);
+        inventory.setHelmet(helmet);
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        for (int slot = 10; slot < 36; slot++) inventory.setItem(slot, new ItemStack(Material.COBBLESTONE, 64));
+        var pumpkin = new ItemStack(Material.CARVED_PUMPKIN);
+        inventory.setHelmet(pumpkin);
+        assertEquals(EquipmentStorage.RestoreResult.RESTORED, storage.restore(inventory, owner, session));
+        assertEquals(helmet, inventory.getHelmet(), "Existing damage and protection are not repaired or discarded");
+        assertEquals(pumpkin, inventory.getItem(9));
+        for (int slot = 10; slot < 36; slot++) assertEquals(new ItemStack(Material.COBBLESTONE, 64), inventory.getItem(slot));
+    }
+
+    @Test
+    void nativeSerializedContentsNeedNoPluginAndRestoreAfterTheBoxMoves() {
+        var inventory = inventory();
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        for (int slot = 0; slot < 9; slot++) inventory.setItem(slot, new ItemStack(Material.ARROW, slot + 1));
+        var nested = new ItemStack(Material.BUNDLE);
+        var bundle = (BundleMeta) nested.getItemMeta();
+        bundle.addItem(new ItemStack(Material.EMERALD, 12));
+        nested.setItemMeta(bundle);
+        inventory.setItem(3, nested);
+        inventory.setHelmet(new ItemStack(Material.DIAMOND_HELMET));
+        inventory.setLeggings(new ItemStack(Material.IRON_LEGGINGS));
+        inventory.setChestplate(new ItemStack(Material.ELYTRA));
+        inventory.setBoots(new ItemStack(Material.GOLDEN_BOOTS));
+        var before = snapshot(inventory);
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        var ops = RegistryOps.create(NbtOps.INSTANCE, CraftRegistry.getMinecraftRegistry());
+        var encoded = net.minecraft.world.item.ItemStack.CODEC.encodeStart(ops,
+            CraftItemStack.asNMSCopy(inventory.getItem(9))).getOrThrow();
+        var decoded = net.minecraft.world.item.ItemStack.CODEC.parse(ops, encoded).getOrThrow();
+        // Minecraft's native container component, not a Fantasy Stick reconstruction receipt.
+        var contents = NonNullList.withSize(27, net.minecraft.world.item.ItemStack.EMPTY);
+        assertNotNull(decoded.get(DataComponents.CONTAINER));
+        decoded.get(DataComponents.CONTAINER).copyInto(contents);
+        assertTrue(net.minecraft.world.item.ItemStack.matches(CraftItemStack.asNMSCopy(nested), contents.get(3)));
+        assertTrue(net.minecraft.world.item.ItemStack.matches(CraftItemStack.asNMSCopy(before[36]), contents.get(9)));
+        assertTrue(net.minecraft.world.item.ItemStack.matches(CraftItemStack.asNMSCopy(before[39]), contents.get(12)));
+        inventory.setItem(9, null);
+        inventory.setItem(35, CraftItemStack.asBukkitCopy(decoded));
+        assertEquals(EquipmentStorage.RestoreResult.RESTORED, storage.restore(inventory, owner, session));
+        assertArrayEquals(before, inventory.getContents());
+        assertEquals(EquipmentStorage.RestoreResult.NOT_FOUND, storage.restore(inventory, owner, session));
+        assertArrayEquals(before, inventory.getContents());
+    }
+
+    @Test
+    void refusesEveryShulkerColorInPackedSlotsWithoutAnyPartialMutation() {
+        for (Material material : Material.values()) {
+            if (!material.name().endsWith("SHULKER_BOX") || material.isLegacy()) continue;
+            for (int slot : new int[]{0, 8, 36, 39}) {
+                var inventory = inventory();
+                inventory.setItem(1, new ItemStack(Material.DIAMOND, 12));
+                inventory.setItem(slot, new ItemStack(material));
+                var before = snapshot(inventory);
+                assertEquals(EquipmentStorage.PackResult.INELIGIBLE_EQUIPMENT,
+                    new EquipmentStorage().pack(inventory, UUID.randomUUID(), UUID.randomUUID()), material + " slot " + slot);
+                assertArrayEquals(before, inventory.getContents());
+            }
+        }
+    }
+
+    private static ItemStack[] snapshot(CraftInventoryPlayer inventory) {
+        return Arrays.stream(inventory.getContents()).map(item -> item == null ? null : item.clone()).toArray(ItemStack[]::new);
+    }
+
+    @Test
+    void movesActualHotbarAndArmorIntoOneNativeShulkerWithoutTouchingMainItemsOrSheet() {
+        var inventory = inventory();
+        var sword = new ItemStack(Material.DIAMOND_SWORD);
+        var meta = (Damageable) sword.getItemMeta();
+        meta.setDamage(137);
+        meta.displayName(Component.text("Old sword"));
+        sword.setItemMeta(meta);
+        var arrows = new ItemStack(Material.ARROW, 47);
+        var boots = new ItemStack(Material.DIAMOND_BOOTS);
+        inventory.setItem(0, sword);
+        inventory.setItem(8, arrows);
+        inventory.setBoots(boots);
+        var unrelated = new ItemStack(Material.RED_SHULKER_BOX);
+        var sheet = new ItemStack(Material.PAPER);
+        inventory.setItem(9, unrelated);
+        inventory.setItemInOffHand(sheet);
+        var storage = new EquipmentStorage();
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        for (int i = 0; i < 9; i++) assertNull(inventory.getItem(i));
+        assertTrue(inventory.getBoots().isEmpty());
+        assertEquals(unrelated, inventory.getItem(9));
+        assertEquals(sheet, inventory.getItemInOffHand());
+        var boxItem = inventory.getItem(10);
+        assertNotNull(boxItem);
+        assertEquals(Material.SHULKER_BOX, boxItem.getType());
+        assertEquals(Component.text("Fantasy Storage Box"), boxItem.getItemMeta().displayName());
+        var box = (ShulkerBox) ((BlockStateMeta) boxItem.getItemMeta()).getBlockState();
+        assertEquals(sword, box.getInventory().getItem(0));
+        assertEquals(arrows, box.getInventory().getItem(8));
+        assertEquals(boots, box.getInventory().getItem(9));
+    }
+}