物品栈与传输 API

基本信息

属性 值
包 com.gtnewhorizon.gtnhlib.item（22 个类）
源码 src/main/java/com/gtnewhorizon/gtnhlib/item/
核心接口 ImmutableItemStack、ItemSource、ItemSink、InventoryIterator
传输引擎 com.gtnewhorizon.gtnhlib.item.ItemTransfer
外部依赖 MineFactory Reloaded（item/impl/mfr/ 3 个类，compileOnly）

功能

README 的 Items 节（README.md）：

  • ImmutableItemStack wraps a stack as read-only to prevent accidental mutation.
  • ItemTransfer moves items between an ItemSource and an ItemSink with predicate filters and count limits.
  • Walk any IInventory with InventoryIterator, including sided slots.
  • The source and sink interfaces abstract pulling and pushing so transfer logic works across any inventory type.

ImmutableItemStack

item/ImmutableItemStack.java:15 是接口（extends ImmutableItemMeta），不是类。用途是把 ItemStack 以只读视图暴露，防止下游逻辑意外改动源栈。

配套的只读元数据视图：

类型 角色
ImmutableItemStack 物品 + 数量的只读视图
ImmutableItemMeta 物品 + meta 的只读视图
InsertionItemStack 插入操作中携带的可写包装

ItemTransfer

item/ItemTransfer.java:20，实例方法式的构建器（不是静态工具类）。典型链式用法：

new ItemTransfer()
    .source(...)
    .sink(...)
    .setSourceSlots(...)
    .setSinkSlots(...)
    .transfer();
方法 作用
source(ItemSource) / source(Object, ForgeDirection) 设源
sink(ItemSink) / sink(Object, ForgeDirection) 设汇
push(Coord, ForgeDirection) / push(Object, ForgeDirection, Object) 推送
pull(Coord, ForgeDirection) / pull(Object, ForgeDirection, Object) 拉取
dropItems(World, IBlockPos) / dropItems(Coord, ForgeDirection) 掉落
setSourceSlots(int...) / setSinkSlots(int...) 限定槽位
transfer() 执行传输

push / pull / dropItems 的泛型上界为 <Coord extends IBlockPos & IWorldReferent>，即同时实现 IBlockPos 与 IWorldReferent 的对象（如方块、TileEntity）可免去解包。

源与汇的抽象

类 角色
ItemSource / ItemSink 接口
SimpleItemSource / SimpleItemSink 抽象基类，实现槽位限制与重置
InventoryItemSource / InventoryItemSink IInventory 实现，InventoryItemSink 带 setSlotStackLimit(int)
WrappedItemIO 包装既有 IO
SimpleItemIO 轻量实现
DroppingItemSink 把物品丢到世界

SimpleItemSource.pull 接受两个可空参数（ItemStackPredicate filter、ItemStack2IntFunction amount），二者均传 null 表示不过滤、不限量 —— 过滤与限量由调用方通过函数式接口注入。

遍历

类 作用
InventoryIterator 遍历接口
AbstractInventoryIterator 抽象基类
StandardInventoryIterator 标准实现
ItemStackPredicate 物品匹配谓词
ItemStack2IntFunction 数量计算函数
ItemStackNBT NBT 工具
FastImmutableItemStack 快速实现

数值

数值名 值
item 包类数 22
ItemTransfer 公开方法 13
ItemTransfer 中 push/pull/dropItems 泛型重载 各 2（带 Coord 与 Object）
item/impl/ 子包类数 5（ItemDuctSink + mfr/ 下 4 个 DSU 类）

item/impl/ 下共 5 个文件：ItemDuctSink.java 与 mfr/ 目录中的 4 个 DSU 类（DSUInventoryIterator、DSUItemIO、DSUItemSink、DSUItemSource）。MineFactory Reloaded 相关代码是唯一带外部 mod 依赖的 item 子包，由 dependencies.gradle 中 compileOnly(rfg.deobf('curse.maven:minefactory-reloaded-66672:2366150')) 支撑；GTNHLib.isMFRLoaded 为 false 时不可用。

交互

InventoryItemSink 直接持有 IInventory 与 ForgeDirection：

public final IInventory inv;
public InventoryItemSink(IInventory inv, ForgeDirection side) { ... }

因此面向侧的槽位映射由 side 决定，simulatedSinkIterator() 用于模拟查询（返回 null 表示不支持模拟）。

相关条目