跨 Chunk 材质合批（DONE）

[jayli]

/speckit.specify 接下来我要做 跨 Chunk 材质合批，目前的问题：相邻 Chunk
的相同纹理方块无法共享 InstancedMesh，我想进一步进行跨 Chunk 材质合批优化 - 将相邻 chunk 的相同纹理合并。

[jayli]

#65

done

[jayli]

合批引入的一个问题：

41d0641 这次提交实现了跨 chunk 合批的功能，目的是解决fps太差的状况。但这次修改引入了一个新的问题，就是部分方块在 合批模式下无法被删除，具体体现有4种状况：

1. 十字准心对准方块时，方块无法被消除，反而是这个方块背后的方块被消除掉了。
2. 十字准心对准的方块可以被消除，但是不是立即被消除，而是等一两秒后才消失。
3. 十字准心对准的方块可以被立即消除，但过几秒后又显示了出来，好像重来没有被消除过一样。
4. 十字准心对准的方块A不能被立即消除，A也不能延时消失，但玩家放置或者消除其他的一些方块后，这个A方块有时候就可以被立即消除掉了，也不会复现，表现的就正常了。

我确信是合批功能引入的这个问题，因为我开启合批时，这种状况会立即出现，关闭合批时，就一切正常。

我尝试在三个提交中修复这个问题：

0e27faf
bcd49b0
81ba7cd

从目前的状况来看，问题依然没有彻底修复，依然存在我说的这四种情况。

请你详细review我的修复，以及最开始合批优化的改动，找出根因。

我理解这个问题应当很好解决，因为无法被消除的方块是可以跟玩家产生碰撞的，只是十字准心射线似乎无法碰撞到这个方块，玩家也不能用十字准心对准方块的一个面时放置另一个方块，这个现象在tree 实体的 wood 方块上出现的概率最高，我感觉方块是实实在在存在的，那么，十字准心射线碰撞检测用的方块数据和用来判断玩家是否身体跟方块碰撞所用的方块是同一个来源吗？

我感觉问题方块跟跨chunk合批的情况直接相关，即有可能不跨chunk的方块不会有这个问题，只有跨chunk的方块有这个问题，请你检查。另外一个可能性是否是，如果一个实体跨出当前chunk后，被另外一个chunk管理，恰好这两个chunk又没有进行合批的动作，是否就容易出现这个问题。请你调研。

请你用 debugging 技能来深入调研根因，找出问题。还有一种选项，就是紧接着跨chunk合批的实现，进一步补足渲染管线上的漏洞，比如删除方块时有多套管线，会带来不一致的问题，有好多脏数据，如果不好通过打补丁的方式修复，那就从机制上做修复。

[jayli]

全局 InstancedMesh 合批方案

现状问题

当前每个 Chunk 独立管理自己的 InstancedMesh，导致：

1. Draw Call 过高 — Draw Call 数 = chunk数 × 方块类型数
2. 多 owner / 归属歧义 — 跨 chunk 方块被多个 chunk 的 blockData 持有，导致删除不彻底、射线命中错误、方块复现
3. 删除用 scale-to-zero 而非真正移除 — 实例仍然占用 InstancedMesh 的 index 位置
4. InstancedMesh 底层 TypedArray 容量固定 — 新增/删除/扩容困难

方案设计：Free-List + Swap-Remove + 周期性紧缩

GlobalInstancedMeshManager (全局单例)
├── per-type buffers: Map<blockType → TypeBuffer>
│   ├── instanceMesh: THREE.InstancedMesh (容量 65536)
│   ├── coordToIndex: Map<number → number>   // 世界坐标编码 → instance index
│   ├── indexToCoord: Uint32Array(65536)     // instance index → 世界坐标编码 (反向查找)
│   ├── activeCount: number                  // 当前活跃实例数
│   └── freeList: number[]                   // 空闲 index 列表
│
├── chunkToBlocks: Map<chunkKey → Set<number>>  // chunk 卸载时批量清理
└── 每种方块类型 = 1 个 InstancedMesh = 1 次 Draw Call（跨所有 chunk）

