feat: Introduce item tiers, integrate them into special item creation and behavior, and update the /hcu give command to support tier specification.

src/main/kotlin/net/hareworks/hcu/items/command/CommandRegistrar.kt

@@ -8,6 +8,7 @@ import org.bukkit.permissions.PermissionDefault
 import org.bukkit.entity.Player
 import net.hareworks.hcu.items.domain.ItemRegistry
 import net.hareworks.hcu.items.domain.SpecialItem
+import net.hareworks.hcu.items.domain.Tier
 
 object CommandRegistrar {
     fun register(plugin: App, permits: MutationSession): KommandLib {
@@ -62,8 +63,48 @@ object CommandRegistrar {
                                 return@executes
                             }
                             
-                            sender.inventory.addItem(item.createItemStack())
+                            sender.inventory.addItem(item.createItemStack(Tier.ONE))
-                            sender.sendMessage("Given $itemId to yourself.")
+                            sender.sendMessage("Given $itemId (Tier 1) to yourself.")
+                        }
+
+                        integer("tier", min = 1, max = 5) {
+                            executes {
+                                val sender = sender
+                                if (sender !is Player) {
+                                    sender.sendMessage("Only players can use this command without a target.")
+                                    return@executes
+                                }
+                                val itemId = argument<String>("itemId")
+                                val tierLevel = argument<Int>("tier")
+                                val item = ItemRegistry.get(itemId)
+                                val tier = Tier.fromLevel(tierLevel) ?: Tier.ONE
+                                
+                                if (item == null) {
+                                    sender.sendMessage("Unknown item: $itemId")
+                                    return@executes
+                                }
+                                
+                                sender.inventory.addItem(item.createItemStack(tier))
+                                sender.sendMessage("Given $itemId (Tier ${tier.level}) to yourself.")
+                            }
+
+                            player("target") {
+                                executes {
+                                    val target = argument<Player>("target")
+                                    val itemId = argument<String>("itemId")
+                                    val tierLevel = argument<Int>("tier")
+                                    val item = ItemRegistry.get(itemId)
+                                    val tier = Tier.fromLevel(tierLevel) ?: Tier.ONE
+                                    
+                                    if (item == null) {
+                                        sender.sendMessage("Unknown item: $itemId")
+                                        return@executes
+                                    }
+                                    
+                                    target.inventory.addItem(item.createItemStack(tier))
+                                    sender.sendMessage("Given $itemId (Tier ${tier.level}) to ${target.name}.")
+                                }
+                            }
                         }
                         
                         player("target") {
@@ -77,8 +118,8 @@ object CommandRegistrar {
                                     return@executes
                                 }
                                 
-                                target.inventory.addItem(item.createItemStack())
+                                target.inventory.addItem(item.createItemStack(Tier.ONE))
-                                sender.sendMessage("Given $itemId to ${target.name}.")
+                                sender.sendMessage("Given $itemId (Tier 1) to ${target.name}.")
                             }
                         }
                     }

src/main/kotlin/net/hareworks/hcu/items/domain/SpecialItem.kt

