Merge pull request #19 from EndlessCodeGroup/feature/items-payload

Items payload support

Author: osipxd

CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+### API
+
+- Add `MimicApiLevel` class to check current running Mimic API version:
+  ```kotlin
+  // Specify here the version required for APIs you use.
+  if (!MimicApiLevel.checkApiLevel(MimicApiLevel.VERSION_0_6)) {
+      println("At least Mimic 0.6 is required. Please download it from {link here}")
+  }
+  ```
+- Add optional payload to `ItemsRegistry.getItem`. It may be used to customize item.
+
 ### Bukkit Plugin
 
 - More detailed output of command `/mimic items info`:
@@ -12,6 +23,8 @@
     minecraft: 976
   ```
 - Improve integration with Heroes class system (#14)
+- Add statistics about used items registries
+- Add payload support to `MinecraftItemsRegistry`.
 
 ### Housekeeping
 

buildSrc/build.gradle.kts

@@ -8,7 +8,9 @@ java {
 }
 
 dependencies {
-    implementation(kotlin("gradle-plugin", version = "1.5.21"))
+    val kotlinVersion = "1.5.21"
+    implementation(kotlin("gradle-plugin", version = kotlinVersion))
+    implementation(kotlin("serialization", version = kotlinVersion))
     implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.5.0")
     implementation("org.jetbrains.kotlinx:binary-compatibility-validator:0.6.0")
     implementation("de.undercouch:gradle-download-task:4.1.2")

buildSrc/src/main/kotlin/HoconSerializationRule.kt

@@ -0,0 +1,15 @@
+import org.gradle.api.artifacts.CacheableRule
+import org.gradle.api.artifacts.ComponentMetadataContext
+import org.gradle.api.artifacts.ComponentMetadataRule
+import org.gradle.api.attributes.java.TargetJvmVersion
+
+@CacheableRule
+abstract class HoconSerializationRule : ComponentMetadataRule {
+    override fun execute(context: ComponentMetadataContext) {
+        context.details.allVariants {
+            attributes {
+                attribute(TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE, 8)
+            }
+        }
+    }
+}

buildSrc/src/main/kotlin/dependencies.kt

@@ -33,6 +33,8 @@ object acf {
 
 object misc {
     const val bstats = "org.bstats:bstats-bukkit:1.8"
+    const val annotations = "org.jetbrains:annotations:13.0"
+    const val serialization_hocon = "org.jetbrains.kotlinx:kotlinx-serialization-hocon:1.2.2"
 }
 
 // Testing

mimic-api/api/mimic-api.api

@@ -1,3 +1,10 @@
+public final class ru/endlesscode/mimic/MimicApiLevel {
+	public static final field CURRENT I
+	public static final field INSTANCE Lru/endlesscode/mimic/MimicApiLevel;
+	public static final field VERSION_0_6 I
+	public static final fun checkApiLevel (I)Z
+}
+
 public abstract interface class ru/endlesscode/mimic/MimicService {
 	public abstract fun getId ()Ljava/lang/String;
 	public abstract fun isEnabled ()Z
@@ -18,7 +25,9 @@ public abstract interface class ru/endlesscode/mimic/classes/ClassSystem {
 
 public abstract interface class ru/endlesscode/mimic/items/ItemsRegistry : ru/endlesscode/mimic/MimicService {
 	public fun getItem (Ljava/lang/String;)Ljava/lang/Object;
-	public abstract fun getItem (Ljava/lang/String;I)Ljava/lang/Object;
+	public fun getItem (Ljava/lang/String;I)Ljava/lang/Object;
+	public fun getItem (Ljava/lang/String;Ljava/lang/Object;)Ljava/lang/Object;
+	public abstract fun getItem (Ljava/lang/String;Ljava/lang/Object;I)Ljava/lang/Object;
 	public abstract fun getItemId (Ljava/lang/Object;)Ljava/lang/String;
 	public abstract fun getKnownIds ()Ljava/util/Collection;
 	public abstract fun isItemExists (Ljava/lang/String;)Z

mimic-api/src/main/kotlin/MimicApiLevel.kt

@@ -0,0 +1,53 @@
+/*
+ * This file is part of Mimic.
+ * Copyright (C) 2021 Osip Fatkullin
+ * Copyright (C) 2021 EndlessCode Group and contributors
+ *
+ * Mimic is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Mimic is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with Mimic.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package ru.endlesscode.mimic
+
+/** Utility to check Mimic API level. */
+public object MimicApiLevel {
+
+    /**
+     * # Version 0.6
+     * - Mimic API levels
+     * - Payload in ItemsRegistry.getItem
+     */
+    public const val VERSION_0_6: Int = 1
+
+    /**
+     * The latest version at the moment of Mimic COMPILATION.
+     *
+     * Usage of this constant will be inlined by the compiler, so use it only to save the version
+     * which was used at your plugin COMPILE TIME.
+     * Use [checkApiLevel] if you want to check that the current RUNNING Mimic API level meets to
+     * the required.
+     */
+    public const val CURRENT: Int = VERSION_0_6
+
+    /**
+     * Returns 'true' if the current RUNNING Mimic API level meets to  the required, otherwise `false`.
+     * ```
+     * // Specify here the version required for APIs you use.
+     * if (!MimicApiLevel.checkApiLevel(MimicApiLevel.VERSION_0_6)) {
+     *     println("At least Mimic 0.6 is required. Please download it from {link here}")
+     * }
+     * ```
+     */
+    @JvmStatic
+    public fun checkApiLevel(apiLevel: Int): Boolean = CURRENT < apiLevel
+}

mimic-api/src/main/kotlin/items/ItemsRegistry.kt

@@ -21,7 +21,7 @@ package ru.endlesscode.mimic.items
 
 import ru.endlesscode.mimic.MimicService
 
-/** Service for getting items by theirs ID. Also can be used to match ID with item. */
+/** Service for getting items by theirs ID. Also, can be used to match ID with item. */
 public interface ItemsRegistry<ItemStackT : Any> : MimicService {
 
     /** Returns all known item IDs. */
@@ -37,13 +37,31 @@ public interface ItemsRegistry<ItemStackT : Any> : MimicService {
     public fun getItemId(item: ItemStackT): String?
 
     /** Returns item by given [itemId], or `null` if the ID not found in this registry. */
-    public fun getItem(itemId: String): ItemStackT? = getItem(itemId, amount = 1)
+    public fun getItem(itemId: String): ItemStackT? = getItem(itemId, payload = null, amount = 1)
+
+    /**
+     * Returns item stack with specified [payload] by given [itemId], or `null` if the ID not found in this registry.
+     *
+     * If [payload] is not `null`, item will be configured using it.
+     */
+    public fun getItem(itemId: String, payload: Any?): ItemStackT? = getItem(itemId, payload, amount = 1)
 
     /**
      * Returns item stack with specified [amount] by given [itemId], or `null` if ID not found in this registry.
      *
      * If given [amount] is greater than maximum possible, will use maximum possible amount.
      * Amount shouldn't be less than `1`.
      */
-    public fun getItem(itemId: String, amount: Int): ItemStackT?
+    public fun getItem(itemId: String, amount: Int): ItemStackT? = getItem(itemId, payload = null, amount)
+
+    /**
+     * Returns item stack with specified [amount] and [payload] by given [itemId],
+     * or `null` if ID not found in this registry.
+     *
+     * If given [amount] is greater than maximum possible, will use maximum possible amount.
+     * Amount shouldn't be less than `1`.
+     *
+     * Given [payload] may be used to configure item.
+     */
+    public fun getItem(itemId: String, payload: Any?, amount: Int): ItemStackT?
 }

mimic-bukkit-api/README.md

@@ -13,10 +13,21 @@ Available services:
 
 ### How to use Mimic APIs?
 
-Firstly you should make sure Mimic is enabled with such method:
+Firstly you should make sure Mimic is enabled:
 ```java
 private boolean checkMimicEnabled() {
-    return getServer().getPluginManager().isPluginEnabled("Mimic");
+    if (!getServer().getPluginManager().isPluginEnabled("Mimic")) {
+        getLogger().severe("Mimic is required for the plugin!");
+        return false;
+    }
+
+    // You can also check if Mimic version is right
+    if (!MimicApiLevel.checkApiLevel(MimicApiLevel.VERSION_0_6)) {
+        getLogger().severe("Required at least Mimic 0.6!");
+        return false;
+    }
+
+    return true;
 }
 ```
 
@@ -26,8 +37,7 @@ Another way is to add it to `softdepend` and show a clear error message to the s
 @Override
 public void onEnable() {
     if (!checkMimicEnabled()) {
-        getLogger().severe("Mimic is required for the plugin!");
-        getLogger().severe("Download it: https://www.spigotmc.org/resources/82515/");
+        getLogger().severe("Download latest version here: https://www.spigotmc.org/resources/82515/");
         getServer().getPluginManager().disablePlugin(this);
         return;
     }
@@ -99,17 +109,27 @@ boolean isMagicStickExists = itemsRegistry.isItemExists("customitems:magic_wand"
         @Override
         public void onEnable() {
             if (!checkMimicEnabled()) {
-                getLogger().severe("Mimic is required for the plugin!");
-                getLogger().severe("Download it on https://www.spigotmc.org/resources/82515/");
+                getLogger().severe("Download latest version here: https://www.spigotmc.org/resources/82515/");
                 getServer().getPluginManager().disablePlugin(this);
                 return;
             }
 
             setupMimic();
         }
-    
+
         private boolean checkMimicEnabled() {
-            return getServer().getPluginManager().isPluginEnabled("Mimic");
+            if (!getServer().getPluginManager().isPluginEnabled("Mimic")) {
+                getLogger().severe("Mimic is required for the plugin!");
+                return false;
+            }
+
+            // You can also check if Mimic version is right
+            if (!MimicApiLevel.checkApiLevel(MimicApiLevel.VERSION_0_6)) {
+                getLogger().severe("Required at least Mimic 0.6!");
+                return false;
+            }
+
+            return true;
         }
 
         private void setupMimic() {

mimic-bukkit/README.md

@@ -32,7 +32,7 @@ No configuration needed.
 
 You can find code of all implementations [here](src/main/kotlin/impl).
 
-#### [Level Systems][BukkitLevelSystem.Provider]
+### [Level Systems][BukkitLevelSystem.Provider]
 
 - **[Minecraft][minecraft-exp]** _(Default)_
 - **[SkillAPI]**
@@ -41,27 +41,43 @@ You can find code of all implementations [here](src/main/kotlin/impl).
 - **[Heroes]**
 - **[QuantumRPG]**
 
-#### [Class Systems][BukkitClassSystem.Provider]
+### [Class Systems][BukkitClassSystem.Provider]
 
 - **Permissions-based** _(Default)_ - give permission `mimic.class.[class_name]` to assign class to player
 - **[SkillAPI]**
 - **[MMOCore]**
 - **[Heroes]**
 - **[QuantumRPG]**
 
-#### [Items Registries][BukkitItemsRegistry]
+### [Items Registries][BukkitItemsRegistry]
 
-[MimicItemsRegistry] - Items registry combining all others items registries.
-It uses service ID as namespace for items IDs.  
-For example: `acacia_boat -> minecraft:acacia_boat`.  
-If you use item ID without a namespace, it will search over all registries.
+#### [MimicItemsRegistry] 
 
- Registry                            | ID Structure      
--------------------------------------|--------------------------
- [Minecraft][MinecraftItemsRegistry] | `minecraft:[id]`
- [CustomItems]                       | `customitems:[id]`
- [MMOItems]                          | `mmoitems:[id]`
- [QuantumRPG]                        | `quantumrpg:[type]/[id]`
+Items registry combining all others items registries.
+It uses service ID as namespace for items IDs.\
+For example: `acacia_boat -> minecraft:acacia_boat`.
+
+> If you use item ID without a namespace, it will search over all registries.
+
+#### [Minecraft][MinecraftItemsRegistry]
+
+**ID Format:** `minecraft:[id]`\
+**Payload:** [ItemMetaPayload]
+
+#### [CustomItems]
+
+**ID Format:** `customitems:[id]`\
+**Payload:** *Not supported*
+
+#### [MMOItems]
+
+**ID Format:** `mmoitems:[id]`\
+**Payload:** *Not supported*
+
+#### [QuantumRPG]
+
+**ID Format:** `quantumrpg:[type]/[id]`\
+**Payload:** *Not supported*
 
 [minecraft-exp]: https://minecraft.gamepedia.com/Experience
 [skillapi]: https://www.spigotmc.org/resources/4824/
@@ -79,3 +95,4 @@ If you use item ID without a namespace, it will search over all registries.
 [BukkitItemsRegistry]: ../mimic-bukkit-api/src/main/kotlin/items/BukkitItemsRegistry.kt
 [MimicItemsRegistry]: src/main/kotlin/impl/mimic/MimicItemsRegistry.kt
 [MinecraftItemsRegistry]: src/main/kotlin/impl/vanilla/MinecraftItemsRegistry.kt
+[ItemMetaPayload]: src/main/kotlin/impl/vanilla/ItemMetaPayload.kt