blockData vs IndexedDB_Memory_Storage 谁适合作为权威数据源

[jayli]

从consolidation 的时候 blockData 被多次深拷贝带来的卡顿的问题分析到了权威数据源的多次全量拷贝带来的设计问题，接下来是深入的分析。

代码基线：

1ed3544

Trace 分析结论：consolidation 触发的持久化深拷贝是卡顿的主因

通过 Chrome Trace 分析，定位到一次删除方块后触发 consolidation 的完整卡顿链路：

单帧卡顿 1422ms

一个动画帧耗时 1422ms（正常 ≤16ms），FunctionCall 事件分解如下：

耗时	位置	说明
1422ms	Game.js:425	游戏主循环帧（总）
392ms	IndexedDBUtils.js:58 request.onsuccess	IndexedDB 事务提交 + 内部 structuredClone
376ms	IndexedDBUtils.js:58 request.onsuccess	同上
358ms	WorkerRpcClient.js:15 worker.onmessage	Worker 返回 consolidation 结果后主线程处理
358ms	PersistenceWorker.js:343 self.onmessage	PersistenceWorker 处理 saveRegionRecord
172ms	PersistenceWorker.js:343 self.onmessage	同上

根因：blockData 被多次 structuredClone

在 consolidation → 持久化链路中，同一份 blockData 被克隆了 3~4 次：

主线程 WorldRuntime._flushDirtyChunks()
  │
  ├─ ① _serializeBlockData()           ← Map → 普通对象转换
  │
  └─ postMessage('applyRegionPatch')
       │
       └─ ② 浏览器内部 structuredClone  ← postMessage 跨 Worker 传递
            │
            PersistenceWorker.self.onmessage (358ms)
              │
              ├─ ③ structuredClone(region)  ← PersistenceWorker.js:235 显式深克隆
              │    整份 region 对象，含所有 chunk 的 blockData
              │
              └─ saveRegionRecord → store.put({ data: record })
                   │
                   └─ ④ IndexedDB 内部 structuredClone ← 规范要求存储隔离

为什么明明是内存存储还这么慢？

不是磁盘 I/O，是 structuredClone 的 CPU 开销。structuredClone 对大型嵌套对象是 O(n) 的遍历和复制操作。一个 region 包含多个 chunk，每个 chunk 的 blockData 有几百到上千个坐标映射，clone 时每个 key-value 都要递归处理。

IndexedDB 规范要求在存储前对数据进行结构化克隆以保障数据隔离，所以即使你把数据存在内存里（无磁盘延迟），store.put(largeObject) 仍然会触发一次完整的 structuredClone。

优化方向

1. 去掉 PersistenceWorker.js:235 的显式 structuredClone（P0）—— IndexedDB 内部本身就会 clone，显式 clone 是纯浪费。改为原地修改 region 缓存，写入失败再从 IndexedDB 回读恢复
2. 将 _flushDirtyChunks 的刷写与 consolidation 错峰（P0）—— consolidation 完成后延迟再触发持久化，避免两者抢 CPU
3. 考虑使用 Transferable 传递 blockData（P1）—— postMessage 时用 transfer list 转移 ArrayBuffer 所有权，避免跨线程 clone
4. 将大 region 粒度拆分（P2）—— 减少单次 store.put 的数据量

---

为此我想将权威数据源统一到 blockData 身上，写了一个方案：

https://gist.github.com/jayli/da68916e68272032abe7cc7e79b5a146

还没有详细review这个方案的合理性

[jayli]

在以上初步分析的基础上，进一步分析权威数据源的设计合理性上的问题

基于当前代码实现，对 runtime 期间几个主要数据源的职责、读写频率、性能与一致性做了进一步梳理，结论如下。

当前真实架构并不是简单的 blockData / visibleBlockData / IndexedDB 三层主从，而更接近于：

• Chunk.blockData：当前 chunk 内的核心逻辑数据表，实际承担 chunk 级逻辑权威角色。
• MemoryWorldStore：世界级运行时内存权威层，负责 unloaded chunk / runtime streaming 下的世界真相。
• visibleKeys + meshData + solidBlocks + instanceIndexMap：渲染/碰撞派生层。当前代码里并不存在单独的 visibleBlockData 结构，这个概念已经被拆散。
• IndexedDB：并未完全退场，虽然注释里多处写成“运行期已旁路、仅供未来手动保存”，但实际 runtime 里仍然存在 saveDebounced() -> WorldRuntime.flushChunk() -> WorldStore.commitChunkRecord() 的持续异步写回链路。

1. 关于 blockData

blockData 现在实际上已经不是“只存动态修改”的小增量表，而更接近“chunk 的完整逻辑块集合”。

原因是：

