HUDCaching（HUD 缓存）

基本信息

属性	值
类	`com.gtnewhorizons.angelica.hudcaching.HUDCaching`
路径	`src/main/java/com/gtnewhorizons/angelica/hudcaching/HUDCaching.java`
行数	244
内部类	`HUDCachingHooks`（`:239`）
mixin	`early/angelica/hudcaching/` 8 个
初始化	`ClientProxy.java:153-155`，条件 `AngelicaConfig.enableHudCaching`

原理

当 HUD 完全静止时（视角、手持物、状态效果均无变化），把 renderGameOverlay 的结果缓存进一张 SharedDepthFramebuffer，后续帧直接 blit 该纹理而不重绘。命中判定对外只暴露一个黑盒方法 HUDCaching.shouldReturnEarly()（在 HUDCachingHooks 内部类里）。

缓存失效节流

:88 与 :100 是核心节流逻辑：

if (!AngelicaConfig.hudCachingActive || mc.displayWidth < 16 || mc.displayHeight < 16) {
    // 不缓存，直接返回
}
...
nextHudRefresh = System.currentTimeMillis() + (1000 / AngelicaConfig.hudCachingFPS);

刷新间隔由 hudCachingFPS 决定。取的是整除 1000 / hudCachingFPS 毫秒 —— 当 hudCachingFPS > 1000 时这个除法会得到 0，间隔退化为 0 ms（即每帧都刷新，缓存等于失效）。hudCachingFPS 字段自带 = 20 初始值（AngelicaConfig.java:117），即默认约 50 ms 刷新一次。

缓存内容

静态字段 :38-62 记录了进入缓存时刻的各种 HUD 状态：

字段	行	内容
`framebuffer`	`:38`	`SharedDepthFramebuffer` 缓存目标
`dirty`	`:39`	是否需要重绘
`renderingCacheOverride`	`:46`	缓存渲染覆盖标志
`renderVignetteCaptured`	`:53`	暗角已捕获
`renderHelmetCaptured`	`:56`	头盔层已捕获
`renderPortalCapturedTicks`	`:57`	传送门刻
`renderCrosshairsCaptured`	`:59`	准星已捕获
`fakeTextEvent`	`:61`	合成的 `RenderGameOverlayEvent.Text`
`fakePostEvent`	`:62`	合成的 `RenderGameOverlayEvent.Post`（HELMET 元素）

两个 fake*Event 用 new RenderGameOverlayEvent(0, null, 0, 0) 构造一个空宿主事件，供下游 mod 的 renderOverlay 在缓存路径上消费，避免 NPE。

尺寸下限

:88 显式排除 displayWidth < 16 || displayHeight < 16 的情况 —— 极小窗口（最小化、分辨率异常）下 VAO 与帧缓冲不可用。

方法

方法	行	作用
`init()`	`:64`	由 `ClientProxy.init` 调用
`resetAfterCrash()`	`:68`	崩溃恢复后重置
`renderCachedHud(renderer, ingame, partialTicks, hasScreen, mouseX, mouseY)`	`:74`	主渲染入口
`fixGLStateBeforeRenderingCache()`	`:195`	渲染缓存前修复 GL 状态
`drawTexturedRect(width, height)`	`:203`	绘制缓存纹理
`rebuildVAO(width, height)`	`:216`	尺寸变化时重建 VAO
`disableHoloInventory()`	`:232`	禁用 HoloInventory 的全息物品栏

静态字段 quadVAO（:42）、quadWidth / quadHeight（:43-44）配合 rebuildVAO 使用。

三条配置

配置	位置	默认	含义
`enableHudCaching`	`AngelicaConfig.java:104`	见配置文件	总开关（`ClientProxy.java:153` 判定）
`hudCachingActive`	`AngelicaConfig.java:112`	—	运行期活跃标志（`:88` 判定）
`hudCachingFPS`	`AngelicaConfig.java:117`	`20`（字段自带初值）	刷新间隔分母
`enableHudCachingEventTransformer`	`AngelicaConfig.java:108`	—	事件层 transformer 开关

对第三方 mod 的 ASM 补丁

HUDCaching.shouldReturnEarly() 需要下游 mod 主动配合 —— 由 HUDCachingEarlyReturnTransformer（loading/fml/compat/transformers/generic/，42 行）注入。该 transformer 由 CompatHandlers 驱动，数据来自 ICompatHandler.getHUDCachingEarlyReturn()。

已确认的默认补丁目标：

目标	注册方
`thaumcraft.client.lib.RenderEventHandler#renderOverlay`	`ThaumcraftCompatHandler.java:14`
`thaumic-horizons` 对应类	`ThaumicHorizonsCompatHandler.java:15`

两者都由 CompatConfig.fixThaumcraft / fixThaumicHorizons 控制（默认 true）。装了 RFB 就拿不到这些补丁，因为兼容 transformer 只在 LaunchWrapper 路径注册 —— 见 AngelicaRfbPlugin。