feat: add Rarity enum for item and entity rarity representation

gradle.properties

@@ -7,6 +7,6 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 javaVersion=25
 mcVersion=1.21.11
 group=dev.slne.surf
-version=1.21.11-2.63.1
+version=1.21.11-2.64.0
 relocationPrefix=dev.slne.surf.surfapi.libs
 snapshot=false

surf-api-bukkit/surf-api-bukkit-api/api/surf-api-bukkit-api.api

@@ -2177,6 +2177,22 @@ public abstract class dev/slne/surf/surfapi/bukkit/api/permission/PermissionRegi
 	public final fun create (Ljava/lang/String;)Ljava/lang/String;
 }
 
+public final class dev/slne/surf/surfapi/bukkit/api/rarity/Rarity : java/lang/Enum, net/kyori/adventure/text/ComponentLike {
+	public static final field COMMON Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+	public static final field EPIC Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+	public static final field LEGENDARY Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+	public static final field MYTHIC Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+	public static final field RARE Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+	public static final field UNCOMMON Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+	public synthetic fun asComponent ()Lnet/kyori/adventure/text/Component;
+	public fun asComponent ()Lnet/kyori/adventure/text/TextComponent;
+	public final fun getColor ()Lnet/kyori/adventure/text/format/TextColor;
+	public final fun getDisplayName ()Lnet/kyori/adventure/text/TextComponent;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+	public static fun values ()[Ldev/slne/surf/surfapi/bukkit/api/rarity/Rarity;
+}
+
 public abstract interface annotation class dev/slne/surf/surfapi/bukkit/api/scoreboard/ObsoleteScoreboardApi : java/lang/annotation/Annotation {
 }
 

surf-api-core/surf-api-core-api/api/surf-api-core-api.api

@@ -8299,6 +8299,22 @@ public abstract interface class dev/slne/surf/surfapi/core/api/random/Weighted {
 	public abstract fun getWeight ()D
 }
 
+public final class dev/slne/surf/surfapi/core/api/rarity/Rarity : java/lang/Enum, net/kyori/adventure/text/ComponentLike {
+	public static final field COMMON Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+	public static final field EPIC Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+	public static final field LEGENDARY Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+	public static final field MYTHIC Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+	public static final field RARE Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+	public static final field UNCOMMON Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+	public synthetic fun asComponent ()Lnet/kyori/adventure/text/Component;
+	public fun asComponent ()Lnet/kyori/adventure/text/TextComponent;
+	public final fun getColor ()Lnet/kyori/adventure/text/format/TextColor;
+	public final fun getDisplayName ()Lnet/kyori/adventure/text/TextComponent;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+	public static fun values ()[Ldev/slne/surf/surfapi/core/api/rarity/Rarity;
+}
+
 public abstract interface annotation class dev/slne/surf/surfapi/core/api/reflection/Constructor : java/lang/annotation/Annotation {
 }
 

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/rarity/Rarity.kt

@@ -0,0 +1,48 @@
+package dev.slne.surf.surfapi.core.api.rarity
+
+import dev.slne.surf.surfapi.core.api.messages.adventure.buildText
+import dev.slne.surf.surfapi.core.api.messages.builder.SurfComponentBuilder
+import net.kyori.adventure.text.ComponentLike
+import net.kyori.adventure.text.format.TextColor
+
+/**
+ * Represents the rarity of an item or entity within the system.
+ *
+ * Each rarity level is associated with a display name and a color,
+ * allowing visually distinct representations for different levels.
+ *
+ * @property displayName The visual display name of the rarity level.
+ * @property color       The textual color associated with the rarity level.
+ */
+enum class Rarity(
+    displayName: SurfComponentBuilder.() -> Unit,
+    val color: TextColor
+) : ComponentLike {
+    COMMON(
+        displayName = { spacer("Gewöhnlich") },
+        color = TextColor.color(0xAAAAAA)
+    ),
+    UNCOMMON(
+        displayName = { spacer("Ungewöhnlich") },
+        color = TextColor.color(0x55FF55)
+    ),
+    RARE(
+        displayName = { success("Selten") },
+        color = TextColor.color(0x55FFFF)
+    ),
+    EPIC(
+        displayName = { info("Episch") },
+        color = TextColor.color(0xFF55FF)
+    ),
+    LEGENDARY(
+        displayName = { warning("Legendär") },
+        color = TextColor.color(0xFFAA00)
+    ),
+    MYTHIC(
+        displayName = { error("Mythisch") },
+        color = TextColor.color(0xAA00AA)
+    );
+
+    val displayName = buildText(displayName)
+    override fun asComponent() = displayName
+}