chunk 装载性能优化

[jayli]

我希望进一步提升远端chunk加载的性能，降低chunk加载的延迟，降低chunk加载带来的卡顿，降低chunk加载对主线程的负面影响。
我不希望以牺牲远端chunk加载有延迟为代价换来更好的性能。我希望继续从 chunk 装载的过程，进一步优化遍历、检索、查询等等算法效率，压缩装载过程的时间。下面是日志，请你分析有哪些可改进的空间？

---

接下来 我用 kimi 和 codex 分别做分析，他们分析的根因侧重点不同

[jayli]

KIMI 初步进行的日志分析结论

基于按 N 和 L 采集的日志，chunk 装载流程存在 6 个显著瓶颈，按影响程度排序如下。

---

瓶颈 1：transitFromWorkerMs 高达 880-1300ms（最大痛点）

workerComputeMs:    25~72ms
transitFromWorkerMs: 883~1316ms

根因：postMessage 的 Structured Clone 序列化开销。WorldWorker 回包同时携带 blockDataBlocks（3000-4000 个对象）、scatteredBlocks（1000-2000 个）、meshData（多组 Float32Array）、visibleKeys、solidBlocks、snapshot 等，单 chunk 回包可达 数 MB。

优化方向：

1. Worker 回包瘦身：blockDataBlocks 和 scatteredBlocks 可从 meshData 反推，不需要三份同时回传。
2. Transferable ArrayBuffer：meshData 中的 matrices、aoLow、aoHigh 等大数组用 postMessage(data, [buffer1, ...]) 零拷贝传输。
3. Worker 池扩容：当前仅 3 个 Worker，多 chunk 并行生成时消息排队。扩容到 4-6 个可降低排队。

---

瓶颈 2：finalize 阶段 14-39ms — 主线程同步阻塞大头

chunk-assembly.task finalize 是单 chunk 加载中最长的同步阻塞阶段。

根因分解：

操作	耗时估算	位置
_registerLightSources()	3-5ms	Chunk.js:1666
_markAllBlocksDirtyAO()	5-10ms	Chunk.js:827
_markBoundaryDirtyAO() × 4 邻居	8-20ms	Chunk.js:843
_executeAORefresh() 大数组分配	2-5ms	Chunk.js:907

具体问题：

• _registerLightSources() 每次遍历 blockData Map（3000-4000 条），但一个 chunk 通常只有 0-5 个光源方块，99% 遍历是无用功。
• _markAllBlocksDirtyAO() finalize 时遍历所有 blockData 标记 dirty，但 Worker 生成时 AO 已算过，只是缺邻居数据。
• _markBoundaryDirtyAO() 遍历整个 blockDataArray（4096 长度），但只关心边界列（X=0/15 或 Z=0/15）。
• _executeAORefresh() 中 [...sentCodes].map(code => Chunk.decodeCoord(code)) 对 1000-2000 个 dirty 方块创建两个大中间数组。

优化方向：

1. 维护 lightSourceBlockCodes Set，增量追踪光源方块，finalize 时直接遍历此 Set。
2. Worker 回包附带因缺邻居而不准确的 AO 方块列表，主线程只标记这些，而非全量扫描。
3. _markBoundaryDirtyAO 只计算边界列索引范围，不扫 4096。
4. _executeAORefresh 用 for-of 遍历 Set 直接写入 TypedArray，避免中间数组。

---

瓶颈 3：chunk-assembly.process 系统性超预算 2-5 倍

budgetMs: 8, maxTasks: 6, processed: 2, durationMs: 18~43ms

根因：ChunkAssemblyScheduler._takeNext() 每次取任务都 线性扫描整个 queue（O(N)）。

优化方向：用 最小堆（Binary Heap） 替代数组队列，enqueue / dequeue 均降为 O(log N)。

---

瓶颈 4：_initArrayStorageFromBlockData() 频繁全量重建

每次 acceptScatteredBlocks、appendScatteredBlocks、_applyConsolidateResult 都全量重建 blockDataArray（4096，fill(0)）、blockPalette、blockPaletteReverse、solidBlockIds，然后遍历整个 blockData Map 重填。

优化方向：

• appendScatteredBlocks 只追加少量方块（日志 4-70 个），改为增量更新数组存储。
• deferConsolidation=true 时可跳过重建，consolidation 时再统一重建。

