✨ feat(inventory): add offline inventory editing commands for players

- implement commands to set item slots and equipment for offline players
- add summary and clear commands for offline inventory management
- introduce EquipmentSlotArgument for equipment slot validation

Author: twisti-dev

surf-api-paper/surf-api-paper-plugin-test/src/main/java/dev/slne/surf/api/paper/test/command/SurfApiTestCommand.java

@@ -31,7 +31,8 @@ public SurfApiTestCommand() {
                 new ShowItemCommand("showitem"),
                 new SortInvCommand("sortInv"),
                 new SignedMessageArgumentTest("signedmessage"),
-                new BlockPdcContainerTest("blockpdc")
+                new BlockPdcContainerTest("blockpdc"),
+                new OfflineInventoryEditTest("editOfflineInventory")
         );
     }
 }

surf-api-paper/surf-api-paper-plugin-test/src/main/kotlin/dev/slne/surf/surfapi/bukkit/test/command/args/EquipmentSlotArgument.kt

@@ -0,0 +1,26 @@
+package dev.slne.surf.surfapi.bukkit.test.command.args
+
+import dev.jorel.commandapi.arguments.ArgumentSuggestions
+import dev.jorel.commandapi.arguments.CustomArgument
+import dev.jorel.commandapi.arguments.StringArgument
+import org.bukkit.inventory.EquipmentSlot
+
+class EquipmentSlotArgument(name: String) :
+    CustomArgument<EquipmentSlot, String>(StringArgument(name), { info ->
+        try {
+            EquipmentSlot.valueOf(info.input)
+        } catch (e: IllegalArgumentException) {
+            throw CustomArgumentException.fromMessageBuilder(
+                MessageBuilder()
+                    .append("Invalid equipment slot: ")
+                    .appendArgInput()
+                    .append(" (valid: ")
+                    .append(EquipmentSlot.entries.joinToString(", ") { it.name })
+                    .append(")")
+            )
+        }
+    }) {
+    init {
+        replaceSuggestions(ArgumentSuggestions.strings(EquipmentSlot.entries.map { it.name }))
+    }
+}

surf-api-paper/surf-api-paper-plugin-test/src/main/kotlin/dev/slne/surf/surfapi/bukkit/test/command/subcommands/OfflineInventoryEditTest.kt