三大核心算法

1. 新增方块 — O(1)

• 优先复用 freeList 中的空闲 index
• 否则追加到 activeCount 末尾，count++
• 写入 TypedArray 矩阵 + AO + 朝向

2. 删除方块 — Swap-Remove O(1)

• 找到被删方块的 index
• 将最后一个活跃实例的数据（矩阵、AO、朝向）拷贝到被删位置
• 更新被移动实例的 coordToIndex 映射
• count--，被删 index 进入 freeList
• 无需重建 TypedArray，纯 O(1)，从数据结构层面保证删除一定生效

3. 周期性紧缩

• freeList 超过阈值时触发
• 将所有活跃实例紧凑排列到 [0, activeCount)
• 防止 freeList 无限膨胀导致内存碎片

与现有系统集成

World.js
├── 持有 globalInstancedMeshManager
├── Chunk 不再创建自己的 InstancedMesh
│   ├── Chunk.group 保留用于动态网格和特殊实体
│   └── Chunk 只管理 blockData / blockDataArray（数据层）
├── resolveBlockOwner() 简化为 O(1) 查找，彻底消除多 owner 问题
└── Chunk unload → 批量清理全局管理器中的方块

解决的历史问题

问题	解决方式
多 owner / owner ≠ 坐标 chunk	彻底消除 — 方块只有一个全局位置，不存在归属歧义
方块无法被删除	Swap-Remove 从数据结构层面保证删除生效
删除后复现	blockData 是唯一真相源，删除即从 Map 和全局管理器同时清除
实体被切割	已在 breakup-blocks-from-entities 分支打散，不再有"实体"概念
Draw Call 过多	每种方块类型 = 1 个 InstancedMesh = 1 次 Draw Call，跨所有 chunk
靠补丁兜底的问题	从机制上消除，不需要 _dedupeLoadedChunkOwners、crossChunkOwnerCache 等

---

Chunk 加载卡顿缓解分析

当前卡顿根因

玩家移动时远方 chunk 加载的卡顿主要来自：

1. Chunk 初建时 acceptScatteredBlocks → buildMeshes — 每个新 chunk 立即创建多个 per-type InstancedMesh（_buildSingleTypeMesh），每个都要 material.clone()、geometry.clone()、创建 BufferAttribute、写入矩阵。这是主线程密集工作。
2. _initArrayStorageFromBlockData() — 每次接受方块数据都会遍历 blockData 重建 palette。
3. _convertScatteredBlocksToMeshData — 遍历所有方块按 type 分组、创建 Float32Array。
4. consolidation 触发 — 新 chunk 的 dirtyBlocks 触发 Worker 计算 + _applyConsolidateResult（销毁旧网格 + 重建新网格）。

本方案能消除的卡顿

卡顿来源	是否解决	原因
每 chunk 创建多个 InstancedMesh	解决	不再有 per-chunk InstancedMesh，全局管理器只做 TypedArray 写入
material.clone() / geometry.clone()	解决	材质和几何体全局共享，不再 clone
_initArrayStorageFromBlockData() 重复调用	部分缓解	blockDataArray 保留，但不需要为渲染重建 palette
_convertScatteredBlocksToMeshData 遍历	大幅简化	Worker 返回的方块直接写入全局 TypedArray，不需要 per-chunk 分组
consolidation 重建 InstancedMesh	消除	consolidate 不再需要销毁+重建 InstancedMesh，只做 AO 通知

本方案不能完全解决的

剩余卡顿来源	说明
Worker 通信往返	worldWorker.postMessage → 等待回包，异步通信本身有开销
BlockScatterManager 分发逻辑	按坐标分发到 chunk buffer 的遍历逻辑仍然存在
AO 计算	_refreshAOFromStableSource → AOWorker 仍然在 chunk 加载时触发

结论

本方案能显著减轻但不会完全消除 chunk 加载卡顿。

