BlockReplacementManager

基本信息

属性 值
完整类名 com.gtnewhorizons.postea.api.BlockReplacementManager
包路径 api
类型 公共 API 注册表（abstract class, 不允许实例化）
调用时机 FMLPostInitializationEvent 或 FMLLoadCompleteEvent 之后
关联事件 ChunkEvent.Load

功能

Postea 的核心 API 之一。在世界区块加载阶段拦截普通 Block（非 TileEntity），对其执行复杂转换或简单替换。注册到同一 ID 的多个 handler 按顺序执行，任一返回 true 即终止。

Block transformers 在 TileEntity transformers 之后执行；当 TileEntity 已将位置替换为 Block 时，Block transformers 仍会作用于该 Block（见 BlockAccessCompat 章节）。

方法

自定义转换注册

方法 说明
addTransformationHandler(String originalId, IBlockTransformationHandler transformer) 注册复杂 Block 转换器，返回 false 表示不识别，继续执行后续 handler

ID 解析注册

方法 说明
registerIDResolver(String originalId, Consumer<Integer> resolver) 注册回调，在世界首次加载时获得给定 namespaced ID 对应的数值 ID；若该 ID 从未存在则返回 -1

Missing Mapping 替换（FML 缺失 ID 重映射）

方法 说明
replaceMissingMapping(String originalId, Block block) 旧 ID 在 FML 检测缺失时直接重映射为目标 Block
ignoreMissingMapping(String originalId) 抑制 FML 对该 ID 的缺失警告

Simple Replacement（简单重映射，常数时间）

方法签名 源 → 目标 行为
addSimpleReplacement(String, Block) block → block 保留 meta
addSimpleReplacement(String, Block, boolean skipStackRemap) 同上 可选跳过 ItemStack 镜像
addSimpleReplacement(String, int meta, Block) block+meta → block 源 meta 可用 WILDCARD_VALUE
addSimpleReplacement(String, int meta, Block, boolean) 同上 可选跳过 ItemStack 镜像
addSimpleReplacement(String, Block, int newMeta) block → block+meta 目标 meta 可用 WILDCARD_VALUE 保留原值
addSimpleReplacement(String, Block, int newMeta, boolean) 同上 可选跳过 ItemStack 镜像
addSimpleReplacement(String, int origMeta, Block, int newMeta) block+meta → block+meta 两个 meta 都可用 WILDCARD_VALUE
addSimpleReplacement(String, int origMeta, Block, int newMeta, boolean) 同上 完整控制

WILDCARD_VALUE 语义：

  • 源侧（originalMeta = 32767）：作为 meta-specific handler 的回退，在没有更精确匹配时使用。
  • 目标侧（newMeta = 32767）：保留原 meta 值，不覆盖。

自动镜像：当 Block 是 ItemBlock 时，Postea 会自动注册对应的 ItemStack 转换器；传 skipStackRemap = true 禁用。

性能特征

  • Simple replacements 使用 SimpleTransformationMap 实现，对同一 ID 注册 N 条规则时执行时间仍为 O(1)。
  • TileEntity / Block transformers 只在每个区块加载时执行一次，结果会被 chunk NBT 的 POSTEA_UPDATE_CODE 哈希缓存；dev 环境下缓存禁用以便调试。

使用示例

// 简单替换：把"othermod:oreCopper"的所有 meta 替换为 vanilla dirt
BlockReplacementManager.addSimpleReplacement("othermod:oreCopper", Blocks.dirt);

// 带 meta 的精确替换：meta=0 替换为 stone，meta=1 替换为 iron_block
BlockReplacementManager.addSimpleReplacement("othermod:ore", 0, Blocks.stone);
BlockReplacementManager.addSimpleReplacement("othermod:ore", 1, Blocks.iron_block);

// 复杂转换：根据 meta 与上下文自定义输出
BlockReplacementManager.addTransformationHandler("othermod:ore", info -> {
    if (info.metadata == 0 && info.chunk.getBlockMetadata(info.x & 15, info.y, info.z & 15) == 5) {
        info.replacement = new BlockInfo(Blocks.diamond_ore, 0, null);
        return true;
    }
    return false;
});

// 注册 ID 解析器以备复杂转换时使用
BlockReplacementManager.registerIDResolver("othermod:ore", id -> MyMod.targetOreId = id);

第三方 mod 集成

  • 依赖：required-after:gtnhlib@[0.6.21,)。
  • 复杂转换应优先调用 IDRegistry.registerBlockIDResolver 缓存数值 ID，避免在每区块回调中做字符串匹配。

相关条目