【继续】将即时生成地图改为预生成，影子存储机制的实现

[jayli]

承接 #68

起点：

498a800

分支：gen-big-map-first

【继续】将即时生成地图改为预生成，实现 worldstore 机制，完成了特殊实体的兼容，接下来是扩图，持久化和性能调优，实现 SpecialEntitiesShadowStore 机制。

[jayli]

代码审查结论补充

2dbb848..HEAD

结论先说：当前重构方向是正确的。特殊实体已基本实现“行为实例”与“IndexedDB读写”解耦，ShadowStore + 异步同步 架构已成型；但存在几处会影响数据正确性的风险点，建议优先修复。

1. 高风险：空实体 chunk 会复用旧内存镜像，可能造成幽灵实体回流

• 现象：loadFromRecord 中以 hasRuntimeEntities（长度>0）判定是否 deserializeAndMerge。当 runtimeEntities 存在但三类数组都为空时，不会清空 ShadowStore 该 chunk，后续又从 ShadowStore 读回旧数据。
• 影响：会破坏“主世界状态 = ShadowStore状态”，导致已删除实体重新出现。
• 位置：src/world/Chunk.js 335, 343, 361

2. 高风险：Worker 部分失败未被主线程处理，刷盘失败可能静默丢失

• 现象：ShadowSyncWorker.batchSync/flushAll 返回了 failedKeys，但 ShadowSyncDispatcher 仅在 RPC throw 时重试，未处理“部分成功”场景。
• 附加问题：batchSync 在 region 存在但 chunk 不存在时仍 successCount += chunkMap.size，成功计数会偏大。
• 影响：部分 chunk 的实体更新可能未落盘且无告警/补偿。
• 位置：src/world/ShadowSyncDispatcher.js 55；src/workers/ShadowSyncWorker.js 62, 67, 88, 142

---

ShadowStore 修复总结

经过两轮 review 和修复，已提交 2 个 commit 解决所有已识别问题：

Commit 1: a8bcd68 — 修复 Worker 部分失败 + 矿车 chunkKey

文件	变更
ShadowSyncDispatcher.js	_flush() 和 flushAll() 检查 Worker 返回的 failedKeys，失败 key 重入 _pending
ShadowSyncWorker.js	batchSync/flushAll 逐 chunk 计数 successCount++，缺失 chunk 推入 failedKeys，flushAll catch 块记录所有 chunk key
MinecartMovementSystem.js	跨 chunk 移动时同步更新 minecart.chunkKey

Commit 2: 6078ade — 修复失败重试 + 空实体清空 + 生命周期接入

文件	变更
ShadowSyncDispatcher.js	_flush() 重入队失败 key 后调用 _scheduleFlush() 自动重试；dispose() 改为 async，await flushAll() 后再终止 worker
Chunk.js	loadFromRecord 无 runtimeEntities 时调用 deserializeAndMerge 用空数据清空 ShadowStore，防止已删除实体回流
World.js	dispose() 改为 async，调用 await shadowSyncDispatcher.dispose() 接入生命周期

解决的问题清单

1. ✅ 高风险 截图 #2: Worker 部分失败未被处理 → 已修复，failedKeys 重入队 + 自动重试
2. ✅ 中风险 todo #4: 矿车跨 chunk 移动后 chunkKey 不更新 → 已修复
3. ✅ 失败 key 重入队后未重新调度 flush → 已修复
4. ✅ 空 runtimeEntities 不清空 ShadowStore → 已修复
5. ✅ flushAll() 未接入生命周期 → 已修复

验证

• npm run lint 通过（0 新增错误，51 个已有 warning 无变化）
• 两轮 subagent-driven 开发，每个任务均通过 spec compliance + code quality 双重审查

3. 中风险：flushAll() 缺少生命周期接入，存在最后脏数据窗口

• 现象：flushAll() 已实现，但当前无调用点；World.dispose() 也未触发它。
• 影响：页面关闭/异常退出时，最近一次 markDirty（500ms 防抖窗口内）可能未落库。
• 位置：src/world/ShadowSyncDispatcher.js 68；src/world/World.js 243

4. 中风险：矿车跨 chunk 移动后 chunkKey 不更新，卸载保存可能错位

• 现象：Minecart.chunkKey 仅在创建/恢复时赋值；移动过程只更新位置索引，不更新 chunkKey。
• 影响：stopMinecartsForChunk() 依赖 minecart.chunkKey 过滤时可能漏停/漏存，或把状态写回错误 chunk。
• 位置：src/actors/minecart/MinecartManager.js 171, 302, 331；src/actors/minecart/MinecartMovementSystem.js 636