• chunk 加载 / worker 回包时，acceptScatteredBlocks() 会把逻辑方块直接写入 blockData
• region 预生成和恢复时，chunkRecord.blockData 也作为主要逻辑载荷存在
• 玩家改单块时，blockData 仍然是第一落点

因此它已经是逻辑层最关键的真相源之一，而不是单纯的 delta。

2. 关于“visibleBlockData”

当前实现里没有这个字段。如果要分析“可见块数据”，应该把它理解为一组派生结构，而不是单表：

• visibleKeys：哪些逻辑块经过面剔除后可见
• meshData：真正送给渲染层的实例数据
• solidBlocks：用于碰撞/实心判断的派生集合
• instanceIndexMap：坐标到实例索引的映射

所以当前体系是“逻辑真相”和“可见渲染派生层”分离，而不是“blockData / visibleBlockData”二分。

3. 高频读写路径的合理性

高频读最合理的部分是 isSolid：

• 热路径优先走 blockDataArray + solidBlockIds 的 O(1) 查询
• 不命中再回退 solidBlocks / blockData

这对物理、碰撞、寻路这类每帧大量读取场景是合理的，说明数组化优化是有效的。

但通用查询如 getBlockEntry() 则未完全吃到这套收益：

• Chunk.getBlockEntry() 仍然优先查 blockData，再回退 blockDataArray
• 如果 blockData 已经接近完整逻辑表，那么数组快路径的收益主要集中在 isSolid，而不是所有通用查询

高频写方面，单次方块修改会同步更新：

• blockData
• visibleKeys
• solidBlocks
• lightSourceCoords
• blockDataArray
• solidBlockIds
• MemoryWorldStore
• AO Worker 副本队列
• WorldRuntime dirty snapshot
• debounce 持久化计时器

这保证了改单块后大部分系统能立即看到一致结果，优点是正确性强；缺点是写放大明显，单次修改的常数成本偏高。

4. 一致性判断

Chunk.blockData 与 MemoryWorldStore：

• 这两层的一致性总体较强
• 因为它们大多在同一个同步调用栈中一起更新
• runtime 正确性实际上主要依赖这两层，而不是 IndexedDB

blockData 与可见层：

• 这里是典型的最终一致性
• visibleKeys / meshData 是派生结果，允许短暂滞后
• worker 回包后还会再根据 blockData 做过滤，防止幻影方块

这说明代码已经明确把 blockData 视为逻辑真相，把 visible 层视为可重建派生层，这个方向是对的。