• 消除：per-chunk InstancedMesh 创建/销毁（这是主线程卡顿的最大来源）
• 保留：Worker 计算 + AO 计算（这些本身是异步的，不阻塞主线程）

要彻底消除卡顿，还需要配合：

1. Worker 生成结果分批返回（而不是一次性返回整个 chunk 的方块）
2. 全局管理器的 addBlock 操作分帧执行（每帧写入固定数量，不集中写入）
3. AO 计算延迟到 idle 阶段（当前已经在做，但可以更早介入）

[jayli]

我仔细看了这个全局 InstancedMesh 合批方案，也对照了当前 breakup-blocks-from-entities 分支的代码。结论是：这个方向可行，而且比之前几次“跨 chunk owner 修补式合批”更接近正确解。但核心算法建议从 Free-list + Swap-Remove + 周期性紧缩 调整为更简单、更稳的：

Dense Array + Swap-Remove + 延迟扩容

也就是说，全局渲染层始终保持 [0, count) 是连续活跃实例。删除时把最后一个实例搬到被删位置，更新反向索引，然后 count--。不要保留洞位，不要 scale-to-zero，不要依赖 freeList。freeList 会重新引入稀疏状态，使 raycaster 的 instanceId、indexToCoord、mesh.count 更容易不一致。

当前分支已经具备的好基础

breakup-blocks-from-entities 已经做对了最关键的一步：实体方块按坐标所属 chunk 分发和落盘，生成阶段之后不再需要长期依赖“实体 owner”语义。

现在的 BlockScatterManager.scatter() 是按 floor(x / CHUNK_SIZE), floor(z / CHUNK_SIZE) 分发方块；Chunk.acceptScatteredBlocks() 也只接收本 chunk 范围内的方块。这意味着后续可以把规则收敛为：

1. 坐标所属 chunk 是唯一逻辑 owner。
2. GlobalInstancedMeshManager 是唯一渲染 owner。
3. coord -> renderRef -> instanceId 是唯一映射。

只要坚持这个不变量，之前 main / cross-chunk-batching 系列里出现的多 owner、owner != 坐标 chunk、删除无效、删除后复现等问题就可以从机制上消掉。

目前仍然存在的问题

当前代码虽然打散了实体方块，但渲染层仍然是 per-chunk InstancedMesh。

Chunk.buildMeshes() 仍然为每个 chunk、每种方块类型创建 THREE.InstancedMesh。所以 draw call 仍然近似是：

chunk 数 × 方块类型数

删除链路也仍然依赖 owner 扫描和 per-chunk instanceIndexMap。World.resolveBlockOwner() 还保留了坐标 chunk、跨 chunk cache、全量扫描三层逻辑；World.removeBlock() 还需要删除所有 owner 来防御历史脏数据。这说明历史问题的根因还没有被最终消除，只是当前分支已经为消除它创造了条件。

推荐的核心数据结构

GlobalInstancedMeshManager
├── buffers: Map<renderKey, TypeBuffer>
├── coordToRef: Map<number, { renderKey, index }>
├── chunkToCoords: Map<string, Set<number>>
└── mutationQueue: 分帧执行的 add/remove/update 队列

TypeBuffer
├── mesh: THREE.InstancedMesh
├── capacity: number
├── count: number
├── coordToIndex: Map<number, number>
├── indexToCoord: Float64Array | Array<number>
├── aoLow: Float32Array
├── aoHigh: Float32Array
├── orientation: Float32Array
└── dirtyRanges

注意：indexToCoord 不建议用 Uint32Array。当前 encodeCoord() 的编码范围远大于 32 位，应该用 Float64Array，或者拆成 Int32Array x/y/z 三列。

第一版建议 renderKey = blockType，也就是每种方块类型一个全局 InstancedMesh。先不要做跨类型材质合批。等“每类型全局合批”稳定后，再考虑升级成 geometryType + materialGroup + renderFlags。

新增算法

