- Implement parallel recipe process.

- Improve container access performance.
- Update documents.

Author: KasumiNova

docs/API.md

@@ -41,3 +41,19 @@ JEI/HEI 集成不属于 `PrototypeMachineryAPI` 的统一入口（它是典型
 详见：
 
 - [生命周期与加载顺序](./Lifecycle.md)
+
+## Key-level IO（基于 PMKey 的结构 IO）
+
+PrototypeMachinery 的结构 IO（Structure IO）在内部已统一迁移为 **key-level**：
+
+- 使用 `PMKey<T>` + `Long` 数量作为核心语义
+- 扫描（parallelism 计算）与执行期复用同一套 key 匹配规则
+- 对外 capability（`IItemHandler` / `IFluidHandler`）仅作为边界适配层（因其 `Int` 限制会做分块/限幅）
+
+接口位置：
+
+- `src/main/kotlin/api/machine/component/container/StructureKeyContainers.kt`
+
+文档与迁移说明：
+
+- [Key-level IO（基于 PMKey 的 IO）](./KeyLevelIO.md)

docs/KeyLevelIO.md

@@ -0,0 +1,72 @@
+# Key-level IO（基于 PMKey 的 IO）
+
+本项目的结构 IO（Structure IO）在内部已统一迁移为 **key-level** 交互：以 `PMKey<T>` + `Long` 数量作为核心数据模型，而不是频繁构造/比较 `ItemStack` / `FluidStack`。
+
+This document describes the **key-level** IO model used internally by PrototypeMachinery: `PMKey<T>` + `Long` counts, instead of stack-level `ItemStack` / `FluidStack` churn.
+
+## 目标 / Goals
+
+- **性能**：减少 `ItemStack`/`FluidStack` 的构造、复制与 NBT 比较。
+- **一致性**：扫描（parallelism 计算）与执行期使用同一套 key 语义，避免“扫描忽略 tag / 执行考虑 tag”这类偏差。
+- **可扩展**：Addon 可以面向稳定的 key-level API 实现自定义容器/存储。
+
+## API 位置 / Where is the API
+
+相关接口位于：
+
+- `src/main/kotlin/api/machine/component/container/StructureKeyContainers.kt`
+
+主要接口：
+
+- `StructureItemKeyContainer`
+- `StructureFluidKeyContainer`
+
+它们是 **结构组件（StructureComponent）** 层级的容器视图：在结构成型/刷新时由结构解析生成，并存放在 `StructureComponentMap` 中。
+
+## 基本语义 / Core semantics
+
+### 以 Key + Long 为准
+
+- Item：`PMKey<ItemStack>` + `Long`（数量）
+- Fluid：`PMKey<FluidStack>` + `Long`（mB 等计量）
+
+这些接口提供形如：
+
+- `insert(key, amount, action): Long`
+- `extract(key, amount, action): Long`
+
+返回值为**实际插入/提取的数量**（`Long`）。
+
+### Action（EXECUTE / SIMULATE）
+
+- `Action.SIMULATE`：只测算能插入/提取多少，不产生实际副作用。
+- `Action.EXECUTE`：真实执行。
+
+注意：扫描并行约束一般使用 `SIMULATE`；配方执行使用 `EXECUTE`。
+
+## unchecked 方法（rollback 专用）
+
+接口同时提供 unchecked 版本（命名可能为 `insertUnchecked` / `extractUnchecked`）：
+
+- 设计目的：**事务 rollback** 时恢复容器状态。
+- 语义：忽略 IOType（输入/输出）限制等“外部规则”，只做“把状态恢复回去”这件事。
+
+重要：unchecked 不是给普通逻辑“绕过规则”用的。
+
+## capability（Forge IItemHandler/IFluidHandler）适配策略
+
+内部以 `Long` 计数运算，但 Forge capability 通常是 `Int` 数量（例如 `ItemStack.count`、`IFluidHandler.fill/drain`）。因此 cap-backed 容器需要在边界做分块/限幅：
+
+- 统一采用 `Int.MAX_VALUE / 2` 作为安全上限（避免溢出、也避免某些实现对极端值的未定义行为）。
+- 大于该上限的插入/提取会被拆分为多个 chunk 循环完成。
+
+这意味着：
+
+- **对外 cap 只是兼容层**；如果你需要真正的大数与零分配语义，请使用 storage-backed（key-level storage）实现。
+
+## 推荐用法 / Recommended usage
+
+- 扫描/并行约束：只使用 `insert/extract(..., SIMULATE)`，不要 materialize stack。
+- 执行/事务：
+  - commit 阶段用 `insert/extract(..., EXECUTE)`
+  - rollback 阶段用 `insertUnchecked/extractUnchecked`（同样建议 EXECUTE）

src/main/kotlin/PrototypeMachinery.kt