---

瓶颈 5：block-scatter.scatter 8-11ms — 分发阶段

distributeMs: 3~5ms
flushReadyChunksMs: 4~6.5ms

根因：

• scatter() 对每个方块做 Math.floor(x / CHUNK_SIZE) 和多次 Map 查找。
• _mergeStructureCenters() 对每个 touched buffer 创建新数组 + Set。
• flushReadyChunks() 遍历全部 chunkBuffers 而非仅 touched。

优化方向：

• 位运算替代 Math.floor(x / 16)：x >> 4。
• _mergeStructureCenters 就地追加，避免新数组。
• flushReadyChunks 只遍历 touchedBuffers。

---

瓶颈 6：apply-consolidate-result 中光源与数组重建

restoreAndReindexMs: ~4ms

每次 consolidation 都要 _unregisterLightSources() + _registerLightSources() + _initArrayStorageFromBlockData()，各自遍历全部 blockData。

优化方向：同上（光源索引 + 增量数组更新）。

---

优化优先级

优先级	改动	预期收益	改动量
P0	Worker 回包使用 Transferable ArrayBuffer	transitFromWorkerMs 1000ms → ~50ms	中
P0	Worker 回包瘦身（去重 blockDataBlocks/scatteredBlocks/meshData）	减少 50%+ 传输数据	中
P0	finalize 阶段光源扫描改为索引遍历	finalize 14-39ms → 8-15ms	小
P1	_markBoundaryDirtyAO 只查边界索引	减少 ~4ms/邻居	小
P1	_initArrayStorageFromBlockData 增量更新	append 阶段减少 1-2ms	中
P1	ChunkAssemblyScheduler 改用最小堆	scheduler 开销降低 60%+	小
P2	Worker 池扩容到 4-6 个	减少 Worker 排队	小
P2	scatter 分发位运算优化	scatter 8ms → 5ms	小

---

额外发现：性能警告 优化率过低 0.0%

来自 FaceCullingSystemDebug.js:183。chunk 加载期间新 InstancedMesh 刚创建，FaceCullingSystem 尚未成功剔除任何面，这是正常的；但如果 runtime-streaming 稳定后仍持续出现，需要确认 GlobalInstancedMeshManager.replaceChunkVisibleBlocks / patchChunkVisibleBlocks 是否在面剔除系统中正确注册了新增实例。

[jayli]

Codex 的初步分析和问题拆解

这次基于 StreamingPerf 和 ChunkPerf 日志做了归因，当前运行期远端 chunk 装载的主线程瓶颈可以收敛为以下几点：

1. block-scatter.flush-ready 是最明确的热点。
   当前实现每次有一个 Worker 回包，就会扫描整个 chunkBuffers。从日志看，acceptedChunks 基本只有 1，但 appendedChunks 长期在 30+，flush-ready 仍稳定在 5.8ms~9.6ms，说明这里的主要成本是“全表扫描 + 历史 buffer 重复检查”的固定税，而不是本次实际变化 chunk 的处理成本。

2. chunk-assembly.task(finalize) 任务粒度过粗，预算没有真正生效。
   虽然 chunk-assembly.process 的预算是 8ms，但日志里 finalize 单任务经常 9.8ms16ms，整个 process 仍会跑到 11ms19ms。这说明问题不是预算参数，而是 finalize 本身同步做的事情太多，必须切成更小阶段。

3. Worker 回包后的主线程 scatter 仍有明显分发成本。
   scatter.distributeMs 在大 chunk 上能到 3ms+。当前路径里每个 block 都要做 chunk 归属计算、编码、Map 查询和 visible key 判断，这部分还存在继续压缩遍历/检索成本的空间。

4. GlobalInstancedMeshManager 的 mutation 队列在高积压时有额外检索浪费。
   StreamingPerf 里 mutationQueueBlocks 峰值已经到 5000+。当前实现是每处理一个 block，就线性扫描一遍 mutationQueue 选最近任务，这会放大尾部上屏延迟，属于纯算法损耗。

5. buildMeshes 不是当前主瓶颈。
   从日志看，chunk.build-meshes-global 大多只有 0.2ms~0.4ms，明显低于 block-scatter 和 finalize。所以本轮优化重点不应该放在 mesh 构建本身，而应该放在 Worker 回包后的装配、分发、队列调度路径。

