AngelicaCompat

[!INFO] Git Commit: 8a7ef89 | Updated: 2026-09-28

AngelicaCompat 是 Angelica 渲染器的兼容性补丁集合，为依赖 ASM/字节码修改与 Mixin 的 Minecraft 1.7.10 Forge mod。它不注册任何 Block / Item / Entity / Enchantment / Dimension / Biome / Potion / Achievement / Structure / TileEntity，所有"功能"都是针对其它 mod 类方法的字节码与 Mixin 补丁：

  • 当 Angelica 的 Sodium 渲染路径、HUDCaching 缓存等启用时，下游 mod 的 ISBRH（renderWorldBlock）、getTileEntity、字段级 Tessellator、HUD overlay 等位置会出现兼容性问题；本 mod 通过 ASM transformer + 兼容处理器注册表 + Mixin 三层结构修复这些问题。
  • 支持的第三方 mod：ExtraUtilities、MineFactoryReloaded、CampfireBackport、StacksOnStacks、Thaumcraft、ThaumicHorizons、XaerosMinimap。

源码包：com.gtnewhorizons.angelicacompat，主类位于 AngelicaCompat。

ASM 转换器列表

  • FieldLevelTessellatorTransformer - 在指定方法内注入局部 Tessellator 引用并替换字段访问，避免多个外部 mod 共享同一个全局 Tessellator 实例导致的渲染污染
  • GetTileEntityNullGuardTransformer - 在 IBlockAccess.getTileEntity(...) 调用结果上插入 null 守卫，避免强转 (MyTileEntity) world.getTileEntity(...) 引发 NPE
  • HUDCachingEarlyReturnTransformer - 在指定 renderOverlay 类方法顶部调用 HUDCaching.shouldReturnEarly()，命中缓存时跳过原渲染
  • ThreadSafeISBRHAnnotationTransformer - 为指定 RenderBlocks 子类添加/替换 @ThreadSafeISBRH(perThread=...) 类级注解
  • StacksOnStacksTransformer - 针对 Stacks on Stacks 模组的特化 transformer，在 RenderTilePile 构造时初始化原先静态的 PileRender 字段，在 ClientUtils.drawQuad/drawRectangularPrism 内注入局部 Tessellator

兼容处理器列表

  • ExtraUtilsCompatHandler - 为 Extra Utilities 的 5 个 RenderBlocks 子类声明 ThreadSafeISBRH 注解配置（RenderBlockColor=false、RenderBlockConnectedTextures=true、RenderBlockConnectedTexturesEthereal=true、RenderBlockFullBright=false、RenderBlockSpike=false）
  • StacksOnStacksCompatHandler - 触发 FieldLevelTessellator、GetTileEntityNullGuard、ThreadSafeISBRHAnnotation 三种 transformer 注册 Stacks on Stacks 的 2 个客户端类；通过 extraTransformers() 启用 StacksOnStacksTransformer
  • ThaumcraftCompatHandler - 向 HUDCaching 注册 Thaumcraft 的 RenderEventHandler#renderOverlay，命中缓存时跳过 Thaumcraft 自带 HUD
  • ThaumicHorizonsCompatHandler - 向 HUDCaching 注册 ThaumicHorizons 的 RenderEventHandler#renderOverlay，命中缓存时跳过 TH 自带 HUD

Mixin 补丁列表

  • MixinEntityRenderer_Xaeros - 早期 Mixin：在 EntityRenderer.updateCameraAndRender 中 renderGameOverlay 调用前补回对 XaeroMinimapCore.beforeIngameGuiRender 的调用，补偿 GuiIngameForgeTransformer 被禁用后的丢失事件
  • MixinIconConnectedTexture - 晚期 Mixin：将 Extra Utilities 的 IconConnectedTexture 类型索引改为 ThreadLocal<Integer>，避免多线程渲染时共享可变状态
  • MixinRenderBlockConnectedTextures - 晚期 Mixin：把 RenderBlockConnectedTextures.getFakeRender() 返回值替换为实例字段 newFakeRender，打破原版静态 fakeRender 的线程不安全
  • MixinRenderBlockConnectedTexturesEthereal - 晚期 Mixin：覆写 RenderBlockConnectedTexturesEthereal.renderWorldBlock，使用实例字段 newFakeRenderEthereal 完成 Ethereal 连接的纹理渲染
  • MixinRenderBlockCampfire - 晚期 Mixin：为 Campfire Backport 的 RenderBlockCampfire 添加 @ThreadSafeISBRH(perThread=false)，并在 renderFace / drawCrossedSquaresTwoIcons 中标记动画纹理更新
  • MixinRedNetCableRenderer - 晚期 Mixin：在 MineFactory Reloaded RedNetCableRenderer.renderWorldBlock 中对 getTileEntity 返回值做 null 守卫，避免 ISBRT 异步线程下出现 NPE

设定列表

  • Mod 入口 - @Mod("angelicacompat") 主类、生命周期事件、SidedProxy、初始化的 ModStatus
  • PatchesConfig - 7 项 @Config.RequiresMcRestart 配置开关（ExtraUtils/CampfireBackport/MFR/XaerosMinimap/StacksOnStacks/Thaumcraft/ThaumicHorizons）
  • ModStatus - preInit 阶段记录的 Xaeros Minimap 加载状态位，供 Mixin 调用时判断
  • AngelicaCompatCore - FML 加载插件 + 向兼容 ASMT 注册 + 配置转换器类名数组 + 类转储开关
  • MixinCompatHackTweaker - 启动期 LaunchWrapper Tweaker：在 acceptOptions 时反射移除 Xaeros GuiIngameForgeTransformer，避免与 Angelica HUDCaching 重复写入 HUD
  • CompatRegistry - 统一的字节码转换器数据注册中心，按 (className → methodNames) 收集 CompatHandler 提供的补丁映射
  • CompatHandlers - 4 个 mod 兼容处理器的注册枚举，按 PatchesConfig 决定是否实际加载
  • AsmTransformers - 通用 ASM 转换器清单与 getTransformers() 入口，按 AngelicaConfig.enableSodium / enableHudCaching 与加载端过滤