@@ -15,13 +15,15 @@ abstract class SpecialItem(val id: String) {
     /**
      * Creates a new ItemStack for this special item.
      * Subclasses should override [buildItem] to define the item's properties.
+     * @param tier The tier of the item to create. Defaults to [Tier.ONE].
      */
-    fun createItemStack(): ItemStack {
+    fun createItemStack(tier: Tier = Tier.ONE): ItemStack {
-        val item = buildItem()
+        val item = buildItem(tier)
         val meta = item.itemMeta ?: return item
         
         // Tag the item as a special HCU item
         meta.persistentDataContainer.set(KEY_HCU_ITEM_ID, PersistentDataType.STRING, id)
+        meta.persistentDataContainer.set(KEY_HCU_ITEM_TIER, PersistentDataType.INTEGER, tier.level)
         
         item.itemMeta = meta
         return item
@@ -30,8 +32,9 @@ abstract class SpecialItem(val id: String) {
     /**
      * Builds the base ItemStack.
      * This method should configure the material, name, lore, etc.
+     * @param tier The tier of the item being built.
      */
-    protected abstract fun buildItem(): ItemStack
+    protected abstract fun buildItem(tier: Tier): ItemStack
 
     /**
      * Called when a player interacts with this item.
@@ -40,6 +43,7 @@ abstract class SpecialItem(val id: String) {
 
     companion object {
         val KEY_HCU_ITEM_ID = NamespacedKey("hcu_items", "id")
+        val KEY_HCU_ITEM_TIER = NamespacedKey("hcu_items", "tier")
 
         /**
          * Checks if the given item is a special HCU item.
@@ -56,5 +60,14 @@ abstract class SpecialItem(val id: String) {
             if (item == null || item.type.isAir) return null
             return item.itemMeta?.persistentDataContainer?.get(KEY_HCU_ITEM_ID, PersistentDataType.STRING)
         }
+
+        /**
+         * Gets the Tier of the given item. Defaults to [Tier.ONE] if not found/valid.
+         */
+        fun getTier(item: ItemStack?): Tier {
+            if (item == null || item.type.isAir) return Tier.ONE
+            val level = item.itemMeta?.persistentDataContainer?.get(KEY_HCU_ITEM_TIER, PersistentDataType.INTEGER) ?: return Tier.ONE
+            return Tier.fromLevel(level) ?: Tier.ONE
+        }
     }
 }

src/main/kotlin/net/hareworks/hcu/items/domain/Tier.kt

@@ -0,0 +1,18 @@
+package net.hareworks.hcu.items.domain
+
+import net.kyori.adventure.text.format.NamedTextColor
+import net.kyori.adventure.text.format.TextColor
+
+enum class Tier(val level: Int, val color: TextColor) {
+    ONE(1, NamedTextColor.WHITE),
+    TWO(2, NamedTextColor.GREEN),
+    THREE(3, NamedTextColor.AQUA),
+    FOUR(4, NamedTextColor.LIGHT_PURPLE),
+    FIVE(5, NamedTextColor.GOLD);
+
+    companion object {
+        fun fromLevel(level: Int): Tier? {
+            return entries.find { it.level == level }
+        }
+    }
+}

src/main/kotlin/net/hareworks/hcu/items/domain/impl/TestItem.kt

@@ -1,19 +1,21 @@
 package net.hareworks.hcu.items.domain.impl
 
 import net.hareworks.hcu.items.domain.SpecialItem
+import net.hareworks.hcu.items.domain.Tier
 import net.kyori.adventure.text.Component
 import net.kyori.adventure.text.format.NamedTextColor
 import org.bukkit.Material
 import org.bukkit.inventory.ItemStack
 
 class TestItem : SpecialItem("test_sword") {
-    override fun buildItem(): ItemStack {
+    override fun buildItem(tier: Tier): ItemStack {
         val item = ItemStack(Material.DIAMOND_SWORD)
         val meta = item.itemMeta ?: return item
         
-        meta.displayName(Component.text("Test Sword", NamedTextColor.GOLD))
+        meta.displayName(Component.text("Test Sword ${tier.level}", tier.color))
         meta.lore(listOf(
-            Component.text("A special sword for testing purposes.", NamedTextColor.GRAY)
+            Component.text("A special sword for testing purposes.", NamedTextColor.GRAY),
+            Component.text("Tier: ${tier.name}", tier.color)
         ))
         
         item.itemMeta = meta
@@ -21,6 +23,13 @@ class TestItem : SpecialItem("test_sword") {
     }
 
     override fun onInteract(event: org.bukkit.event.player.PlayerInteractEvent) {
-        event.player.sendMessage(Component.text("You used the Test Sword!", NamedTextColor.GREEN))
+        val item = event.item
+        val tier = SpecialItem.getTier(item)
+        
+        event.player.sendMessage(Component.text("You used the Test Sword (Tier ${tier.level})!", tier.color))
+        
+        if (tier.level >= 3) {
+            event.player.sendMessage(Component.text("High tier bonus activated!", NamedTextColor.GOLD))
+        }
     }
 }