结论上，这一轮优化不建议走“降低预算/降低吞吐换平滑”的方向，而应该优先做：

• BlockScatterManager 去全表扫描，改成按本次触达 key 消费
• finalize 切成可预算调度的小阶段
• mutationQueue 改成按 task 批量消费，降低重复检索成本

对应文档：

• 设计文档：https://github.com/jayli/mc-lite/blob/73a5f55e7e49bd8577227ecbf18ad75c8523b83d/docs/superpowers/specs/2026-04-24-runtime-chunk-streaming-p1-design.md
• 实施计划：https://github.com/jayli/mc-lite/blob/73a5f55e7e49bd8577227ecbf18ad75c8523b83d/docs/superpowers/plans/2026-04-24-runtime-chunk-streaming-p1.md

[jayli]

接下来应将两者进行整合，进一步详细分析真正根因。

[jayli]

✅ P1 优化实施完成 — 提交 fc48571

根据之前 Codex 的性能分析，已实施三个核心优化：

1. BlockScatterManager 去全表扫描

• 文件: src/world/BlockScatterManager.js
• 改动: 引入 pendingReadyChunkKeys 集合，scatter() 只入队本次触达的 key，flushReadyChunks() 从全表遍历改为按队列消费
• 效果: 从 O(N) 全表扫描（N = 全部 buffer 数，约 30+）降到 O(K)（K = 实际变化 chunk 数，约 1-4）

2. Finalize 阶段拆分

• 文件: src/world/Chunk.js + src/world/ChunkAssemblyScheduler.js
• 改动: finalizeAssemblyPhase() 精简为预检查（consolidation 触发 + 状态标记），新增 finalizeNonDeferredPhase() 处理持久化/实体恢复/光源注册，两步各自占用独立的调度器 task
• 效果: 单体大函数被拆分为两个 budget-aware task，避免单任务超出 8ms 预算

3. Mutation Queue 批量消费

• 文件: src/core/GlobalInstancedMeshManager.js
• 改动: flushMutationQueue 从"每处理 1 个 block 就 O(N) 扫描整个队列选最近任务"改为"选中后批量消费该 task 的多个条目"
• 效果: 消除高积压场景（5000+ blocks）下的重复线性检索开销

其他

• ChunkPerfMonitor.js: console.debug → console.log（浏览器默认隐藏 debug 级别）
• 新增 test-block-scatter-manager.js 跨 chunk structureCenters 保留测试
• 更新 test-world.js finalize 行为测试适配两阶段架构

[jayli]

✅ 本轮优化已完成：scatter 归属判断前移到 Worker — 提交 6ed7752

这轮改造延续前面的结论：

• 主线程应尽量只做装配
• 归属判断、分桶、可见性准备应尽量在 Worker 中完成
• scatter() 不应该再对几千个 block 做逐个归属计算

本轮改动

1. WorldWorker 新增 routing 回包结构

• 文件: src/workers/WorldWorker.js
• 改动:
  • 新增 routing.schemaVersion
  • 新增 routing.ownChunk
  • 新增 routing.overflowChunks
  • Worker 直接把 own chunk 和 overflow chunk 的逻辑块 / 可见块按目标 chunk 预分桶
• 兼容策略:
  • 旧字段 blockDataBlocks / scatteredBlocks / visibleKeys 仍保留，便于过渡与回退

2. BlockScatterManager 优先消费 Worker 预分桶结果

• 文件: src/world/BlockScatterManager.js
• 改动:
  • scatter() 优先走 routing
  • own chunk 直接进 own buffer
  • overflow chunk 直接进 pendingCrossChunkPatchBuffers
  • 不再在主线程逐 block 重算 chunkCx / chunkCz / isOwnChunk

3. Chunk 直接支持 visibleBlocks

• 文件: src/world/Chunk.js
• 改动:
  • acceptScatteredBlocks() / appendScatteredBlocks() 支持直接接收 visibleBlocks
  • 渲染转换路径优先消费 visibleBlocks
  • 降低对 visibleKeys -> Set -> encodeCoord -> has 旧路径的依赖

4. 补充了契约与行为测试

