HUDCachingEarlyReturnTransformer

基本信息

属性	值
类名	`com.gtnewhorizons.angelicacompat.asm.transformers.generic.HUDCachingEarlyReturnTransformer`
实现接口	`net.minecraft.launchwrapper.IClassTransformer`
数据源	`CompatRegistry.INSTANCE.getHudCachingEarlyReturns()`
触发条件	`AngelicaConfig.enableHudCaching == true` 且 `Side.CLIENT`
注册枚举	`AsmTransformers.HUDCACHING_EARLY_RETURN`
启用版本	Minecraft 1.7.10（仅客户端）

功能

Angelica 的 HUDCaching 在玩家 HUD 完全静止（视角/手持物/状态效果均无变化）时让 renderGameOverlay 整体早退，避免每帧重新渲染坐标、Buff 图标、Thaumcraft 的 Aspects 文本等。下游 mod 的 renderOverlay 方法不会被 Angelica 自动调用——它们仍然每帧运行，浪费 CPU。

HUDCachingEarlyReturnTransformer 在补丁目标方法的最前插入 Angelica 的 shouldReturnEarly() 检查，命中缓存时立即按方法返回类型返回：

public void renderOverlay(...) {     // 或 boolean / int
    if (HUDCaching.shouldReturnEarly()) {
        return;                       // 或 return false / 0
    }
    // ... 原方法体 ...
}

注入算法

找到目标方法体 method.instructions。
在最前插入：
- INVOKESTATIC com/gtnewhorizons/angelica/hudcaching/HUDCaching$HUDCachingHooks.shouldReturnEarly()Z
- IFEQ exitLabel
按方法返回类型分支：
- 返回 boolean（... Z）→ ICONST_0 + IRETURN
- 返回 int（... I）→ ICONST_0 + IRETURN
- 返回 void（... V）→ RETURN
- 其它返回类型（J/F/D/L/[...）→ 日志 WARN “Unknown return type”，跳过改写返回原字节码（return basicClass）
紧跟其后追加 exitLabel: 让原方法体继续。

字节码示意

返回类型	入口注入
`void`	`INVOKESTATIC shouldReturnEarly` → `IFEQ exitLabel` → `RETURN` → `exitLabel:`
`boolean`/`int`	`INVOKESTATIC shouldReturnEarly` → `IFEQ exitLabel` → `ICONST_0` → `IRETURN` → `exitLabel:`

补丁覆盖（默认）

thaumcraft.client.lib.RenderEventHandler#renderOverlay（由 ThaumcraftCompatHandler 注册）
com.kentington.thaumichorizons.client.lib.RenderEventHandler#renderOverlay（由 ThaumicHorizonsCompatHandler 注册）

ClassWriter 标志

COMPUTE_FRAMES：必需。

输出与调试

注入日志：

[AngelicaTweaker] Injecting HUDCaching Conditional Return: <className>#<methodName>

未知返回类型警告日志：

[AngelicaTweaker] HUDCaching Conditional Return - Unknown return type: <className>#<methodName>:<desc>

详见 AngelicaCompatCore — 当 AngelicaCompatCore.DUMP_CLASSES() 为 true 时写出改写前后字节码。

数值

数值	默认	含义
数据来源	`CompatRegistry.getHudCachingEarlyReturns()`	运行时由 CompatHandler 注册
默认目标方法数	2（Thaumcraft + ThaumicHorizons）	`RenderEventHandler#renderOverlay` 各一次
触发开关	`AngelicaConfig.enableHudCaching`	仅 HUD 缓存启用时装载

限制

只支持 void / boolean / int 返回类型；其他返回类型会被跳过并 WARN（不抛错）。
shouldReturnEarly() 是黑盒检查：调用方 mod 自行决定哪些状态触发缓存命中；本 transformer 仅在被调用时信任该返回值。
renderOverlay 以外的命名/签名（例如 mod 自定义 onRenderTick）需要单独注册。

第三方 mod 集成

通用 transformer，依赖 CompatRegistry 运行时填充。当前内置 Thaumcraft + ThaumicHorizons 两个兼容目标。