Postea
[!INFO] Git Commit:
8234973| Updated: 2026-09-29
Postea 是一个面向 GTNH (1.7.10) 的运行时世界数据迁移框架（library/API 模组），不包含任何方块、物品、实体等内容。它为依赖模组提供一整套注册入口，用以在世界区块加载或物品 NBT 反序列化的瞬间拦截、改写或完全替换 TileEntity、Block、ItemStack 的内容。
适用场景
- 模组卸载后残留 ID 的批量清理。
- TileEntity NBT 字段的结构性调整（如 GregTech 旧矿石抹除、Furnace → Chest 整体迁移）。
- 物品 ID 与 damage/meta 的批量重映射（简单替换与复杂 NBT 编辑均支持）。
- FML 缺失映射（Missing Mapping）的优雅抑制或重定向。
核心特性
- TileEntity Transformers：拦截 TileEntity NBT，支持替换为 Block、纯 NBT 编辑、整体类型替换。
- Block Transformers：拦截普通 Block NBT，支持任意复杂逻辑或 O(1) 简单重映射。
- ItemStack Transformers：拦截物品 NBT 反序列化瞬间；与 Block 转换器对称。
- Simple Replacement API：基于
SimpleTransformationMap的 O(1) 批量替换，无可感知的性能开销。 - Missing Mapping Replacement API：统一的 FML 缺失 ID 处理入口（重映射 / 抑制）。
- Numeric ID Identification for Removed Content：识别已被 Forge 当作 Air 的"已删除 ID"，无需注册 dummy Block。
跨 mod 兼容性
通过反射检测以下依赖并自动启用对应后端：
| 依赖 mod | 作用 |
|---|---|
gtnhlib |
Postea 的硬依赖（required-after:gtnhlib@[0.6.21,)） |
EndlessIDs |
识别 32k+ ID 空间的方块 / 物品 |
NotEnoughIDs (NEID) |
同上，兼容 NEID 内部存储 |
API 列表
| API | 用途 |
|---|---|
| TileEntityReplacementManager | 注册 TileEntity 转换器（替换 / NBT 编辑 / 整体迁移） |
| BlockReplacementManager | 注册 Block 转换器、ID Resolver、Simple Replacement、Missing Mapping |
| ItemStackReplacementManager | 注册 ItemStack 转换器、ID Resolver、Simple Replacement、Missing Mapping |
| PosteaBlockStackTransformer | 声明式转换器基类：子类实现接口后调用 register() 自动分发 |
| BlockAccessCompat | 在 TileEntity 转换器中安全读取原方块 ID 与 meta |
| IDExtenderCompat | 读写 ItemStack NBT 的 ID 字段，兼容 EndlessIDs / NEID |
| MissingMappingHandler | FML FMLMissingMappingsEvent 监听与处理（utility 层） |
执行顺序
当世界加载一个区块时，Postea 按以下顺序执行：
- TileEntity Transformers（按注册顺序，可返回 null 让后续 handler 接手）
- Block Transformers（针对上一步未处理的方块 + 普通 Block）
- Simple Transformations（O(1) 映射表）
ItemStack Transformers 在任何 NBT 反序列化为 ItemStack 时独立触发，不依赖区块加载。
触发事件
| 事件 | 触发点 |
|---|---|
FMLPostInitializationEvent |
推荐调用 API 注册转换器的位置 |
FMLLoadCompleteEvent |
SimpleTransformationRegistry 的最终初始化 |
FMLModIdMappingEvent |
ID 重新映射后刷新转换器缓存 |
FMLMissingMappingsEvent |
MissingMappingHandler 处理缺失 ID |
ChunkEvent.Load |
ChunkFixerUtility 对已加载区块执行转换 |
第三方 mod 集成
本模组不调用任何第三方 mod 的 API（除通过反射检测 EndlessIDs / NEID 是否存在）；它提供 API 给其他 mod 使用。集成方需在自家模组的 FMLPostInitializationEvent 或更晚阶段调用上述 API。