• 文件:
  • src/tests/test-world.js
  • src/tests/test-block-scatter-manager.js
  • src/tests/test-chunk.js
• 验证结果:
  • 浏览器测试页 274/274 全通过

---

改造后的实际效果

1. 这轮改造是有效的

从最新 ChunkPerf 日志看：

• world.chunk-worker-result 多数样本落在 4.0ms ~ 6.3ms
• 改造前这一段常见在 5.2ms ~ 7.1ms
• 说明 Worker 回包后的主线程路径整体是变薄了

而且现在 block-scatter.scatter 日志中已经能看到：

• blockDataBlocks: 0
• scatteredBlocks: 0
• flushReadyChunksMs: 0

这说明旧的“主线程逐 block 归属判断 + visible key 二次归并”路径确实已经被绕开，新的 routing 路径已经在生效。

2. 这轮改造没有解决全部卡顿，但把瓶颈暴露得更清楚了

改造后 scatter 仍常见在：

• 3.3ms ~ 6.6ms
• 个别尖峰到 15.6ms

这说明现在 scatter 的主成本已经不再是“逐 block 算归属”，而是：

• flushReadyChunks() 同步触发 acceptScatteredBlocks()
• chunk 首次接收后的同步装配成本本身

也就是说，这一步不是没收益，而是把瓶颈从“归属判断”推进到了“接收装配”。

3. 当前最大的主线程瓶颈仍然是 non-deferred-finalize

最新日志里仍然持续出现：

• 13.4ms
• 16.2ms
• 17.0ms
• 19.1ms

并且直接把：

• chunk-assembly.process budgetMs: 8

打穿到：

• 17.3ms
• 19.1ms
• 21.3ms
• 23.5ms
• 24.2ms

这说明当前 chunk 加载时“轻微卡一下”的头号来源，仍然不是 Worker 回包接收，而是 finalize 阶段的同步长任务。

4. acceptScatteredBlocks 已经成为新的前台热点之一

最新样本里：

• 多数在 2.8ms ~ 5.6ms
• 但已经出现 14.6ms 的尖峰

说明接下来如果要继续压缩 chunk 首次装载的同步开销，acceptScatteredBlocks() 本身就该被拆解和削重了。

5. mutationQueue 仍会瞬时积压

StreamingPerf 里仍然出现：

• mutationQueueBlocks: 4265
• mutationQueueTasks: 18

说明全局实例写入队列依然是后续要处理的次级瓶颈，只是当前它还不是最尖锐的卡顿来源。

---

当前结论更新

现在可以把瓶颈优先级进一步收敛为：

P0

1. non-deferred-finalize 长任务拆片
2. acceptScatteredBlocks() 同步装配削重

P1

3. _initArrayStorageFromBlockData() 增量化，避免 append/patch 时整块重建
4. mutationQueue 继续做批量化 / 降检索复杂度

P2

5. 继续删除旧 visibleKeys 主路径，彻底收敛到 visibleBlocks
6. 继续把主线程中的可推导逻辑前移到 Worker

---

下一步建议

下一步我建议直接做下面两件事，不要分散：

1. 拆 non-deferred-finalize

目标：把当前 13ms~19ms 的 finalize 长任务切成多个真正可预算调度的小阶段。

优先拆出的内容：

• 持久化刷写
• 运行时实体恢复
• 光源注册
• AO 稳定源相关收尾

2. 削减 acceptScatteredBlocks() 的同步重活

目标：把 chunk 首次接收的同步阶段从“全量写入 + 全量重建 + 渲染转换”压成更轻的装配步骤。

优先方向：

• _initArrayStorageFromBlockData() 改增量路径
• visibleKeys 旧路径继续清退
• 能在 Worker 中准备好的数据，继续前移

如果这两步做完，chunk 加载时那种“轻微顿一下”的体感才会继续明显下降。

[jayli]

想到一个思路，跟原版我的世界一样，一次性生成一个超大的地图，玩家只要没到边界，都只从一个已经生成好的权威数据源blockData来装载chunk，blockData是在世界初始化阶段就已经生成好，只要blockData已经生成好了，就已经完成了实体方块的跨chunk归属的处理。玩家奔跑过程中，新加载的chunk都是从现有的blockData中取数据，blockData里都是权威数据