addVisibleBlock(coord, entry, chunkKey, renderData) {
  if (coordToRef.has(coord)) {
    updateBlock(coord, entry, renderData);
    return;
  }

  const renderKey = getRenderKey(entry.type);
  const buffer = getBuffer(renderKey);
  buffer.ensureCapacity(buffer.count + 1);

  const index = buffer.count++;
  buffer.coordToIndex.set(coord, index);
  buffer.indexToCoord[index] = coord;
  coordToRef.set(coord, { renderKey, index });

  chunkToCoords.get(chunkKey).add(coord);

  writeMatrix(buffer, index, coord, entry.orientation);
  writeAO(buffer, index, renderData.aoLow, renderData.aoHigh);
  writeOrientation(buffer, index, entry.orientation);

  buffer.mesh.count = buffer.count;
  buffer.markDirty(index);
}

新增是 O(1)。容量不足时按 1.5x 或 2x 扩容，创建更大的 InstancedMesh，复制旧 TypedArray，替换 scene 中的 mesh。扩容不是每次新增都发生，所以摊还复杂度是 O(1)。

删除算法

removeVisibleBlock(coord) {
  const ref = coordToRef.get(coord);
  if (!ref) return false;

  const buffer = buffers.get(ref.renderKey);
  const index = ref.index;
  const last = buffer.count - 1;
  const movedCoord = buffer.indexToCoord[last];

  if (index !== last) {
    copyInstance(buffer, last, index);
    buffer.indexToCoord[index] = movedCoord;
    buffer.coordToIndex.set(movedCoord, index);
    coordToRef.get(movedCoord).index = index;
  }

  buffer.coordToIndex.delete(coord);
  coordToRef.delete(coord);
  buffer.indexToCoord[last] = 0;
  buffer.count--;
  buffer.mesh.count = buffer.count;

  buffer.markDirty(index);
  return true;
}

这个路径不需要 scale-to-zero，不需要 freeList，不需要周期性紧缩。活跃实例永远连续，raycaster 的 instanceId 永远能通过 indexToCoord[instanceId] 找回真实方块坐标。

和当前代码的集成顺序

第一阶段：只替换渲染 owner

保留 Chunk.blockData、blockDataArray、solidBlocks，继续作为逻辑、物理、持久化数据源。

改造 Chunk.buildMeshes(meshData)：不再创建 per-chunk InstancedMesh，而是把 meshData 里的 visible block 注册到 world.globalInstancedMeshManager。

Chunk.group 暂时保留，用于特殊实体、粒子、调试对象等非普通方块对象。

第二阶段：改 raycaster 坐标解析

PlayerInteraction.getInteractionTargets() 需要加入全局 manager 的所有 mesh。

命中全局 InstancedMesh 后，不再靠 hit.point 或 owner scan 推断方块坐标，而是：

const buffer = hit.object.userData.globalBuffer;
const coord = buffer.indexToCoord[hit.instanceId];
const { x, y, z } = decodeCoord(coord);

然后直接 world.removeBlock(x, y, z)。

这是解决“十字准心命中但删不到直接瞄准方块”的关键点。

第三阶段：简化 owner 语义

World.resolveBlockOwner() 最终应该只查坐标所属 chunk，不再全量扫描所有 chunk。

getAllBlockOwners() 可以保留一段时间作为迁移期诊断工具：如果发现同一坐标有多个 owner，直接报警统计，而不是作为正常删除路径。

第四阶段：consolidation 从“重建 mesh”改成“提交 patch”

当前 consolidation 会清理旧网格再 buildMeshes()，全局合批后这条路径应该改成：

globalInstancedMeshManager.applyVisibilityPatch(chunkKey, {
  addedVisibleBlocks,
  removedVisibleCoords,
  updatedAO,
  updatedOrientation
});

consolidation 不再销毁/重建 InstancedMesh，只负责基于 Worker 结果提交 visibility/AO patch。

第五阶段：chunk unload

chunk unload 时不再 dispose per-chunk InstancedMesh，而是：

for (const coord of chunkToCoords.get(chunkKey)) {
  removeVisibleBlock(coord);
}
chunkToCoords.delete(chunkKey);