@@ -0,0 +1,137 @@
+@file:OptIn(NmsUseWithCaution::class)
+
+package dev.slne.surf.surfapi.bukkit.test.command.subcommands
+
+import dev.jorel.commandapi.CommandAPICommand
+import dev.jorel.commandapi.arguments.AsyncPlayerProfileArgument
+import dev.jorel.commandapi.kotlindsl.argument
+import dev.jorel.commandapi.kotlindsl.getValue
+import dev.jorel.commandapi.kotlindsl.integerArgument
+import dev.jorel.commandapi.kotlindsl.subcommand
+import dev.slne.surf.api.paper.command.executors.anyExecutorSuspend
+import dev.slne.surf.api.paper.command.executors.playerExecutorSuspend
+import dev.slne.surf.api.paper.command.util.awaitAsyncPlayerProfile
+import dev.slne.surf.api.paper.command.util.idOrThrow
+import dev.slne.surf.api.paper.extensions.server
+import dev.slne.surf.api.paper.nms.NmsUseWithCaution
+import dev.slne.surf.api.paper.nms.bridges.SurfPaperNmsPlayerBridge
+import dev.slne.surf.surfapi.bukkit.test.command.args.EquipmentSlotArgument
+import org.bukkit.command.CommandSender
+import org.bukkit.inventory.EquipmentSlot
+import java.util.*
+
+class OfflineInventoryEditTest(name: String) : CommandAPICommand(name) {
+    init {
+        setSlotCommand()
+        setEquipmentCommand()
+        summaryCommand()
+        clearCommand()
+    }
+
+    private fun setSlotCommand() = subcommand("set-slot") {
+        argument(AsyncPlayerProfileArgument("player"))
+        integerArgument("slot", 0, 35)
+
+        playerExecutorSuspend { sender, args ->
+            val target = args.awaitAsyncPlayerProfile("player").idOrThrow()
+            val slot: Int by args
+            val item = sender.inventory.itemInMainHand.clone()
+
+            if (item.isEmpty) {
+                sender.sendMessage("Hold an item in your main hand to copy it into the offline inventory.")
+                return@playerExecutorSuspend
+            }
+
+            if (!runEdit(sender, target) { edit ->
+                edit.items[slot] = item
+            }) return@playerExecutorSuspend
+
+            sender.sendMessage("Set slot $slot of $target to ${item.type.key.asString()} x${item.amount}.")
+        }
+    }
+
+    private fun setEquipmentCommand() = subcommand("set-equipment") {
+        argument(AsyncPlayerProfileArgument("player"))
+        argument(EquipmentSlotArgument("slot"))
+
+        playerExecutorSuspend { sender, args ->
+            val target = args.awaitAsyncPlayerProfile("player").idOrThrow()
+            val slot: EquipmentSlot by args
+            val item = sender.inventory.itemInMainHand.clone()
+
+            if (item.isEmpty) {
+                sender.sendMessage("Hold an item in your main hand to copy it into the offline equipment.")
+                return@playerExecutorSuspend
+            }
+
+            if (!runEdit(sender, target) { edit ->
+                edit.equipment.setItem(slot, item)
+            }) return@playerExecutorSuspend
+
+            sender.sendMessage("Set equipment slot ${slot.name} of $target to ${item.type.key.asString()} x${item.amount}.")
+        }
+    }
+
+    private fun summaryCommand() = subcommand("summary") {
+        argument(AsyncPlayerProfileArgument("player"))
+
+        anyExecutorSuspend { sender, args ->
+            val target = args.awaitAsyncPlayerProfile("player").idOrThrow()
+            var inventoryItems = emptyList<String>()
+            var equipmentItems = emptyList<String>()
+
+            if (!runEdit(sender, target) { edit ->
+                inventoryItems = edit.items.withIndex()
+                    .filter { (_, item) -> !item.isEmpty }
+                    .map { (slot, item) -> "slot $slot=${item.type.key.asString()} x${item.amount}" }
+
+                equipmentItems = EDITABLE_EQUIPMENT_SLOTS
+                    .map { slot -> slot to edit.equipment.getItem(slot) }
+                    .filter { (_, item) -> !item.isEmpty }
+                    .map { (slot, item) -> "${slot.name}=${item.type.key.asString()} x${item.amount}" }
+            }) return@anyExecutorSuspend
+
+            sender.sendMessage("Offline inventory summary for ${target}:")
+            sender.sendMessage("Inventory: ${inventoryItems.ifEmpty { listOf("empty") }.joinToString()}")
+            sender.sendMessage("Equipment: ${equipmentItems.ifEmpty { listOf("empty") }.joinToString()}")
+        }
+    }
+
+    private fun clearCommand() = subcommand("clear") {
+        argument(AsyncPlayerProfileArgument("player"))
+
+        anyExecutorSuspend { sender, args ->
+            val target = args.awaitAsyncPlayerProfile("player").idOrThrow()
+
+            if (!runEdit(sender, target) { edit ->
+                edit.items.clear()
+                edit.equipment.clear()
+            }) return@anyExecutorSuspend
+
+            sender.sendMessage("Cleared offline inventory and equipment of ${target}.")
+        }
+    }
+
+    private suspend fun runEdit(
+        sender: CommandSender,
+        target: UUID,
+        edit: (SurfPaperNmsPlayerBridge.PlayerInventoryEdit) -> Unit
+    ): Boolean {
+        return runCatching {
+            SurfPaperNmsPlayerBridge.editOfflineInventory(server.getOfflinePlayer(target), edit)
+        }.onFailure { error ->
+            sender.sendMessage("editOfflineInventory failed: ${error::class.simpleName}: ${error.message}")
+        }.isSuccess
+    }
+
+    companion object {
+        private val EDITABLE_EQUIPMENT_SLOTS = listOf(
+            EquipmentSlot.HAND,
+            EquipmentSlot.OFF_HAND,
+            EquipmentSlot.HEAD,
+            EquipmentSlot.CHEST,
+            EquipmentSlot.LEGS,
+            EquipmentSlot.FEET
+        )
+    }
+}