@@ -8,6 +8,7 @@ import github.kasuminova.prototypemachinery.common.network.NetworkHandler
 import github.kasuminova.prototypemachinery.common.registry.MachineTypeRegisterer
 import github.kasuminova.prototypemachinery.common.structure.loader.StructureLoader
 import github.kasuminova.prototypemachinery.impl.recipe.index.RecipeIndexRegistry
+import github.kasuminova.prototypemachinery.impl.recipe.scanning.DefaultRecipeParallelismConstraints
 import github.kasuminova.prototypemachinery.impl.scheduler.TaskSchedulerImpl
 import github.kasuminova.prototypemachinery.integration.crafttweaker.CraftTweakerExamples
 import net.minecraftforge.common.MinecraftForge
@@ -55,6 +56,9 @@ public object PrototypeMachinery {
 
         NetworkHandler.init()
 
+        // Register scan-time parallelism constraints (pluggable extension point for addons).
+        DefaultRecipeParallelismConstraints.registerAll()
+
         // Register scheduler to event bus
         // 注册调度器到事件总线
         MinecraftForge.EVENT_BUS.register(TaskSchedulerImpl)

src/main/kotlin/api/machine/component/container/StructureKeyContainers.kt

@@ -0,0 +1,56 @@
+package github.kasuminova.prototypemachinery.api.machine.component.container
+
+import github.kasuminova.prototypemachinery.api.key.PMKey
+import github.kasuminova.prototypemachinery.api.machine.component.StructureComponent
+import github.kasuminova.prototypemachinery.common.util.Action
+import github.kasuminova.prototypemachinery.common.util.IOType
+import net.minecraft.item.ItemStack
+import net.minecraftforge.fluids.FluidStack
+
+/**
+ * Key-level container view for items.
+ *
+ * This is the preferred API for recipe IO and scanning.
+ *
+ * - No ItemStack predicate matching
+ * - No per-slot snapshot/restore requirements
+ * - All amounts are Long
+ */
+public interface StructureItemKeyContainer : StructureComponent {
+
+    public fun isAllowedIOType(ioType: IOType): Boolean
+
+    /** Inserts up to [amount] of [key]. Returns the amount actually inserted. */
+    public fun insert(key: PMKey<ItemStack>, amount: Long, action: Action): Long
+
+    /** Extracts up to [amount] of [key]. Returns the amount actually extracted. */
+    public fun extract(key: PMKey<ItemStack>, amount: Long, action: Action): Long
+
+    /** Unchecked variant that ignores IOType restrictions (for rollback). */
+    public fun insertUnchecked(key: PMKey<ItemStack>, amount: Long, action: Action): Long
+
+    /** Unchecked variant that ignores IOType restrictions (for rollback). */
+    public fun extractUnchecked(key: PMKey<ItemStack>, amount: Long, action: Action): Long
+}
+
+/**
+ * Key-level container view for fluids.
+ *
+ * NOTE: fluid key equality decides whether NBT/tag participates.
+ */
+public interface StructureFluidKeyContainer : StructureComponent {
+
+    public fun isAllowedIOType(ioType: IOType): Boolean
+
+    /** Inserts up to [amount] of [key]. Returns the amount actually inserted. */
+    public fun insert(key: PMKey<FluidStack>, amount: Long, action: Action): Long
+
+    /** Extracts up to [amount] of [key]. Returns the amount actually extracted. */
+    public fun extract(key: PMKey<FluidStack>, amount: Long, action: Action): Long
+
+    /** Unchecked variant that ignores IOType restrictions (for rollback). */
+    public fun insertUnchecked(key: PMKey<FluidStack>, amount: Long, action: Action): Long
+
+    /** Unchecked variant that ignores IOType restrictions (for rollback). */
+    public fun extractUnchecked(key: PMKey<FluidStack>, amount: Long, action: Action): Long
+}

src/main/kotlin/api/recipe/requirement/component/system/RecipeRequirementSystem.kt

@@ -120,6 +120,20 @@ public interface RecipeRequirementSystem<C : RecipeRequirementComponent> {
  */
 public interface RequirementTransaction {
 
+    /**
+     * A shared no-op success transaction instance.
+     *
+     * 通用的“成功且无副作用”的事务单例，用于避免在各处反复构造匿名对象。
+     *
+     * - result = [ProcessResult.Success]
+     * - commit()/rollback() 均为 no-op
+     */
+    public object NoOpSuccess : RequirementTransaction {
+        override val result: ProcessResult = ProcessResult.Success
+        override fun commit() {}
+        override fun rollback() {}
+    }
+
     /** Result of attempting to acquire the transaction / 获取事务的结果 */
     public val result: ProcessResult
 

src/main/kotlin/api/recipe/scanning/RecipeParallelismConstraint.kt

@@ -0,0 +1,50 @@
+package github.kasuminova.prototypemachinery.api.recipe.scanning
+
+import github.kasuminova.prototypemachinery.api.machine.MachineInstance
+import github.kasuminova.prototypemachinery.api.recipe.MachineRecipe
+import github.kasuminova.prototypemachinery.api.recipe.requirement.component.RecipeRequirementComponent
+import net.minecraft.util.ResourceLocation
+
+/**
+ * A pluggable constraint used by the recipe scanning system to decide whether a recipe can run with a given
+ * effective parallel amount `k`.
+ *
+ * 用于“配方扫描阶段”计算最大可并行数 k 的可插拔约束。
+ *
+ * ### Design notes
+ * - The scanning system will binary-search k in [1..limit].
+ * - Each constraint decides whether the machine state can satisfy the requirement(s) at that k, typically via
+ *   Action.SIMULATE.
+ * - If a requirement type has no registered constraint, the scanner will conservatively clamp k to 1.
+ */
+public interface RecipeParallelismConstraint {
+
+    /** Requirement type id this constraint applies to. / 约束对应的需求类型 ID */
+    public val requirementTypeId: ResourceLocation
+
+    /**
+     * Optional fast upper bound estimation.
+     *
+     * You may return a value <= currentLimit to reduce the binary search space.
+     *
+     * 可选的上界估算：用于快速收敛二分范围。
+     */
+    public fun upperBound(
+        machine: MachineInstance,
+        recipe: MachineRecipe,
+        components: List<RecipeRequirementComponent>,
+        currentLimit: Int
+    ): Int = currentLimit
+
+    /**
+     * Whether the machine can satisfy the given requirement components at the specified parallel amount.
+     *
+     * Return false to indicate the scanner should try a smaller k.
+     */
+    public fun canSatisfy(
+        machine: MachineInstance,
+        recipe: MachineRecipe,
+        components: List<RecipeRequirementComponent>,
+        parallels: Int
+    ): Boolean
+}

src/main/kotlin/api/recipe/scanning/RecipeParallelismConstraintRegistry.kt

@@ -0,0 +1,34 @@
+package github.kasuminova.prototypemachinery.api.recipe.scanning
+
+import net.minecraft.util.ResourceLocation
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Registry for [RecipeParallelismConstraint].
+ *
+ * 配方并行可行性约束注册表。
+ *
+ * This is intentionally minimal:
+ * - The core mod registers default constraints for built-in requirement types.
+ * - Addons can register constraints for their custom requirement types to participate in scan-time parallelism.
+ */
+public object RecipeParallelismConstraintRegistry {
+
+    private val constraints: MutableMap<ResourceLocation, RecipeParallelismConstraint> = ConcurrentHashMap()
+
+    @JvmStatic
+    public fun register(constraint: RecipeParallelismConstraint): RecipeParallelismConstraint {
+        constraints[constraint.requirementTypeId] = constraint
+        return constraint
+    }
+
+    @JvmStatic
+    public fun get(requirementTypeId: ResourceLocation): RecipeParallelismConstraint? {
+        return constraints[requirementTypeId]
+    }
+
+    @JvmStatic
+    public fun all(): Collection<RecipeParallelismConstraint> {
+        return constraints.values
+    }
+}

src/main/kotlin/common/util/RecipeParallelism.kt

@@ -0,0 +1,40 @@
+package github.kasuminova.prototypemachinery.common.util
+
+import github.kasuminova.prototypemachinery.api.machine.attribute.StandardMachineAttributes
+import github.kasuminova.prototypemachinery.api.recipe.process.RecipeProcess
+import kotlin.math.floor
+
+/**
+ * Utilities for recipe parallelism.
+ *
+ * IMPORTANT:
+ * - We treat PROCESS_PARALLELISM on the process attribute map as the **effective** parallel amount
+ *   for this specific process instance.
+ * - The value is floored to an integer and clamped to >= 1.
+ */
+public object RecipeParallelism {
+
+    public fun getParallelism(process: RecipeProcess): Int {
+        val raw = process.attributeMap.attributes[StandardMachineAttributes.PROCESS_PARALLELISM]?.value ?: 1.0
+        if (raw.isNaN() || raw.isInfinite()) return 1
+        return floor(raw).toInt().coerceAtLeast(1)
+    }
+
+    /**
+     * Scales a non-negative [base] by integer [k] with overflow protection.
+     *
+     * If overflow would occur, this returns [Long.MAX_VALUE] (saturating arithmetic).
+     */
+    public fun scaleCount(base: Long, k: Int): Long {
+        if (base <= 0L) return base
+        if (k <= 1) return base
+        if (base > Long.MAX_VALUE / k.toLong()) return Long.MAX_VALUE
+        return base * k.toLong()
+    }
+}
+
+/** Shortcut extension: effective parallels for this process (>= 1). */
+public fun RecipeProcess.parallelism(): Int = RecipeParallelism.getParallelism(this)
+
+/** Shortcut extension: scale count by this process's parallelism. */
+public fun RecipeProcess.scaleByParallelism(base: Long): Long = RecipeParallelism.scaleCount(base, parallelism())