MemoryWorldStore 与 IndexedDB`：

• 这里是当前最模糊、也最值得收敛的部分
• 注释语义是“运行期以内存为权威，IndexedDB 只负责旧存档导入和未来手动保存”
• 但实际代码仍在 runtime 中持续 flush 到 IndexedDB

所以现在并不是彻底的“单权威 + 冷存储”，而是“内存权威 + IndexedDB 异步跟随”的混合模式。

5. 性能与架构合理性的总体评价

合理的部分：

• isSolid 已经有明确的热路径优化
• blockData -> visibleKeys / meshData 的真相 / 派生关系是清晰的
• MemoryWorldStore 作为 streaming 场景下的世界级内存权威是合理方向
• worker 回包再对照 blockData 过滤，能压制异步竞态导致的幻影方块

不合理或需要进一步收敛的部分：

• visibleBlockData 概念已经不再对应真实实现，继续沿用这个词容易误导讨论
• blockData 的注释职责与真实职责已经漂移
• blockData、blockDataArray、solidBlocks、solidBlockIds、MemoryWorldStore.blockData 之间存在明显数据重复，读性能有收益，但写路径维护成本较高
• 最大问题是 IndexedDB 在 runtime 里并没有真正退居“冷存储层”，而是仍在参与持续异步写回，导致概念上不是单权威，也带来 region 粒度读改写的写放大

6. 当前最关键的判断

如果只看“运行期是否能正确工作”，这套架构是基本成立的。

如果看“是否已经是清晰、彻底、可长期维护的 runtime 存储架构”，答案是否定的。当前最大问题不是某个容器本身慢，而是：

• 运行期到底谁是唯一权威，概念还没有完全收口
• blockData 的职责边界和文档描述已经不一致
• IndexedDB 仍然半退半留，导致 runtime 双写和 region 级写放大

建议后续讨论优先围绕两件事展开：

• 先把 runtime 真实数据流按场景画清楚：单块修改、chunk 加载、chunk 卸载、consolidation、手动保存
• 再决定 IndexedDB 是否要真正降级为“仅手动保存导出层”，否则“MemoryWorldStore 是运行期唯一权威”这个说法在工程上并不彻底

[jayli]

补充一份“当前数据源全景表”，把现有代码里的主要数据结构，映射到目标设计中的分层位置，便于后续讨论哪些应保留、哪些应降级、哪些应删除。

代码基线：

1ed3544

当前数据源全景表

当前数据源 / 结构	当前职责	读写频率	是否权威源	在新设计中的归属	处理建议
Chunk.blockData	已加载 chunk 的逻辑方块数据，承接加载、玩家修改、worker 回包	高读高写	是（局部）	权威逻辑层 blockData	保留，升级为 loaded chunk 的唯一逻辑权威
MemoryWorldStore.chunks[].blockData	未加载 chunk 的世界级内存驻留数据；reload 时恢复 chunkRecord	中读中写	是（世界级）	权威逻辑层 blockData 的 unloaded 形态	保留，但语义改为“未加载 chunk 的 blockData 容器”，不再作为并行第二权威
WorldRuntime._dirtyChunks[].blockDataSnapshot	运行时 flush 用的稳定快照，避免直接依赖 live chunk.blockData	中写低读	否	持久化过渡快照层	目标删除
pendingUnloadFlushQueue	chunk 卸载前排队待写回的稳定 chunkRecord	低频	否	持久化过渡快照层	目标删除或显著收缩
WorldRuntime._regionCache	region 级缓存，支撑 flush / prefetch / 旧存储路径	中读中写	否	持久化过渡缓存层	运行时主链路中降级，仅保留冷启动/导出辅助用途
PersistenceService.cache	旧的 chunk snapshot cache	低频	否	持久化过渡缓存层	目标删除运行时职责
PersistenceWorker.regionCache	Worker 侧 region 缓存，减少 IndexedDB 重复回读	中读中写	否	持久化过渡缓存层	仅在冷启动阶段按需保留；主链路切稳后评估删除
Chunk.visibleKeys	面剔除后当前可见块集合，服务显示与补面	高读中写	否	渲染索引层	保留原语义，明确为 blockData 的派生索引
Chunk.solidBlocks	当前实心块集合，服务碰撞/物理/实心判断	极高读中写	否	碰撞索引层	保留原语义，明确为 blockData 的派生索引
Chunk.blockDataArray	chunk 内 Y:0~15 的紧凑数组快路径，服务 O(1) 查询	极高读中写	否	高速查询索引层	建议保留，继续作为 blockData 的派生紧凑索引
Chunk.solidBlockIds	与 blockDataArray 配套，快速判断 blockId 是否实心	极高读中写	否	高速查询索引层	建议保留
Chunk.blockPalette / blockPaletteReverse	blockId <-> block entry 映射，支撑数组快路径	高读中写	否	高速查询索引层	若保留 blockDataArray，则继续保留
Worker 返回的 meshData	chunk 级渲染载荷，直接供 InstancedMesh 构建	中读中写	否	渲染载荷层	保留
Chunk.instanceIndexMap	坐标到实例槽位的映射，服务局部增量更新	高读中写	否	渲染载荷层 / 渲染索引子层	保留
GlobalInstancedMeshManager 内 chunk 可见实例状态	全局 InstancedMesh 输出层	高读高写	否	渲染载荷层（全局输出）	保留
Chunk.renderDelta	渲染增量补丁队列，供全局实例系统按预算消费	高写中读	否	渲染载荷层（增量补丁）	保留
Chunk.dynamicMeshes	旧路径/降级路径下的动态 mesh 缓存	中读中写	否	渲染降级层	视全局实例化改造进度逐步收缩
Chunk.lightSourceCoords	光源方块索引，避免遍历全部 blockData	高读中写	否	光照/AO 派生层	保留
Chunk.dirtyAOPositions	AO 脏集，驱动局部 AO 重算	高写中读	否	光照/AO 派生层	保留
AOWorker.chunkCache / AOBridge 镜像	Worker 侧 AO 计算所需的 blockData 副本	中读中写	否	Worker 副本层	保留，但明确是 blockData 的最终一致镜像
Chunk.deletedBlockTombstones	防止晚到的 worker 回包把已删除方块写回	中读中写	否	异步一致性保护层	必须保留，除非有更强版本化替代
Chunk.structureCenters	跨 chunk 结构判断、可见性例外、补片判定辅助	中读低写	否	结构辅助层	保留
Chunk.entityCollisionIndex	特殊实体碰撞占位，不属于普通方块 blockData	高读中写	否	实体碰撞层	建议保留独立语义，不硬塞进 blockData
chunkRecord.runtimeEntities / staticEntities	实体持久化与恢复数据	中读中写	是（实体域）	实体逻辑层	保留，与 blockData 并列但不混合
IndexedDB world_regions / world_meta	冷存储、导入导出、刷新后恢复	低频	否（runtime 中）	冷存储层	降级为异步落盘/导出，不再参与运行时权威判断

建议的目标分层

结合上表，较稳妥的目标设计不是简单的“两层”，而是下面这套：

1. 权威逻辑层

   • blockData
   • 语义上统一覆盖当前的 Chunk.blockData + MemoryWorldStore.blockData
   • 已加载 chunk 时由 Chunk.blockData 持有
   • 未加载 chunk 时由 MemoryWorldStore 作为该 chunk 的 blockData 容器持有

2. 渲染索引层

   • visibleKeys
   • 只回答“当前是否可见/是否应参与显示更新”

3. 碰撞索引层

   • solidBlocks
   • 只回答“当前是否实心/是否参与碰撞”

4. 高速查询索引层

   • blockDataArray
   • solidBlockIds
   • blockPalette / blockPaletteReverse
   • 继续服务 chunk 内极高频查询，不承担权威职责

5. 渲染载荷层

   • meshData
   • instanceIndexMap
   • renderDelta
   • GlobalInstancedMeshManager 的全局实例状态

6. 光照 / AO / 一致性保护层

   • lightSourceCoords
   • dirtyAOPositions
   • AO Worker 镜像
   • deletedBlockTombstones

7. 实体与冷存储层

   • entityCollisionIndex
   • runtimeEntities / staticEntities
   • IndexedDB

这张表对应的关键判断

• 真正要合并的，不是 visibleKeys、solidBlocks、blockDataArray 这些索引层，而是当前被拆成两份运行时权威的 Chunk.blockData + MemoryWorldStore.blockData 语义。
• visibleKeys 和 solidBlocks 不应合并，应该原样保留用途，但明确降级为派生索引。
• blockDataArray / palette 这类紧凑结构也不应被误删，它们不是“多余权威源”，而是高频查询加速层。
• 真正应收缩/删除的是 WorldRuntime / PersistenceService / PersistenceWorker 周围那套 blockData snapshot / region cache / flush queue 过渡快照链。
• IndexedDB 应降级为冷存储和异步落盘层，而不是继续参与 runtime 权威判断。

如果继续往下推进改造，我建议下一步先画出“单块修改 / chunk 加载 / chunk 卸载 / reload / 手动保存”这 5 条链路的目标数据流，再开始动代码。

[jayli]

docs/superpowers/plans/2026-05-07-blockdata-authority-unification.md
docs/superpowers/specs/2026-05-07-blockdata-authority-unification-design.md

[jayli]

完善文档的 prompt：

我在当前分支要做的事是完善几个大的数据源的重新梳理和重构，让数据源的设计更加合理，减少冗余和设计歧义，为下一步减少无谓的数据同步、遍历、查找等耗时的操作优化打基础。

现在我希望将 blockData 设计为权威数据源，代替MemoryWorldStore的权威数据源的语义，同时保持现有的游戏功能，在此基础上重新设计数据源的层次和同步机制，为下一步的性能 优化打基础。

为此我对代码现状（c846695e2f1ad340e122c43d6cbec79ab692a2ec）做了详细的分析，最初是分析consolidation的卡顿来源，分析到了大量的不合理的blockData的非常耗时的深拷贝(https://github.com/jayli/mc-lite/issues/74#issue-4398920716)，在此基础上，进一步分析权威数据源的设计合理性上的问题（https://github.com/jayli/mc-lite/issues/74#issuecomment-4397466348），这两份文档是对现状的严重程度的一个分析。

在这些分析基础上，我制作了一份当前数据源全景表(https://github.com/jayli/mc-lite/issues/74#issuecomment-4397731241)，当前数据源在代码功能上是可以工作的，这个文档里还包括了建议的目标分层，为你接下来做方案设计做参考。

通过以上的分析，我写了一份设计文档和实施计划文档：

docs/superpowers/plans/2026-05-07-blockdata-authority-unification.md
docs/superpowers/specs/2026-05-07-blockdata-authority-unification-design.md

请你再次根据当前代码的现状，以及我的要求（统一权威数据源的设计），实现更清晰可靠的数据源流转，为接下来的冗余数据剔除进而优化性能而打基础。请你根据这些信息做详细分析，判断这两份设计文档和计划文档是否已经足够完善，还有没有遗漏的地方，还有哪些地方需要完善。

这将是一个非常巨大的改造，涉及到底层逻辑的变动，对计划文档的质量要求极高，请你深入分析。

[jayli]

执行前的代码基线：

c846695

[jayli]

第一次完整实施后的代码基线：

2a7d38a

[jayli]

#77

完整的实现，现在唯一的问题是，在我的 macbook 上游戏运行时，地面有空洞