星火 2.0 开发文档

主题

旧客户端专用的图片缓存预算 ​

部分旧客户端可能在 Canvas 图片回收、重载后出现纹理登记失效，表现为部分图片或物品图标批量变白，而文字和其他图片仍正常。临时提高 UI 图片缓存预算可以减少回收和重载机会，不能修复底层缺陷，也不能保证长时间游玩不再触发。

这是按症状选用的兼容措施。新项目、没有相符问题的项目，以及已经确认包含客户端修复的版本，不应默认加入此配置。

先确认适用范围 ​

  • 重点检查使用 Canvas.DrawImage / CanvasAnimated 的图片，尤其是频繁切地图、加载大量场景图和物品图的项目。
  • 对齐发生问题的游戏局、平台、客户端二进制版本及图片路径。文件缺失、下载失败、图片路径错误、GPU 设备丢失或内存不足，需要先处理对应错误；白图本身不能证明是缓存问题。
  • GameCore.ResourceType.Image 保存的是资源路径，缓存这个值不等于持有 GPU 纹理。
  • 本规避方案使用既有 GameGraph.ResourceSystem.ResourceCache.SetMemoryBudget API。已核对 Windows 客户端 176 的对应接口存在；这不表示所有更老版本或其他平台版本号都支持它。先确认项目 SDK 可编译且目标客户端支持此 API，不自行添加底层导入绕过版本限制。
  • 不把 CapabilityVersion == 4 或 BinaryVersion <= 176 当成受影响版本判断。客户端缺陷修复不一定提升能力版本，不同平台的二进制版本也不能直接比较。修复版本尚未确认时，保留显式的项目临时配置和测试记录，不编造版本门槛。

最小项目改动 ​

在已确认需要规避的客户端初始化路径中，游戏 UI 视图创建后、首批 Canvas 图片开始绘制前设置一次。不要每帧调用，也不要放入所有项目共用的默认初始化代码。

以下 512 MiB 仅作为 PC 项目的测试起点；移动端或内存紧张设备必须另行评估，不能直接照搬：

csharp
#if CLIENT
GameGraph.ResourceSystem.ResourceCache.SetMemoryBudget(
    "UITextureResource",
    512UL * 1024 * 1024);
#endif

"UITextureResource" 是此兼容措施指定的引擎资源类型名，需要原样填写。预算影响当前客户端 ResourceCache 中的这一类 UI 图片，共享该缓存的其他界面也会受影响，并非只作用于某一个 Canvas。新建游戏 UI 视图可能重新设置默认预算，因此应放在该视图创建后的项目初始化位置。

  • 默认预算为 100 MiB。调高预算不会立刻分配对应大小的内存；它推迟闲置图片的预算回收。
  • 预算不是整个游戏的内存或显存硬上限，仍在使用的图片也可能让占用超过预算。
  • 不要用 0 表示恢复默认。 此处 0 表示不按预算回收，图片很多的项目可能持续积累内存。撤除临时调用后完整重启客户端，恢复默认初始化行为。
  • PNG/JPEG 文件大小不代表运行时纹理大小。可用宽 × 高 × 每像素字节数估算源图基础层，再区分实际纹理压缩、mipmap 和同时驻留集合；不要把所有图片的估算总和当作实时显存占用。

避免加重触发 ​

  • 不要定时调用 ImageCache.Invalidate、强制释放资源或反复清缓存作为刷新方案，这会增加回收和重载。
  • 不要承诺销毁重建 Canvas 能恢复。同一个游戏视图中的 Canvas 共用底层图片登记，换一个 Canvas 不会清空整个视图的登记状态。
  • 图片已经变白后，调高预算不会自动修复已损坏的纹理；先完整退出并重启客户端，再验证配置。
  • 若仍容易触发，可降低大幅场景图片的实际像素尺寸，减少运行时纹理占用。单纯减小 PNG 文件字节数通常达不到这个目的。

验证与撤除 ​

在相同旧客户端、相同项目资源和相似游玩路线下，对比修改前后反复切地图、开关背包、滚动图标及长时间游玩的表现，同时记录进程内存和可获得的纹理内存统计。不能用最新编辑器正常显示替代旧客户端验证。

如仍出现白图，或内存占用/稳定性变差，停止提高预算，保留日志并继续排查；不无限增加预算。没有运行测试时，明确标为“待验证的临时规避”，不能写成已修复。

待目标平台实际发布包含 Canvas 图片生命周期修复的客户端后，在新客户端移除这项临时配置，重新做上述回归。混合版本支持期若需要按版本启用，仅使用该平台已确认的修复版本界限。移除规避后不再依赖特殊预算，应以客户端修复为长期方案。