补充：

• 总体架构评价：方向正确，值得继续推进。
• 当前未闭环重点：失败补偿语义、退出时最终落盘语义。
• 静态检查：npm run lint 通过（0 error，项目内既有 warning 未新增阻断项）。

[jayli]

Codex 架构师牵头做的性能扫尾的工作

代码基线：

6078ade

基于当前 gen-big-map-first 分支的代码现状，我对本轮 worldStore / Region / ShadowStore 重构的结论如下：

1. 整体方向是正确的，WorldStore + Region + runtime blockData 工作集 + ShadowSyncWorker 这条主线已经建立起来了。
2. 特殊实体（炮塔、丧尸巢穴、矿车）与持久化的解耦完成度较高，SpecialEntitiesShadowStore + ShadowSyncWorker 已经明显降低了特殊实体落盘对主线程的直接影响。
3. 地图预生成与 Region 机制已经落地，运行时不再走旧的"边渲染边生成地形"路径，这一点对大地图流畅度是实质性进展。
4. 当前代码还不能判定为已经完全达到目标 → P0 + P1 已全部收口，剩余问题见下方 P2+ 优先级。

目前最核心的残留问题有两类：

• WorldStore 还没有彻底收敛成唯一权威源 → P2 解决。
• 主线程上仍然保留了不少大对象处理 → P0 + P1 已消除热路径中的整块复制和全量序列化。

下一阶段的优先级建议：

P0：先砍掉 runtime 热路径里的"双缓存 + 全量复制" ✅ 已完成

• 彻底梳理 PersistenceService.cache 的职责，明确它是"迁移兼容层"还是"正式运行时层"，禁止继续和 WorldStore 共同参与真相判定。
• 去掉 Chunk.loadFromRecord() 对 PersistenceService.cache.blocks 的 overlay 依赖，改成只允许一次性迁移入口使用旧数据。
• 停止 Chunk.addBlockDynamic()、addBlocksBatchFast()、removeBlocksBatch() 在每次玩家操作时继续写 PersistenceService.recordChangeForChunk()。
• 停止 World.update() 在 chunk 卸载时调用 snapshotChunkBlocks() 全量复制整个 blockData。
• 让 WorldRuntime 成为唯一的 runtime 写回协调者，玩家编辑只改内存工作集并标脏，不再同步维护旧 delta cache。

P1：把主线程上的全量序列化/对象克隆压到最低 ✅ 已完成

• 重构 WorldRuntime.flushChunk() / flushAllDirty() / flushBeforeUnload()，避免每次 flush 都把整块 Map 转成完整 plain object。
• 评估改成"chunk dirty patch"或"增量 mutation log"写回，而不是"全量 chunkRecord 重写"。（recordBlockMutation 已承担增量脏 patch 角色）
• 如果短期不能增量化，至少把序列化放进专用 worker。（热路径已走 snapshot/cache，live Map 序列化仅在兜底分支触发，不再阻塞 P1 结项）
• 清理 Chunk.loadFromRecord() 里 pendingSnapshot.blocks = { ...effectiveBlockData } 这种额外全量拷贝。（182e94e 已设置为 null）
• 给 blockData / region record 的序列化链路打 perf 埋点，记录每次 flush 的 block count、耗时、对象大小。（9b6db3b 已补齐）

P1 完成后的代码基线：

9b6db3b

P2：把 WorldStore 真正收敛成唯一权威存储接口 ✅ 部分完成（2/3/4 已完成，1/5 待处理）

• 列出所有仍直接读写 PersistenceService 老接口的地方，逐个迁移到 WorldStore/WorldRuntime。
• 把 world_deltas 明确降级为"仅旧档迁移用途"，新运行时不再持续写入。
• 为 WorldStore 增加更清晰的 API 分层：load region/chunk、commit chunk changes、commit runtime entities，避免业务层绕路。
• 检查 WorldRuntime.ensureChunkData() 的迁移分支，迁移完成后删除 _ensureChunkEntitiesMigrated() 和对应兼容逻辑。
• 做一次"新档从零开始"和"旧档升级迁移"的读写路径图，确认没有双写和回流。

P2 做完后的基线：

33797e4

P3：继续收缩 runtime 每帧非渲染工作

