ItemStackReplacementManager
基本信息
| 属性 | 值 |
|---|---|
| 完整类名 | com.gtnewhorizons.postea.api.ItemStackReplacementManager |
| 包路径 | api |
| 类型 | 公共 API 注册表（abstract class, 不允许实例化） |
| 调用时机 | FMLPostInitializationEvent 或 FMLLoadCompleteEvent 之后 |
| 触发条件 | 任何 NBT 被反序列化为 ItemStack 时（带 "id" 字段） |
功能
Postea 的核心 API 之一。在 ItemStack NBT 反序列化的瞬间拦截它，对其执行复杂转换或简单替换。与 BlockReplacementManager 对称，但作用于物品/物品堆叠而非方块。
与
BlockReplacementManager不同：本 API 不依赖世界加载，在 NBT 解析的任何位置（包括 TileEntity 内、玩家物品栏、容器 NBT 等）都会触发。
方法
自定义转换注册
| 方法 | 说明 |
|---|---|
addTransformationHandler(String originalId, IItemStackTransformationHandler transformer) |
注册复杂 ItemStack 转换器，返回 false 表示不识别 |
回调签名：boolean apply(String originalId, NBTTagCompound stack)。返回 true 阻止后续 handler 执行。
ID 解析注册
| 方法 | 说明 |
|---|---|
registerIDResolver(String originalId, Consumer<Integer> resolver) |
注册回调，缓存 namespaced ID → 数值 ID 的映射 |
Missing Mapping 替换
| 方法 | 说明 |
|---|---|
replaceMissingMapping(String originalId, Item item) |
旧 ID 在 FML 检测缺失时直接重映射为目标 Item |
ignoreMissingMapping(String originalId) |
抑制 FML 对该 ID 的缺失警告 |
Simple Replacement（O(1) 执行）
| 方法签名 | 源 → 目标 | 行为 |
|---|---|---|
addSimpleReplacement(String, Item) |
item → item | 保留 damage |
addSimpleReplacement(String, Item, boolean skipBlockRemap) |
同上 | 可选跳过 Block 镜像 |
addSimpleReplacement(String, Item, int newMeta) |
item → item+meta | newMeta 可用 WILDCARD_VALUE 保留 |
addSimpleReplacement(String, Item, int newMeta, boolean) |
同上 | 可选跳过 Block 镜像 |
addSimpleReplacement(String, ItemStack) |
item → stack | 不复制 NBT，只换 ID + damage |
addSimpleReplacement(String, ItemStack, boolean) |
同上 | 可选跳过 Block 镜像 |
addSimpleReplacement(String, int origMeta, Item) |
item+meta → item | origMeta 可用 WILDCARD_VALUE |
addSimpleReplacement(String, int origMeta, Item, boolean) |
同上 | 可选跳过 Block 镜像 |
addSimpleReplacement(String, int origMeta, ItemStack) |
item+meta → stack | 不复制 NBT |
addSimpleReplacement(String, int origMeta, ItemStack, boolean) |
同上 | 可选跳过 Block 镜像 |
addSimpleReplacement(String, int origMeta, Item, int newMeta) |
item+meta → item+meta | 两 meta 都可用 WILDCARD_VALUE |
addSimpleReplacement(String, int origMeta, Item, int newMeta, boolean) |
同上 | 完整控制 |
WILDCARD_VALUE 语义：源侧 32767 = meta-specific 回退；目标侧 32767 = 保留原值。
自动镜像：当 Item 是 ItemBlock 时，Postea 会自动注册对应的 Block 转换器；传
skipBlockRemap = true禁用。
NBT 不复制：以
ItemStack为目标的简单替换只替换 ID 与 damage，原 NBT 数据全部丢弃。
性能特征
- Simple replacements 使用
SimpleTransformationMap，对同一 ID 注册 N 条规则时执行时间仍为 O(1)。 - 不做 chunk 缓存：每次 NBT 反序列化都会调用（用于纯 NBT 转换的写回）。
使用示例
// 简单替换：把"oldmod:ruby"全部换成 minecraft:diamond
ItemStackReplacementManager.addSimpleReplacement("oldmod:ruby", Items.diamond);
// 仅替换特定 meta 的 item+meta → item+meta
ItemStackReplacementManager.addSimpleReplacement("oldmod:ruby", 1, Items.emerald, 0);
// 复杂转换：自定义 NBT 调整（如修改 tag）
ItemStackReplacementManager.addTransformationHandler("oldmod:specialTool", (origId, tag) -> {
if (!tag.hasKey("CustomData")) return false;
tag.setString("MigratedFrom", origId);
return true;
});
// 缓存数值 ID 用于复杂转换的快速比对
ItemStackReplacementManager.registerIDResolver("minecraft:diamond", id -> MyMod.diamondId = id);
第三方 mod 集成
- 依赖：
required-after:gtnhlib@[0.6.21,)。 - 复杂转换应优先用
IDRegistry.registerItemIDResolver缓存数值 ID；string ID 在 handler 中可直接用，无需 resolve。