这能保证卸载只移除该 chunk 的全局实例，不影响其他 chunk 的同类型 mesh。

必须守住的不变量

1. 同一 coord 在全局渲染层最多存在一次。
2. coordToIndex 与 indexToCoord 永远互逆。
3. mesh.count === buffer.count。
4. 活跃实例永远位于 [0, count)。
5. 删除逻辑只接受坐标，不接受 owner。
6. raycaster 命中 InstancedMesh 后，坐标来自 indexToCoord[instanceId]，不是从 hit.point 猜。
7. Worker 异步回包应用前必须校验当前 blockData 仍存在且类型一致，否则丢弃，避免删除后复现。

风险判断

这个方案会明显降低 draw call，也能从机制上解决多 owner 和删除无效问题。它对 chunk 加载卡顿也有帮助，因为 per-chunk InstancedMesh 创建、geometry clone、material clone、consolidation 后重建 mesh 都可以被消掉。

主要风险是全局 mesh 会削弱 chunk 级 frustum culling。当前 renderDistance 只有 2-3，收益大概率大于风险。如果以后扩大视距，可以再把每种类型拆成“区域页 mesh”，例如每 4x4 chunk 一个 page，但第一版不建议做这个复杂度。

最终建议路线：

1. 先做“每种方块类型一个全局 InstancedMesh”。
2. 再改 raycaster 通过 instanceId -> coord 删除。
3. 再把 resolveBlockOwner() 收敛为坐标 chunk 唯一 owner。
4. 最后把 consolidation 改成 visibility/AO patch，不再重建 mesh。

不要第一版就做跨类型材质合批。先把全局实例索引层做稳，FPS 和删除正确性都会先得到最大收益。

[jayli]

这轮把 _convertScatteredBlocksToMeshData() 尽量前移到 Worker 之后，数据上已经有明确改观。

观察结论：

1. 主线程前处理压力已经明显下降

• 之前奔跑时常见：mutationQueueBlocks 在 8000 ~ 30000，mutationQueueTasks 在 20 ~ 100+
• 现在奔跑时常见：mutationQueueBlocks 在 3447 / 3675 / 4408 / 4560 / 6434，mutationQueueTasks 在 15 / 18 / 22 / 27 / 66
• 说明 Worker 侧预构建 meshData 这步是有效的，主线程 _convertScatteredBlocksToMeshData() 这一块确实是之前的重要 CPU 开销来源之一

2. 当前瓶颈已经不再是 chunk 装配调度

• 奔跑采样里 assemblyQueue 基本持续为 0
• 这说明 ChunkAssemblyScheduler 并没有形成持续积压
• 当前主要问题已经收敛到全局 InstancedMesh 的 mutationQueue 短时突发，而不是装配阶段排队

3. 现在的问题形态已经从“长期积压”收敛成“短时尖峰”

• 典型现象是：某一秒奔跑进入新区域时，mutationQueueBlocks 冲到几千；下一秒又回到 0
• 这比之前“大量堆积且持续排不完”已经好很多
• 但仍然会在局部时刻打出长帧，例如这次采样里出现了：[Violation] requestAnimationFrame handler took 64ms

所以当前可以下一个明确判断：

• Worker 前移 meshData 生成，这个方向是对的，而且已经显著缓解了 chunk 加载排队
• 但它不是全部答案
• 剩余瓶颈已经从“主线程持续排队”收敛成“全局实例 flush 的短时尖峰”

下一步优化重点应该从“继续怀疑 meshData 主线程转换”切换到“削峰”：

• 继续减少 mutationQueue 的瞬时入队峰值
• 做更聪明的 flush 优先级（距离 + 运动方向，而不是视线方向）
• 增加对单帧 flush 峰值的观测，而不只是看每秒吞吐

一句话总结：

这次改造已经把问题从“持续积压、远端 chunk 长时间跟不上”推进到了“总体可清空，但在奔跑进入新区时仍有短时尖峰”。这说明整体方向已经走对了，下一阶段要做的是削峰，而不是继续在同一个层面重复优化。