• 审查 World.update() 里所有定时/轮询工作，区分"每帧必须做"和"可 idle/可事件驱动"。
• 检查 chunk load/unload 时还有哪些同步重操作残留在主线程，特别是实体收集、mesh 清理、对象转换。
• 检查特殊实体恢复链路，确认 ShadowStore -> runtime instance 不会在 chunk 频繁进出时重复做重初始化。
• 复查 AO、face culling、consolidation 的调度，确认它们不会和 flush/扩图同时形成尖峰。
• 给 chunk 装载、卸载、finalize、consolidation 建立统一的帧预算统计。

P4（降级）：把扩图和预生成进一步从主线程搬走

说明：预生成在 loading 阶段完成，不影响运行时 FPS；扩图期间的优化改为"串行→受控并发 + 节流"的轻量方案即可，结构性重构（RegionRecord 搬 Worker、overflow 处理位置等）工作量较大但运行时收益有限。降级到 P4 之后，待 runtime 每帧优化完成后再视压测结果决定是否执行。

• 初始预生成和扩图改为受控并发批处理（如 2-3 region 并行），缩短 _isGenerating 锁定窗口。
• 扩图阶段补上节流策略（扩图完成后冷却 N 秒再允许下一轮），避免玩家贴边移动时连续扩图拖慢主线程。
• 检查 WorldGenerationService._generateRegion() 当前主线程做的 RegionRecord 拼装和 overflow 合并，能搬到 worker 的尽量搬。
• 让 worker 直接产出更接近最终存储格式的 RegionRecord，主线程只负责提交，不负责大规模对象重组。
• 重新审视 cross-region overflow 的处理位置，减少主线程 Map/Object 合并。

P5：建立"稳定 60fps"验证闭环

• 定义硬指标：平均 FPS、P95/P99 帧耗时、chunk load 峰值耗时、flush 峰值耗时、扩图期间帧抖动。
• 做 3 个标准场景压测：高速跑图、连续放/拆方块、靠近边界触发扩图。
• 给 WorldRuntime flush、region load、chunk loadFromRecord、shadow sync 打结构化日志或 HUD 面板。
• 建立回归基线，改一项就对比一次，不再凭体感判断"是否更流畅"。
• 浏览器内补测试，至少覆盖：新档预生成、旧档迁移、chunk 卸载回写、特殊实体恢复、扩图后 reload 一致性。

建议执行顺序

1. 先做 P0 + P1 → 已完成
2. 再做 P2
3. 然后处理 P4（runtime 每帧优化）
4. 用 P5 验证是否真的逼近稳定 60fps
5. 视压测结果决定是否执行 P3（降级的扩图/预生成优化）

---

[jayli]

经过上一轮优化，chunk的 load 性能基本已经能控制的很好了，现在影响跑动过程中的卡顿问题的因素主要是chunk 卸载和 flush 带来的。接下来的优化重心是 chunk 的 unload 和 flush 刷盘（同步数据到 indexedDB）中。即接下来要做的事情。

[jayli]

2026-04-29 第二轮 runtime profiling

代码基线：

33797e4

基于本轮 CHUNK_PERF_DEBUG 的运行日志，当前结论需要更新：

1. 上一轮对 chunk load 的优化方向是对的，且已经生效。
2. loadFromRecord -> 主线程本地 blockData 遍历 -> _convertScatteredBlocksToMeshData -> buildMeshes 这条旧热路径已经基本被打掉。
3. 从最新日志看，新的主要瓶颈不再是 load，而是 unload 时的 flushBeforeUnload。
4. 玩家跑图时感受到的"chunk loading 卡顿"，本质上更像是 load/unload 同时发生时，unload flush 尖峰盖过了 load 优化收益。

关键证据：

• chunk.accept-worker-result: 约 0.3ms ~ 0.9ms
• chunk.build-meshes-global: 约 0.1ms ~ 0.5ms
• chunk.accept-scattered-blocks: 约 2.1ms ~ 3.4ms

这说明当前 chunk load 主线程装载路径已经比较轻。

真正异常的是：

• world-runtime.flush-before-unload: 4172ms ~ 12109ms
• 且 blockDataSource = live-chunk
• blockCount = 3400 ~ 5000

这说明 chunk unload 时，WorldRuntime.flushBeforeUnload() 仍然频繁落到 live-chunk 分支，直接从运行时 chunk.blockData 做整块 Map -> plain object 序列化，再批量写回 WorldStore / IndexedDB。

