Draft: Implement BlocksRegistry API

build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
 
 // Common configurations for all Mimic projects
 subprojects {
-    version = "0.8.0"
+    version = "0.9.0-SNAPSHOT"
     group = "ru.endlesscode.mimic"
 }
 

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

@@ -52,6 +52,12 @@ public object MimicApiLevel {
      */
     public const val VERSION_0_8: Int = 4
 
+    /**
+     * # Version 0.9
+     * - Experimental API: BlocksRegistry
+     */
+    public const val VERSION_0_9: Int = 5
+
     /**
      * The latest version at the moment of Mimic **COMPILATION**.
      *
@@ -60,7 +66,7 @@ public object MimicApiLevel {
      * Use [checkApiLevel] if you want to check that the current **RUNNING**
      * Mimic API level meets to the required API level.
      */
-    public const val CURRENT: Int = VERSION_0_8
+    public const val CURRENT: Int = VERSION_0_9
 
     /**
      * Returns `true` if the current **RUNNING** Mimic API level is equal

mimic-api/src/main/kotlin/blocks/BlocksRegistry.kt

@@ -0,0 +1,81 @@
+package blocks
+
+import ru.endlesscode.mimic.ExperimentalMimicApi
+import ru.endlesscode.mimic.MimicService
+
+/**
+ * Registry to get and place blocks.
+ * @since 0.9.0
+ */
+@ExperimentalMimicApi
+public interface BlocksRegistry<ItemStackT : Any, BlockT : Any> : MimicService {
+
+    /** Returns all known block IDs. */
+    public val knownIds: Collection<String>
+
+    /** Returns `true` if given [block] represented with given [blockId]. */
+    public fun isSameBlock(block: BlockT, blockId: String): Boolean = getBlockId(block) == blockId
+
+    /** Returns `true` if given [blockItem] is an item stack containing the block represented with given [blockId]. */
+    public fun isSameBlockItem(blockItem: ItemStackT, blockId: String): Boolean = getBlockItemId(blockItem) == blockId
+
+    /** Returns `true` if block with given [blockId] exists. */
+    public fun isBlockExists(blockId: String): Boolean
+
+    /** Returns ID representing given [block], or `null` if the ID not found in this registry. */
+    public fun getBlockId(block: BlockT): String?
+
+    /**
+     * Returns ID representing the block contained in given [blockItem],
+     * or `null` if the ID not found in this registry.
+     */
+    public fun getBlockItemId(blockItem: ItemStackT): String?
+
+    /** Returns item containing block by given [blockId], or `null` if the ID not found in this registry. */
+    public fun getBlockItem(blockId: String): ItemStackT? = getBlockItem(blockId, payload = null, amount = 1)
+
+    /**
+     * Returns item containing block with specified [payload] by given [blockId],
+     * or `null` if the ID not found in this registry.
+     *
+     * If [payload] is not `null`, block will be configured using it.
+     */
+    public fun getBlockItem(blockId: String, payload: Any?): ItemStackT? = getBlockItem(blockId, payload, amount = 1)
+
+    /**
+     * Returns item containing block with specified [amount] by given [blockId],
+     * or `null` if ID not found in this registry.
+     *
+     * If the given [amount] is greater than maximum possible, will use maximum possible amount.
+     * Amount shouldn't be less than `1`.
+     */
+    public fun getBlockItem(blockId: String, amount: Int): ItemStackT? = getBlockItem(blockId, payload = null, amount)
+
+    /**
+     * Returns item containing block with specified [amount] and [payload] by given [blockId],
+     * or `null` if ID not found in this registry.
+     *
+     * If the 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 block.
+     */
+    public fun getBlockItem(blockId: String, payload: Any?, amount: Int): ItemStackT?
+
+    /**
+     * Places block by given [blockId] at [destination].
+     *
+     * Returns `true` if the block was placed, and `false` if ID not found in this registry.
+     */
+    public fun placeBlock(blockId: String, destination: BlockT): Boolean =
+        placeBlock(blockId, payload = null, destination)
+
+    /**
+     * Places block with specified [payload] by given [blockId] at [destination].
+     *
+     * Given [payload] may be used to configure block.
+     *
+     * Returns `true` if the block was placed, and `false` if ID not found in this registry.
+     */
+    public fun placeBlock(blockId: String, payload: Any?, destination: BlockT): Boolean
+}

mimic-bukkit-api/src/main/kotlin/Mimic.kt

@@ -5,6 +5,7 @@ import org.bukkit.entity.Player
 import org.bukkit.plugin.Plugin
 import org.bukkit.plugin.ServicePriority
 import org.jetbrains.annotations.ApiStatus
+import ru.endlesscode.mimic.blocks.BukkitBlocksRegistry
 import ru.endlesscode.mimic.bukkit.load
 import ru.endlesscode.mimic.classes.BukkitClassSystem
 import ru.endlesscode.mimic.inventory.BukkitPlayerInventory
@@ -14,6 +15,68 @@ import ru.endlesscode.mimic.level.BukkitLevelSystem
 /** Mimic provides access to abstraction APIs. */
 public interface Mimic {
 
+    // region Blocks Registry
+    /**
+     * Registers the given [registry] with normal priority.
+     *
+     * @param registry The [BukkitBlocksRegistry] implementation
+     * @param apiLevel Minimal required API level for this item registry implementation:
+     *                 - if required API level is higher than installed Mimic, provider will not be registered,
+     *                 - if required API level is lower - will be enabled compatibility mode.
+     *                 Specify `MimicApiLevel.CURRENT` to use API level of Mimic dependency used on compile time.
+     * @param plugin The plugin implementing this item registry.
+     * @return registered registry or `null` if it was not registered.
+     * @since 0.9.0
+     */
+    @ExperimentalMimicApi
+    @ApiStatus.Experimental
+    public fun registerBlocksRegistry(
+        registry: BukkitBlocksRegistry,
+        apiLevel: Int,
+        plugin: Plugin,
+    ): BukkitBlocksRegistry? = registerBlocksRegistry(registry, apiLevel, plugin, ServicePriority.Normal)
+
+    /**
+     * Registers the given [registry].
+     *
+     * @param registry The [BukkitBlocksRegistry] implementation
+     * @param apiLevel Minimal required API level for this item registry implementation:
+     *                 - if required API level is higher than installed Mimic, provider will not be registered,
+     *                 - if required API level is lower - will be enabled compatibility mode.
+     *                 Specify `MimicApiLevel.CURRENT` to use API level of Mimic dependency used on compile time.
+     * @param plugin The plugin implementing this item registry.
+     * @param priority Default priority. Service with higher priority will be used if user have not configured
+     *                 preferred service in config.
+     * @return registered registry or `null` if it was not registered.
+     * @since 0.9.0
+     */
+    @ExperimentalMimicApi
+    @ApiStatus.Experimental
+    public fun registerBlocksRegistry(
+        registry: BukkitBlocksRegistry,
+        apiLevel: Int,
+        plugin: Plugin,
+        priority: ServicePriority,
+    ): BukkitBlocksRegistry?
+
+    /**
+     * Returns [BukkitBlocksRegistry] implementation.
+     * @since 0.9.0
+     */
+    @ExperimentalMimicApi
+    @ApiStatus.Experimental
+    public fun getBlocksRegistry(): BukkitBlocksRegistry
+
+    /**
+     * Returns map containing all known [BukkitBlocksRegistry], where key is an item registry ID.
+     * @since 0.9.0
+     */
+    @ExperimentalMimicApi
+    @ApiStatus.Experimental
+    public fun getAllBlocksRegistries(): Map<String, BukkitBlocksRegistry>
+    // endregion
+
+    // region Class System
     /**
      * Registers the given [provider] for [BukkitClassSystem] with normal priority.
      *
@@ -62,7 +125,9 @@ public interface Mimic {
 
     /** Returns map containing all known [BukkitClassSystem.Provider]s, where key is a provider ID. */
     public fun getAllClassSystemProviders(): Map<String, BukkitClassSystem.Provider>
+    // endregion
 
+    // region Inventory Provider
     /**
      * Registers the given [provider] for [BukkitPlayerInventory] with normal priority.
      *
@@ -133,7 +198,9 @@ public interface Mimic {
     @ExperimentalMimicApi
     @ApiStatus.Experimental
     public fun getAllPlayerInventoryProviders(): Map<String, BukkitPlayerInventory.Provider>
+    // endregion
 
+    // region Items Registry
     /**
      * Registers the given [registry] with normal priority.
      *
@@ -176,7 +243,9 @@ public interface Mimic {
 
     /** Returns map containing all known [BukkitItemsRegistry], where key is an item registry ID. */
     public fun getAllItemsRegistries(): Map<String, BukkitItemsRegistry>
+    // endregion
 
+    // region Level System
     /**
      * Registers the given [provider] for [BukkitLevelSystem] with normal priority.
      *
@@ -225,6 +294,7 @@ public interface Mimic {
 
     /** Returns map containing all known [BukkitLevelSystem.Provider]s, where key is a provider ID. */
     public fun getAllLevelSystemProviders(): Map<String, BukkitLevelSystem.Provider>
+    // endregion
 
     public companion object {
         /**

mimic-bukkit-api/src/main/kotlin/blocks/BukkitBlocksRegistry.kt

@@ -0,0 +1,13 @@
+package ru.endlesscode.mimic.blocks
+
+import blocks.BlocksRegistry
+import org.bukkit.block.Block
+import org.bukkit.inventory.ItemStack
+import ru.endlesscode.mimic.ExperimentalMimicApi
+
+/**
+ * [BlocksRegistry] for Bukkit.
+ * @since 0.9.0
+ */
+@ExperimentalMimicApi
+public interface BukkitBlocksRegistry : BlocksRegistry<ItemStack, Block>

mimic-bukkit/src/main/kotlin/MimicImpl.kt

@@ -3,6 +3,7 @@ package ru.endlesscode.mimic
 import org.bukkit.plugin.Plugin
 import org.bukkit.plugin.ServicePriority
 import org.bukkit.plugin.ServicesManager
+import ru.endlesscode.mimic.blocks.BukkitBlocksRegistry
 import ru.endlesscode.mimic.bukkit.loadAll
 import ru.endlesscode.mimic.bukkit.register
 import ru.endlesscode.mimic.classes.BukkitClassSystem
@@ -23,6 +24,26 @@ internal class MimicImpl(
     private val config: MimicConfig,
 ) : Mimic {
 
+    // region Blocks Registry
+    @ExperimentalMimicApi
+    override fun registerBlocksRegistry(
+        registry: BukkitBlocksRegistry,
+        apiLevel: Int,
+        plugin: Plugin,
+        priority: ServicePriority
+    ): BukkitBlocksRegistry? = tryRegisterService<BukkitBlocksRegistry>(apiLevel, plugin, priority) {
+        TODO("Not implemented yet")
+        // WrappedBlocksRegistry(registry, config, plugin)
+    }
+
+    @ExperimentalMimicApi
+    override fun getBlocksRegistry(): BukkitBlocksRegistry = loadService()
+
+    @ExperimentalMimicApi
+    override fun getAllBlocksRegistries(): Map<String, BukkitBlocksRegistry> = loadAllServices()
+    // endregion
+
+    // region Class System
     override fun registerClassSystem(
         provider: BukkitClassSystem.Provider,
         apiLevel: Int,
@@ -34,7 +55,9 @@ internal class MimicImpl(
 
     override fun getClassSystemProvider(): BukkitClassSystem.Provider = loadService(config.classSystem)
     override fun getAllClassSystemProviders(): Map<String, BukkitClassSystem.Provider> = loadAllServices()
+    // endregion
 
+    // region Inventory Provider
     @ExperimentalMimicApi
     override fun registerPlayerInventoryProvider(
         provider: PlayerInventoryProvider,
@@ -50,7 +73,9 @@ internal class MimicImpl(
 
     @ExperimentalMimicApi
     override fun getAllPlayerInventoryProviders(): Map<String, PlayerInventoryProvider> = loadAllServices()
+    // endregion
 
+    // region Items Registry
     override fun registerItemsRegistry(
         registry: BukkitItemsRegistry,
         apiLevel: Int,
@@ -62,7 +87,9 @@ internal class MimicImpl(
 
     override fun getItemsRegistry(): BukkitItemsRegistry = loadService()
     override fun getAllItemsRegistries(): Map<String, BukkitItemsRegistry> = loadAllServices()
+    // endregion
 
+    // region Level System
     override fun registerLevelSystem(
         provider: BukkitLevelSystem.Provider,
         apiLevel: Int,
@@ -74,6 +101,7 @@ internal class MimicImpl(
 
     override fun getLevelSystemProvider(): BukkitLevelSystem.Provider = loadService(config.levelSystem)
     override fun getAllLevelSystemProviders(): Map<String, BukkitLevelSystem.Provider> = loadAllServices()
+    // endregion
 
     private inline fun <reified Service : MimicService> tryRegisterService(
         apiLevel: Int,
@@ -138,6 +166,7 @@ internal class MimicImpl(
         BukkitLevelSystem.Provider::class -> "LevelSystem"
         BukkitPlayerInventory.Provider::class -> "PlayerInventory"
         BukkitItemsRegistry::class -> "ItemsRegistry"
+        BukkitBlocksRegistry::class -> "BlocksRegistry"
         else -> error("Unknown service: ${this.java.name}")
     }
 }