- KDocを更新

Author: Hiiragi283

src/api/kotlin/hiiragi283/ragium/api/RagiumAPI.kt

@@ -11,6 +11,7 @@ import hiiragi283.ragium.api.extension.mutableTableOf
 import hiiragi283.ragium.api.machine.HTMachineType
 import hiiragi283.ragium.api.material.HTMaterialKey
 import hiiragi283.ragium.api.material.HTMaterialRegistry
+import hiiragi283.ragium.api.storage.HTItemSlot
 import hiiragi283.ragium.api.util.HTMultiMap
 import hiiragi283.ragium.api.util.HTTable
 import net.minecraft.core.BlockPos
@@ -23,6 +24,7 @@ import net.minecraft.server.level.ServerPlayer
 import net.minecraft.tags.TagKey
 import net.minecraft.world.entity.player.Inventory
 import net.minecraft.world.inventory.AbstractContainerMenu
+import net.minecraft.world.item.ItemStack
 import net.minecraft.world.level.material.Fluid
 import net.neoforged.fml.LogicalSide
 import net.neoforged.neoforge.energy.IEnergyStorage
@@ -101,6 +103,9 @@ interface RagiumAPI {
      */
     fun getCurrentServer(): MinecraftServer?
 
+    /**
+     * 現在の物理サイドを返します。
+     */
     fun getCurrentSide(): LogicalSide
 
     fun getEnergyNetwork(): (ServerLevel) -> IEnergyStorage = ::getEnergyNetwork
@@ -199,4 +204,15 @@ interface RagiumAPI {
      * @see [HTMachineType.getBlock]
      */
     fun getMachineBlock(type: HTMachineType): DeferredBlock<*>
+
+    /**
+     * @see [HTItemSlot.Builder.build]
+     */
+    fun buildItemSlot(
+        maxSize: Int,
+        insertFilter: (ItemStack, HTStorageIO) -> Boolean,
+        extractFilter: (ItemStack, HTStorageIO) -> Boolean,
+        validator: (ItemStack) -> Boolean,
+        callback: Runnable,
+    ): HTItemSlot
 }

src/api/kotlin/hiiragi283/ragium/api/block/entity/HTBlockEntity.kt

@@ -25,6 +25,9 @@ import net.minecraft.world.level.block.state.BlockState
 import net.minecraft.world.phys.BlockHitResult
 import java.util.function.Supplier
 
+/**
+ * Ragiumで使用する[BlockEntity]の基本クラス
+ */
 abstract class HTBlockEntity(type: Supplier<out BlockEntityType<*>>, pos: BlockPos, state: BlockState) :
     BlockEntity(type.get(), pos, state) {
     companion object {

src/api/kotlin/hiiragi283/ragium/api/block/entity/HTErrorHoldingBlockEntity.kt

@@ -1,5 +1,10 @@
 package hiiragi283.ragium.api.block.entity
 
+import net.minecraft.world.level.block.entity.BlockEntity
+
+/**
+ * エラーメッセージを保持する[BlockEntity]
+ */
 fun interface HTErrorHoldingBlockEntity {
     fun getErrorMessage(): String?
 }

src/api/kotlin/hiiragi283/ragium/api/block/entity/HTPlayerOwningBlockEntity.kt

@@ -3,18 +3,28 @@ package hiiragi283.ragium.api.block.entity
 import com.mojang.serialization.Codec
 import hiiragi283.ragium.api.RagiumAPI
 import net.minecraft.core.UUIDUtil
+import net.minecraft.server.level.ServerPlayer
 import net.minecraft.util.ExtraCodecs
-import net.minecraft.world.entity.player.Player
+import net.minecraft.world.level.block.entity.BlockEntity
 import java.util.*
 
+/**
+ * 所有者を保持する[BlockEntity]
+ */
 interface HTPlayerOwningBlockEntity {
     companion object {
         @JvmField
         val UUID_CODEC: Codec<Optional<UUID>> = ExtraCodecs.optionalEmptyMap(UUIDUtil.STRING_CODEC)
     }
 
+    /**
+     * 所有者の[UUID]を返します。
+     */
     val ownerUUID: UUID?
 
-    val owner: Player?
+    /**
+     * 現在のサーバーと[ownerUUID]から，所有者の[ServerPlayer]を返します。
+     */
+    val owner: ServerPlayer?
         get() = RagiumAPI.getInstance().getPlayer(ownerUUID)
 }

src/api/kotlin/hiiragi283/ragium/api/capability/HTStorageIO.kt

@@ -1,6 +1,7 @@
 package hiiragi283.ragium.api.capability
 
 import hiiragi283.ragium.api.RagiumAPI
+import net.minecraft.world.level.block.entity.BlockEntity
 import net.neoforged.neoforge.energy.IEnergyStorage
 import net.neoforged.neoforge.fluids.capability.IFluidHandler
 import net.neoforged.neoforge.items.IItemHandlerModifiable
@@ -9,9 +10,29 @@ import net.neoforged.neoforge.items.IItemHandlerModifiable
  * ストレージの搬入出を管理するクラス
  */
 enum class HTStorageIO(val canInsert: Boolean, val canExtract: Boolean) {
+    /**
+     * ホッパーやパイプを介した搬入
+     */
     INPUT(true, false),
+
+    /**
+     * ホッパーやパイプを介した搬出
+     */
     OUTPUT(false, true),
+
+    /**
+     * デフォルトの操作
+     */
     GENERIC(true, true),
+
+    /**
+     * GUI上のでプレイヤーによる操作
+     */
+    INVENTORY(true, true),
+
+    /**
+     * [BlockEntity]内での操作
+     */
     INTERNAL(false, false),
     ;
 

src/api/kotlin/hiiragi283/ragium/api/data/HTTagBuilder.kt

@@ -11,6 +11,9 @@ import net.minecraft.resources.ResourceLocation
 import net.minecraft.tags.TagEntry
 import net.minecraft.tags.TagKey
 
+/**
+ * 登録した[TagKey]をソートして生成するビルダー
+ */
 @Suppress("UNCHECKED_CAST")
 class HTTagBuilder<T : Any>(val lookup: HolderLookup.RegistryLookup<T>) {
     private val entryCache: HTMultiMap.Mutable<TagKey<T>, Entry> = multiMapOf()

src/api/kotlin/hiiragi283/ragium/api/data/recipe/HTIngredientBuilder.kt

@@ -1,6 +1,5 @@
 package hiiragi283.ragium.api.data.recipe
 
-import com.mojang.logging.LogUtils
 import hiiragi283.ragium.api.extension.commonTag
 import hiiragi283.ragium.api.material.HTMaterialKey
 import hiiragi283.ragium.api.material.HTTagPrefix
@@ -26,18 +25,16 @@ import net.neoforged.neoforge.fluids.FluidStack
 import net.neoforged.neoforge.fluids.FluidType
 import net.neoforged.neoforge.fluids.crafting.FluidIngredient
 import net.neoforged.neoforge.registries.DeferredHolder
-import org.slf4j.Logger
 import java.util.function.Supplier
 
+/**
+ * 機械レシピのビルダーの基本クラス
+ * @param T このクラスを継承したビルダーのクラス
+ * @param R 生成する機械レシピのクラス
+ * @param lookup 現在未使用
+ */
 abstract class HTMachineRecipeBuilderBase<T : HTMachineRecipeBuilderBase<T, R>, R : HTMachineRecipeBase>(val lookup: HolderGetter<Item>) :
     RecipeBuilder {
-    companion object {
-        @JvmStatic
-        private val LOGGER: Logger = LogUtils.getLogger()
-    }
-
-    private var isErrored: Boolean = false
-
     //    Item Input    //
 
     fun itemInput(item: ItemLike, count: Int = 1): T = itemInput(HTItemIngredient.of(item, count))
@@ -115,15 +112,7 @@ abstract class HTMachineRecipeBuilderBase<T : HTMachineRecipeBuilderBase<T, R>,
         save(recipeOutput, getPrimalId().withSuffix(suffix))
     }
 
-    private fun logWarn(id: ResourceLocation) {
-        LOGGER.debug("Machine recipe: {} will not be saved!", id)
-    }
-
     final override fun save(recipeOutput: RecipeOutput, id: ResourceLocation) {
-        if (isErrored) {
-            logWarn(id)
-            return
-        }
         recipeOutput.accept(fixId(id), createRecipe(), null)
     }
 
@@ -136,10 +125,6 @@ abstract class HTMachineRecipeBuilderBase<T : HTMachineRecipeBuilderBase<T, R>,
     protected abstract fun createRecipe(): R
 
     fun export(id: ResourceLocation, consumer: (RecipeHolder<R>) -> Unit) {
-        if (isErrored) {
-            logWarn(id)
-            return
-        }
         consumer(RecipeHolder(fixId(id), createRecipe()))
     }
 }

src/api/kotlin/hiiragi283/ragium/api/data/recipe/HTMachineRecipeBuilderBase.kt

@@ -20,12 +20,23 @@ import net.neoforged.bus.api.Event
 import java.util.function.Function
 import kotlin.jvm.optionals.getOrNull
 
+/**
+ * 機械レシピが再読み込みされたときに呼び出されるイベント
+ * @see [HTRecipeType.reloadCache]
+ */
 class HTMachineRecipesUpdatedEvent(
     provider: HolderLookup.Provider,
     private val currentType: HTRecipeType<*>,
     private val consumer: (RecipeHolder<out HTMachineRecipeBase>) -> Unit,
 ) : Event(),
     HolderLookup.Provider by provider {
+    /**
+     * 機械レシピを登録します
+     * @param T 登録する機械レシピのクラス
+     * @param recipeType 登録するレシピの種類
+     * @param recipeId 登録するレシピのID
+     * @param function 登録するレシピのビルダーを返すブロック
+     */
     fun <T : HTMachineRecipeBase> register(
         recipeType: HTRecipeType<T>,
         recipeId: ResourceLocation,
@@ -38,10 +49,22 @@ class HTMachineRecipesUpdatedEvent(
 
     //    Helper    //
 
+    /**
+     * 指定した[prefix]と[key]に含まれる[Holder]を返します。
+     * @return 名前空間が`ragium`, `minecraft`の順に検索し，見つからない場合は最初の値を返す
+     */
     fun getFirstHolder(prefix: HTTagPrefix, key: HTMaterialKey): Holder<Item>? = getFirstHolder(prefix.createTag(key))
 
+    /**
+     * 指定した[prefix]と[key]に含まれる[Item]を返します。
+     * @return 名前空間が`ragium`, `minecraft`の順に検索し，見つからない場合は最初の値を返す
+     */
     fun getFirstItem(prefix: HTTagPrefix, key: HTMaterialKey): Item? = getFirstHolder(prefix, key)?.value()
 
+    /**
+     * 指定した[tagKey]に含まれる[Holder]を返します。
+     * @return 名前空間が`ragium`, `minecraft`の順に検索し，見つからない場合は最初の値を返す
+     */
     fun getFirstHolder(tagKey: TagKey<Item>): Holder<Item>? {
         val holderSet: HolderSet.Named<Item> = itemLookup().get(tagKey).getOrNull() ?: return null
         // Find item from Ragium
@@ -55,5 +78,9 @@ class HTMachineRecipesUpdatedEvent(
         return firstHolder ?: holderSet.firstOrNull()
     }
 
+    /**
+     * 指定した[tagKey]に含まれる[Item]を返します。
+     * @return 名前空間が`ragium`, `minecraft`の順に検索し，見つからない場合は最初の値を返す
+     */
     fun getFirstItem(tagKey: TagKey<Item>): Item? = getFirstHolder(tagKey)?.value()
 }

src/api/kotlin/hiiragi283/ragium/api/event/HTMachineRecipesUpdatedEvent.kt

@@ -9,6 +9,9 @@ import net.minecraft.world.item.ItemStack
 import net.minecraft.world.level.ItemLike
 import net.neoforged.neoforge.common.MutableDataComponentHolder
 
+/**
+ * コンポーネント付きの[ItemStack]のインスタンスを作るビルダー
+ */
 class HTItemStackBuilder : MutableDataComponentHolder {
     private val stack: ItemStack
 

src/api/kotlin/hiiragi283/ragium/api/item/HTItemStackBuilder.kt

@@ -10,6 +10,9 @@ import net.minecraft.world.item.enchantment.ItemEnchantments
 import net.neoforged.neoforge.common.extensions.IItemExtension
 import kotlin.math.max
 
+/**
+ * 単一の[Enchantment]を常に返す[IItemExtension]
+ */
 interface HTSingleEnchantmentAwareItem : IItemExtension {
     val targetEnchantment: ResourceKey<Enchantment>
     val targetLevel: Int

src/api/kotlin/hiiragi283/ragium/api/item/HTSingleEnchantmentAwareItem.kt

@@ -39,6 +39,10 @@ class HTRecipeType<T : HTMachineRecipeBase>(val machine: HTMachineType, val seri
     private var lastRecipe: ResourceLocation? = null
     private var changed: Boolean = true
 
+    /**
+     * 指定した[input]と[level]から最初に一致するレシピを返します。
+     * @return 見つからなかった場合は[Result.failure]
+     */
     fun getFirstRecipe(input: HTMachineRecipeInput, level: Level): Result<T> {
         var firstRecipe: RecipeHolder<T>? = null
         // Check cache update
@@ -62,14 +66,23 @@ class HTRecipeType<T : HTMachineRecipeBase>(val machine: HTMachineType, val seri
             }
     }
 
+    /**
+     * キャッシュされたレシピの一覧を返します。
+     */
     fun getAllRecipes(): List<RecipeHolder<T>> = recipeCache.values.toList()
 
     //    Cache    //
 
+    /**
+     * レシピを更新するフラグを立てます。
+     */
     fun setChanged() {
         changed = true
     }
 
+    /**
+     * レシピを現在のサーバに基づいて更新します。
+     */
     fun reloadCache() {
         if (changed && RagiumAPI.getInstance().getCurrentSide().isServer) {
             RagiumAPI
@@ -81,6 +94,9 @@ class HTRecipeType<T : HTMachineRecipeBase>(val machine: HTMachineType, val seri
         }
     }
 
+    /**
+     * 指定した[manager]からレシピを更新します。
+     */
     @Suppress("UNCHECKED_CAST")
     fun reloadCache(manager: RecipeManager) {
         lastRecipe = null