所以当前 runtime 主瓶颈已经从：

• 旧阶段：load 时主线程 mesh/build 路径过重

转移为：

• 现阶段：unload 时整块同步序列化 + 多 chunk Flush 洪峰

这和当前 branch 的大目标（降低 runtime 每帧计算压力、把 IO 与运行时解耦）仍然一致：

下一刀应该集中打 unload flush 卡顿，不是继续追 load。

---

新的 TODO（替换原 P3 中 runtime 方向的当前执行焦点）

P3.1：先收敛 unload flush 的同步重路径

• 审查 World.update() 的 chunk unload 流程，确认哪些步骤必须同步，哪些可以延迟到后台。（71f8b1a：测试验证 unload 当帧直接 dispose + chunks.delete，不等待 flush promise）
• 审查 WorldRuntime.flushBeforeUnload() 为什么频繁落到 live-chunk 分支，而不是优先使用已有 snapshot / dirty patch / region cache。（71f8b1a：_resolveSerializedBlockData 新增 allowLiveChunk 参数，构建后台快照时传 false 切断 live-chunk 回退）
• 禁止 unload 瞬间对大 chunk 直接做整块 Map -> Object 序列化，至少不能一帧内对多个 chunk 同时发生。（71f8b1a：flushBeforeUnload 改为入队，热路径无序列化）
• 评估把 unload flush 改成"先脱离场景 / 释放可见性，再异步排队写回"，避免渲染线程被持久化前置阻塞。（71f8b1a：注册 unload-flush-queue 到 runtimeIdleScheduler，priority 40 / budget 2ms / 每帧一次）

P3.2：把 unload flush 改成受控队列，而不是同帧洪峰

• 为 unload flush 建立专用队列，限制每帧/每批最多提交的 chunk 数量。（71f8b1a：pendingUnloadFlushQueue + flushPendingUnloadQueueWithinBudget 三维度预算 maxRegions/maxChunks/maxMs）
• 优先按 region 分组或按 chunk dirty 状态合并写回，减少碎片化 flush。（71f8b1a：按 region 聚合 chunkPatches，一次 applyRegionPatch 提交）
• 为 unload flush 增加背压/节流策略，避免玩家高速跑图时连续卸载引发 flush 雪崩。（71f8b1a：_pendingUnloadFlushInFlight 飞行保护 + idle scheduler 限频）

P3.3：让写回数据源尽量脱离 live runtime 对象

• 优先使用 dirty snapshot / mutation log / cached chunkRecord 写回，不再以 live chunk.blockData 为默认卸载数据源。（71f8b1a：解析链 explicitSnapshot → dirtyEntry → cachedChunkRecord → null，无稳定来源则跳过入队）
• 如果确实需要兜底序列化 live blockData，必须切片、限流或下沉到 worker，而不能在 unload 热路径里直接全量做。（71f8b1a：兜底路径默认关闭 allowLiveChunk: false，序列化发生在入队构造时而非热路径）

P3.4：补强观测，避免误判"load 卡顿"

• 将 chunk load 与 chunk unload flush 的日志分开汇总，分别看 P95 / P99。（71f8b1a：perf 事件 world-runtime.unload-enqueue / world-runtime.background-flush，与 load 路径完全独立）
• 区分"同步主线程耗时"和"异步 flush 总完成时间"，避免把队列耗时误当成单帧 load 耗时。（71f8b1a：getPendingUnloadFlushStats() 暴露 queueSize / lastProcessedChunks/Regions / lastElapsedMs）
• CHUNK_PERF_DEBUG 下对超大 blockData 的 JSON.stringify 统计做降级，避免观测本身放大卡顿。（71f8b1a：_recordFlushPerf 支持 allowObjectMetrics: false）

---

结论：P3.1 ~ P3.4 全部完成。 commit 71f8b1a 已实现：

• flushBeforeUnload 同步写盘 → 稳定快照入队 → 后台 idle 按 region 合批消费
• 彻底切断 live-chunk 回退路径
• 完整的遥测指标与测试覆盖

建议下一步：复测高速跑图场景，确认 unload flush 尖峰已消除后再决定是否继续深入 optimization callback / dispose 尖峰。

[jayli]

代码基线：

71f8b1a

下一步可以直接开始做第三阶段：专门收敛 load/assembly 路径的尖峰。

[jayli]

2026-04-30 第三轮 runtime profiling 补充结论

