blockData 的快速缓存层，为了进一步减少（遍历）计算而设定的快速上屏所需的高速缓存层

[jayli]

代码基线

fc0eba2

[jayli]

基于当前分支 fc0eba235a8454507c6e87548c7a746ce7324366 的代码和最近一轮运行时日志，我的判断是：

当前 worldStore / region / shadow sync 这一轮重构的大方向是正确的，尤其是把 IndexedDB 从玩家交互热路径中拆掉、把 chunk unload 改成后台 flush queue，这两件事已经明显见效。现在 runtime 还没有彻底稳住 60fps 的主要原因，已经不再是“地图生成仍在主线程”，而是“chunk 从 WorldStore 读出来后，主线程仍然要重新解释 blockData，再生成上屏所需的 mesh/AO 数据”。

我把当前主要性能点整理如下：

1. flush-before-unload 已经很轻，说明 unload 不再同步打盘

• 日志里 world-runtime.flush-before-unload 基本在 0.00ms ~ 0.20ms
• 这说明“先入队、后台落盘”的思路已经达成目标
• 当前问题不在 unload 入队本身，而在后台 flush 的 region 级 patch/save 吞吐

2. load-from-record 已经成为新的 runtime 主热点之一

• 当前日志里 chunk.load-from-record 总耗时大约在 5.2ms ~ 12.5ms
• 其中最关键的是 convertMeshDataMs，大约在 2.6ms ~ 9.9ms
• 这部分对应的不是 IndexedDB IO，而是 chunk 从 store 读出来后，主线程又扫一遍 blockData，生成 blocks[] / meshData / visibleKeys
• 对于 60fps 的 16.7ms 帧预算来说，单 chunk 常态 3ms ~ 4ms、重一点 5ms ~ 7ms、极端接近 10ms，已经足够成为掉帧主因

3. 当前 runtime 读路径表面上按 chunk 用，底层实际还是“整块 RegionRecord 回主线程”

• ensureChunkData() 的使用粒度是 chunk
• 但 WorldStore 目前第一次命中 region 时，底层还是 getRegionRecord()，再在主线程投影出 chunk
• 这会把整块 region 的 structured clone / message transfer 成本压到主线程 message handler 上
• 日志里的 WorkerRpcClient.js:15 [Violation] 'message' handler took 305ms / 448ms，大概率就是这类大对象跨线程搬运成本，而不是 WorkerRpcClient 逻辑本身重

4. mutationQueue 也已经暴露为第二阶段瓶颈

• StreamingPerf 日志里多次出现 mutationQueueBlocks: 9k ~ 16k
• 这说明很多 chunk 其实已经完成装配，但还没真正刷进 GPU 实例数据
• 所以现在的瓶颈已经从“地图没生成好”进一步转移到“上屏提交吞吐”

5. FaceCulling 当前的 优化率过低: 0.0% 基本不能作为后续优化依据

• 代码里对应的 debug 统计还是模拟/占位性质
• 这一类警告当前更多是观测噪音，不是实际优化方向

基于上面这些现状，我对 issue #70 的建议是：

下一步优先级建议

P0：给 blockData 增加专门的 render cache 层，避免 runtime 主线程重复扫 blockData 生成 meshData

推荐把每个 ChunkRecord 拆成两层：

1. 权威层（world truth）

• blockData
• staticEntities
• runtimeSeedData
• runtimeEntities

2. 渲染快取层（仅为快速上屏服务）

• renderCache.meshData
• renderCache.visibleKeys
• renderCache.lightSources
• renderCache.version
• renderCache.sourceHash

这个 renderCache 必须被明确定位为：

• 非权威
• 可丢弃
• 可重建
• 用空间换 runtime 主线程时间

这样 runtime 纯加载路径就从：

blockData -> blocks[] -> convertMeshData -> buildMeshes

改成：

renderCache.meshData -> buildMeshes

如果 cache 缺失或失效，再回退到 worker 异步补建，而不是主线程补建。

P1：render cache 的生成时机

我建议两处生成：

1. 预生成阶段

• WorldWorker / region generation 产出 blockData 时，顺手把 renderCache 一起产出并写入 WorldStore

2. 运行时修改后

• consolidation 完成后，由 worker 按最新 blockData 重建该 chunk 的 renderCache
• 再回写到 WorldStore

这样 runtime streaming 的主线程只消费 cache，不重新解释 blockData。

P2：把“chunk 级读取”真正下沉到 worker / persistence 层

即使做了 render cache，如果第一次命中 region 时仍然把整个 RegionRecord 整包搬回主线程，message handler / structured clone 还是会有明显尖峰。

所以后续最好继续推进：

• worker/persistence 层直接提供 chunk 级投影读取
• 主线程拿到的是单 chunk 的 ChunkRecord（含 renderCache）
• 而不是先拿完整 region 再切

P3：再处理 GlobalInstancedMesh 的 mutation queue 吞吐

在上面两步完成后，再继续看：

• 是否需要降低单 chunk 初次上屏的实例提交量
• 是否需要把 render cache 进一步切成更适合直接灌入 global instanced manager 的格式

结论

issue #70 的方向我认同，而且我认为这一步现在已经不是“锦上添花”的缓存优化，而是 runtime streaming 继续降主线程负担所必须的一层。

更准确地说：

• blockData 仍然是世界真相
• renderCache 是 chunk 的快速上屏缓存
• 它的目标不是提升数据正确性，而是消灭 load-from-record 里那段 3ms ~ 10ms / chunk 的主线程重建成本

我下一步会按这个方向继续细化方案，先给出 ChunkRecord.renderCache 的结构、失效规则、生成链路和 fallback 行为，再决定是否需要把它独立成单独 store，还是先内嵌到 RegionRecord.chunks[chunkKey] 中落第一版。

---

已经设计好了方案和计划：

• docs/superpowers/specs/2026-04-30-blockdata-render-cache-design.md
• docs/superpowers/plans/2026-04-30-blockdata-render-cache.md

当前代码基线：

b7e14ad