代码基线：

修改完成的当前工作树

fc0eba2

基于最近两轮 CHUNK_PERF_DEBUG 运行日志，可以把 #69 当前结论更新为：

1. chunk unload 热路径问题已经基本解决。
2. non-deferred-finalize 中由 AO 稳定源刷新带来的主线程尖峰已经被明显压下去。
3. 当前跑图过程中的主要前台瓶颈，已经进一步收敛到 runtime-build / loadFromRecord 这条装配路径。
4. background-flush 仍然吞吐较慢，但它现在更像后台持久化吞吐问题，而不是当前最优先的前台卡顿来源。

---

本轮结论拆解

1. unload 热路径已收口

这一点已经比较稳定：

• world-runtime.unload-enqueue: 0.00ms ~ 0.20ms
• 不再出现 flush-before-unload: 4s ~ 12s
• 不再出现 blockDataSource = live-chunk

这说明上一阶段把 unload 改成“稳定快照入队 + idle 后台 flush”的方向是对的，而且已经生效。

2. AO 导致的 finalize 主峰已被打掉

上一轮日志里最重的是：

• chunk-assembly.task stage: non-deferred-finalize = 20ms ~ 32ms

根因确认是：

• finalizeNonDeferredPhase()
• onChunkFinalized()
• onChunkAOSourceStable(fullRefresh: true)
• aoBridge.fullSync(chunk.blockData)

这条链路仍在 finalized 当帧把整块 blockData 全量同步给 AO worker。

本轮优化后，新的日志已经显示：

• 大多数 non-deferred-finalize 已降到 0ms ~ 8ms
• 只在少量大 chunk 上出现 10ms 左右

这说明：

• AO 稳定源刷新从 non-deferred-finalize 热路径移走，已经明确生效。

3. 当前新的主瓶颈：runtime-build / loadFromRecord

现在最稳定、最持续的前台重路径是：

• chunk.load-from-record: 4.7ms ~ 6.2ms
• 大 chunk 可到 9.0ms ~ 9.8ms
• 对应 chunk-assembly.task stage: runtime-build = 5ms ~ 10ms

并且 chunk-assembly.process 经常表现为：

• 11ms ~ 13ms
• 大 chunk 时可到 18ms ~ 21.5ms

这说明当前 scheduler 不是被 finalize 打爆，而是被 单个 runtime-build 任务本身 打爆。

更具体地说，当前最值得继续拆的路径是：

• loadFromRecord()
• _buildMeshFromExistingBlockData()
• blockData 遍历 -> convertMeshData -> buildMeshes

4. background-flush 仍慢，但优先级下降

后台 flush 依然会出现：

• world-runtime.background-flush: 357ms ~ 899ms

说明后台持久化吞吐问题还在。

但从当前整组日志看，这条路径已经不是最值得先打的前台问题：

• unload enqueue 已很轻
• finalize AO 已大幅下降
• 现在真正持续压帧的是 runtime-build

所以 background-flush 应暂时保留在“后台吞吐优化”问题域，不再作为当前跑图卡顿的第一优先级。

---

当前阶段总结

可以把 #69 的阶段性结论更新为：

• P3.1 ~ P3.4（unload/flush smoothing）已经达成目标。
• 新补的一轮 AO 后移优化也已生效，non-deferred-finalize 主峰已明显下降。
• 当前最主要的 runtime 卡顿来源，已经转移到 load/assembly 的 runtime-build 阶段。

---

建议的下一步执行焦点

建议从 #69 中把下一阶段重心明确切到：

P3.5：继续拆 runtime-build / loadFromRecord 热路径

• 把 loadFromRecord -> _buildMeshFromExistingBlockData() 再拆成更细的装配阶段，避免单个 runtime-build 任务吃掉整帧预算。
• 将 convertMeshData 与 buildMeshes 分离，必要时做切片或分帧提交。
• 对超大 chunk（blockCount 5000+ / blockDataSize 7000+）建立特殊处理策略，避免个别 chunk 形成 9ms ~ 10ms 级单任务峰值。
• 继续观察 GlobalInstancedMeshManager 的 mutation queue，因为 StreamingPerf 中 mutationQueueBlocks 仍会周期性冲到 5000 ~ 10000+，可能是 runtime-build 之后的下一层瓶颈。

当前判断：

unload 已基本收口，AO finalize 已收口一大半，接下来该打的是 runtime-build。

[jayli]

#75

done