minecraft-renderer 0.1.79 → 0.1.80

package/src/three/globalLegacyBuffer.ts

@@ -7,7 +7,7 @@ import {
   logLegacyMultiDrawTierOnce,
   type LegacyDrawSpan,
   type LegacyMultiDrawCaps,
-  type LegacyMultiDrawScratch,
+  type LegacyMultiDrawScratch
 } from './legacyMultiDraw'
 import { computeCameraRelativeUniforms, type RenderOrigin } from './shaders/legacyBlockShader'
 
@@ -22,24 +22,83 @@ const DEFAULT_GROWTH_INCREMENT_QUADS = 128_000
 const MAX_UPLOAD_QUADS_PER_FRAME = 5_000
 const FRAGMENTATION_THRESHOLD = 0.25
 
-type PendingMove = { key: string, oldStart: number, newStart: number, count: number }
+type PendingMove = { key: string; oldStart: number; newStart: number; count: number }
+type PendingReplace = { oldStart: number; oldCount: number }
 
 /** CPU bytes per allocated quad slot (all legacy vertex/index attrs). */
-export const LEGACY_BYTES_PER_QUAD =
-  VERTS_PER_QUAD * (FLOATS_PER_VERT * 3 + FLOATS_PER_LIGHT_VERT * 2 + FLOATS_PER_UV_VERT) * 4
-  + INDICES_PER_QUAD * 4
+export const LEGACY_BYTES_PER_QUAD = VERTS_PER_QUAD * (FLOATS_PER_VERT * 3 + FLOATS_PER_LIGHT_VERT * 2 + FLOATS_PER_UV_VERT) * 4 + INDICES_PER_QUAD * 4
 
 export const FULL_DRAW_VISIBLE_FRACTION = 0.75
-export const SPAN_GAP_TOLERANCE_QUADS = 256
+/** Initial multi_draw scratch size; arrays auto-grow — not a draw-call cap. */
 export const MAX_OPAQUE_SPANS = 64
 
+/** Dev assert: every quad in draw spans must lie in a live section's drawable range. */
+export function assertDrawSpansWithinLiveRanges(
+  spans: ReadonlyArray<{ start: number; count: number }>,
+  liveRanges: ReadonlyArray<{ start: number; count: number }>,
+  bufferName: string
+): void {
+  for (const span of spans) {
+    for (let q = span.start; q < span.start + span.count; q++) {
+      let inLive = false
+      for (const live of liveRanges) {
+        if (q >= live.start && q < live.start + live.count) {
+          inLive = true
+          break
+        }
+      }
+      if (!inLive) {
+        console.error('[GlobalLegacyBuffer] draw span covers non-live quad', {
+          buffer: bufferName,
+          quad: q,
+          span,
+          liveRanges
+        })
+      }
+    }
+  }
+}
+
+export type DirtyRange = { start: number; end: number }
+
+/** Split draw spans to exclude quad/face ranges still in pendingRanges (not yet on GPU). */
+export function carveSpansAroundPendingRanges(
+  spans: Array<{ start: number; count: number }>,
+  pendingRanges: ReadonlyArray<DirtyRange>
+): Array<{ start: number; count: number }> {
+  if (pendingRanges.length === 0) return spans
+  const out: Array<{ start: number; count: number }> = []
+  for (const span of spans) {
+    let segments: Array<{ start: number; count: number }> = [span]
+    for (const pr of pendingRanges) {
+      const next: Array<{ start: number; count: number }> = []
+      for (const seg of segments) {
+        const segEnd = seg.start + seg.count - 1
+        if (pr.end < seg.start || pr.start > segEnd) {
+          next.push(seg)
+          continue
+        }
+        if (pr.start > seg.start) {
+          next.push({ start: seg.start, count: pr.start - seg.start })
+        }
+        if (pr.end < segEnd) {
+          next.push({ start: pr.end + 1, count: segEnd - pr.end })
+        }
+      }
+      segments = next
+    }
+    out.push(...segments)
+  }
+  return out.filter(s => s.count > 0)
+}
+
 export type GlobalLegacyBufferOptions = {
   name?: string
   initialCapacityQuads?: number
   growthIncrementQuads?: number
 }
 
-export type VisibleSectionSpan = { key: string, distSq: number }
+export type VisibleSectionSpan = { key: string; distSq: number }
 
 export type LegacySectionGeometry = {
   positions: Float32Array
@@ -75,24 +134,22 @@ export class GlobalLegacyBuffer {
   private uvs: Float32Array
   private aOrigin: Float32Array
   private indices: Uint32Array
-  private readonly sectionSlots = new Map<string, { start: number, count: number }>()
-  private freeList: Array<{ start: number, count: number }> = []
+  private readonly sectionSlots = new Map<string, { start: number; count: number }>()
+  private freeList: Array<{ start: number; count: number }> = []
   private highWatermark = 0
-  private pendingRanges: Array<{ start: number, end: number }> = []
-  private readonly _spanScratch: Array<{ start: number, count: number }> = []
+  private pendingRanges: Array<{ start: number; end: number }> = []
+  private readonly _spanScratch: Array<{ start: number; count: number }> = []
   private renderOrigin: RenderOrigin = { x: 0, y: 0, z: 0 }
   private layoutVersion = 0
   private pendingMove: PendingMove | null = null
+  private readonly pendingReplace = new Map<string, PendingReplace>()
+  private uploadEpoch = 0
   private visibleIndexSpans: LegacyDrawSpan[] = []
   private readonly _drawScratch: LegacyMultiDrawScratch = createLegacyMultiDrawScratch()
   private multiDrawCaps: LegacyMultiDrawCaps | null = null
   private debugOverlay = false
 
-  constructor (
-    material: THREE.ShaderMaterial,
-    scene: THREE.Object3D,
-    opts?: GlobalLegacyBufferOptions,
-  ) {
+  constructor(material: THREE.ShaderMaterial, scene: THREE.Object3D, opts?: GlobalLegacyBufferOptions) {
     this.material = material
     this.growthIncrementQuads = opts?.growthIncrementQuads ?? DEFAULT_GROWTH_INCREMENT_QUADS
     this.capacityQuads = opts?.initialCapacityQuads ?? DEFAULT_INITIAL_CAPACITY_QUADS
@@ -146,7 +203,7 @@ export class GlobalLegacyBuffer {
     }
   }
 
-  setDebugOverlay (enabled: boolean): void {
+  setDebugOverlay(enabled: boolean): void {
     this.debugOverlay = enabled
   }
 
@@ -156,19 +213,19 @@ export class GlobalLegacyBuffer {
    * program/VAO/ELEMENT_ARRAY_BUFFER stay bound while three draws ~nothing.
    * Draws one triangle from index 0 (usually harmless; if quad 0 is culled, one stray tri).
    */
-  suppressThreeDraw (): void {
+  suppressThreeDraw(): void {
     this.mesh.geometry.setDrawRange(0, 3)
   }
 
-  setVisibleIndexSpans (spans: LegacyDrawSpan[]): void {
+  setVisibleIndexSpans(spans: LegacyDrawSpan[]): void {
     this.visibleIndexSpans = spans
   }
 
-  getVisibleIndexSpans (): readonly LegacyDrawSpan[] {
+  getVisibleIndexSpans(): readonly LegacyDrawSpan[] {
     return this.visibleIndexSpans
   }
 
-  private syncDefaultDrawGroups (): void {
+  private syncDefaultDrawGroups(): void {
     const geometry = this.mesh.geometry
     geometry.clearGroups()
     const indexCount = this.highWatermark * INDICES_PER_QUAD
@@ -178,13 +235,7 @@ export class GlobalLegacyBuffer {
     geometry.setDrawRange(0, indexCount)
   }
 
-  addSection (
-    sectionKey: string,
-    geo: LegacySectionGeometry,
-    sx: number,
-    sy: number,
-    sz: number,
-  ): boolean {
+  addSection(sectionKey: string, geo: LegacySectionGeometry, sx: number, sy: number, sz: number): boolean {
     const vertCount = geo.positions.length / FLOATS_PER_VERT
     const quadCount = vertCount / VERTS_PER_QUAD
     if (vertCount === 0 || quadCount * VERTS_PER_QUAD !== vertCount) {
@@ -195,8 +246,23 @@ export class GlobalLegacyBuffer {
       return false
     }
 
-    if (this.sectionSlots.has(sectionKey)) {
-      this.removeSection(sectionKey)
+    const isRemesh = this.sectionSlots.has(sectionKey)
+    let previousSlot: { start: number; count: number } | undefined
+    if (isRemesh) {
+      const currentSlot = this.sectionSlots.get(sectionKey)!
+      const inflightReplace = this.pendingReplace.get(sectionKey)
+      const inflightMove = this.pendingMove?.key === sectionKey ? this.pendingMove : undefined
+      if (inflightReplace) {
+        this.zeroAndFreeSlot(currentSlot.start, currentSlot.count)
+        previousSlot = { start: inflightReplace.oldStart, count: inflightReplace.oldCount }
+        this.pendingReplace.delete(sectionKey)
+      } else if (inflightMove) {
+        this.zeroAndFreeSlot(currentSlot.start, currentSlot.count)
+        previousSlot = { start: inflightMove.oldStart, count: inflightMove.count }
+        this.pendingMove = null
+      } else {
+        previousSlot = currentSlot
+      }
     }
 
     if (quadCount > this.capacityQuads) {
@@ -240,29 +306,65 @@ export class GlobalLegacyBuffer {
     }
 
     this.sectionSlots.set(sectionKey, slot)
+    if (isRemesh && previousSlot) {
+      this.pendingReplace.set(sectionKey, { oldStart: previousSlot.start, oldCount: previousSlot.count })
+    }
     this.markDirty(slot.start, slot.start + quadCount - 1)
     this.syncDefaultDrawGroups()
     this.layoutVersion++
     return true
   }
 
-  getLayoutVersion (): number {
+  getLayoutVersion(): number {
     return this.layoutVersion
   }
 
-  getSectionDrawStart (sectionKey: string): number | undefined {
+  getUploadEpoch(): number {
+    return this.uploadEpoch
+  }
+
+  hasPendingReplace(): boolean {
+    return this.pendingReplace.size > 0
+  }
+
+  canUseFullDrawShortcut(): boolean {
+    return this.pendingRanges.length === 0 && this.interiorFreeQuads() === 0 && this.pendingMove === null && this.pendingReplace.size === 0
+  }
+
+  isRangeFullyUploaded(start: number, end: number): boolean {
+    return this.rangeFullyUploaded(start, end)
+  }
+
+  getPendingDirtyRanges(): ReadonlyArray<DirtyRange> {
+    return this.pendingRanges
+  }
+
+  getSectionDrawStart(sectionKey: string): number | undefined {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return undefined
     if (this.pendingMove?.key === sectionKey) return this.pendingMove.oldStart
+    const replace = this.pendingReplace.get(sectionKey)
+    if (replace) return replace.oldStart
+    if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) return undefined
     return slot.start
   }
 
-  getPendingMove (): PendingMove | null {
+  getSectionDrawCount(sectionKey: string): number | undefined {
+    const slot = this.sectionSlots.get(sectionKey)
+    if (!slot) return undefined
+    if (this.pendingMove?.key === sectionKey) return this.pendingMove.count
+    const replace = this.pendingReplace.get(sectionKey)
+    if (replace) return replace.oldCount
+    if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) return undefined
+    return slot.count
+  }
+
+  getPendingMove(): PendingMove | null {
     return this.pendingMove
   }
 
   /** One interior-hole move per frame when fragmentation exceeds threshold; deferred shrink. */
-  compactStep (): void {
+  compactStep(): void {
     if (this.pendingMove) {
       const { newStart, count } = this.pendingMove
       if (this.rangeFullyUploaded(newStart, newStart + count - 1)) {
@@ -271,6 +373,14 @@ export class GlobalLegacyBuffer {
       return
     }
 
+    for (const key of [...this.pendingReplace.keys()]) {
+      const slot = this.sectionSlots.get(key)
+      if (!slot) continue
+      if (this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) {
+        this.finalizePendingReplace(key)
+      }
+    }
+
     if (this.highWatermark === 0) return
     const interiorFree = this.interiorFreeQuads()
     if (interiorFree / this.highWatermark <= FRAGMENTATION_THRESHOLD) return
@@ -292,7 +402,7 @@ export class GlobalLegacyBuffer {
     this.layoutVersion++
   }
 
-  updateDrawSpans (visible: VisibleSectionSpan[], mode: 'opaque' | 'sortedBlend'): void {
+  updateDrawSpans(visible: VisibleSectionSpan[], mode: 'opaque' | 'sortedBlend'): void {
     this.visibleIndexSpans = []
 
     if (this.highWatermark === 0) {
@@ -305,10 +415,11 @@ export class GlobalLegacyBuffer {
 
     for (const entry of visible) {
       const drawStart = this.getSectionDrawStart(entry.key)
+      const drawCount = this.getSectionDrawCount(entry.key)
       const slot = this.sectionSlots.get(entry.key)
-      if (drawStart === undefined || !slot) continue
-      spans.push({ start: drawStart, count: slot.count })
-      visibleQuadCount += slot.count
+      if (drawStart === undefined || drawCount === undefined || !slot) continue
+      spans.push({ start: drawStart, count: drawCount })
+      visibleQuadCount += drawCount
     }
 
     if (spans.length === 0) {
@@ -318,45 +429,47 @@ export class GlobalLegacyBuffer {
     const pushIndexSpan = (quadStart: number, quadCount: number): void => {
       this.visibleIndexSpans.push({
         indexStart: quadStart * INDICES_PER_QUAD,
-        indexCount: quadCount * INDICES_PER_QUAD,
+        indexCount: quadCount * INDICES_PER_QUAD
       })
     }
 
     if (mode === 'opaque') {
-      if (visibleQuadCount >= this.highWatermark * FULL_DRAW_VISIBLE_FRACTION) {
-        this.visibleIndexSpans.push({
-          indexStart: 0,
-          indexCount: this.highWatermark * INDICES_PER_QUAD,
-        })
-        return
+      let finalQuads: Array<{ start: number; count: number }>
+      const liveDrawRanges = spans.map(s => ({ ...s }))
+      const usedFullDraw = this.canUseFullDrawShortcut() && visibleQuadCount >= this.highWatermark * FULL_DRAW_VISIBLE_FRACTION
+      if (usedFullDraw) {
+        finalQuads = [{ start: 0, count: this.highWatermark }]
+      } else {
+        spans.sort((a, b) => a.start - b.start)
+        this.mergeOpaqueSpans(spans)
+        finalQuads = spans
       }
-
-      spans.sort((a, b) => a.start - b.start)
-      this.mergeOpaqueSpans(spans)
-      this.capOpaqueSpans(spans)
-
-      for (const span of spans) {
+      finalQuads = carveSpansAroundPendingRanges(finalQuads, this.pendingRanges)
+      if (!usedFullDraw) {
+        assertDrawSpansWithinLiveRanges(finalQuads, liveDrawRanges, this.mesh.name)
+      }
+      for (const span of finalQuads) {
         pushIndexSpan(span.start, span.count)
       }
     } else {
       visible.sort((a, b) => b.distSq - a.distSq)
       for (const entry of visible) {
         const drawStart = this.getSectionDrawStart(entry.key)
-        const slot = this.sectionSlots.get(entry.key)
-        if (drawStart === undefined || !slot) continue
-        pushIndexSpan(drawStart, slot.count)
+        const drawCount = this.getSectionDrawCount(entry.key)
+        if (drawStart === undefined || drawCount === undefined) continue
+        pushIndexSpan(drawStart, drawCount)
       }
     }
   }
 
-  private mergeOpaqueSpans (spans: Array<{ start: number, count: number }>): void {
+  /** Merge only physically adjacent section slots (gap === 0). Never bridge interior holes. */
+  private mergeOpaqueSpans(spans: Array<{ start: number; count: number }>): void {
     if (spans.length < 2) return
     let i = 0
     while (i < spans.length - 1) {
       const cur = spans[i]!
       const next = spans[i + 1]!
-      const gap = next.start - (cur.start + cur.count)
-      if (gap <= SPAN_GAP_TOLERANCE_QUADS) {
+      if (cur.start + cur.count === next.start) {
         cur.count = next.start + next.count - cur.start
         spans.splice(i + 1, 1)
       } else {
@@ -365,40 +478,22 @@ export class GlobalLegacyBuffer {
     }
   }
 
-  private capOpaqueSpans (spans: Array<{ start: number, count: number }>): void {
-    while (spans.length > MAX_OPAQUE_SPANS) {
-      let bestIdx = 0
-      let bestGap = Infinity
-      for (let i = 0; i < spans.length - 1; i++) {
-        const gap = spans[i + 1]!.start - (spans[i]!.start + spans[i]!.count)
-        if (gap < bestGap) {
-          bestGap = gap
-          bestIdx = i
-        }
-      }
-      const cur = spans[bestIdx]!
-      const next = spans[bestIdx + 1]!
-      cur.count = next.start + next.count - cur.start
-      spans.splice(bestIdx + 1, 1)
-    }
-  }
-
-  hasSection (sectionKey: string): boolean {
+  hasSection(sectionKey: string): boolean {
     return this.sectionSlots.has(sectionKey)
   }
 
-  getSectionSlot (sectionKey: string): { start: number, count: number } | undefined {
+  getSectionSlot(sectionKey: string): { start: number; count: number } | undefined {
     return this.sectionSlots.get(sectionKey)
   }
 
-  takeSectionData (sectionKey: string): LegacySectionGeometryData | undefined {
+  takeSectionData(sectionKey: string): LegacySectionGeometryData | undefined {
     const data = this.getSectionGeometryData(sectionKey)
     if (!data) return undefined
     this.removeSection(sectionKey)
     return data
   }
 
-  getSectionGeometryData (sectionKey: string): LegacySectionGeometryData | undefined {
+  getSectionGeometryData(sectionKey: string): LegacySectionGeometryData | undefined {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return undefined
 
@@ -429,19 +524,19 @@ export class GlobalLegacyBuffer {
     return { positions, colors, skyLights, blockLights, uvs, indices, sx, sy, sz }
   }
 
-  removeSection (sectionKey: string): void {
+  removeSection(sectionKey: string): void {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return
 
+    if (this.pendingReplace.has(sectionKey)) {
+      const pr = this.pendingReplace.get(sectionKey)!
+      this.zeroAndFreeSlot(pr.oldStart, pr.oldCount)
+      this.pendingReplace.delete(sectionKey)
+    }
+
     if (this.pendingMove?.key === sectionKey) {
       const { oldStart, count } = this.pendingMove
-      const oldIndexBase = oldStart * INDICES_PER_QUAD
-      const oldIndexLen = count * INDICES_PER_QUAD
-      for (let i = 0; i < oldIndexLen; i++) {
-        this.indices[oldIndexBase + i] = 0
-      }
-      this.markDirty(oldStart, oldStart + count - 1)
-      this.insertFreeSlot({ start: oldStart, count })
+      this.zeroAndFreeSlot(oldStart, count)
       this.pendingMove = null
     }
 
@@ -459,11 +554,11 @@ export class GlobalLegacyBuffer {
     this.layoutVersion++
   }
 
-  hasPendingUploads (): boolean {
+  hasPendingUploads(): boolean {
     return this.pendingRanges.length > 0
   }
 
-  uploadDirtyRange (): void {
+  uploadDirtyRange(): void {
     const r = this.pendingRanges[0]
     if (!r) return
 
@@ -510,15 +605,19 @@ export class GlobalLegacyBuffer {
     indexAttr.addUpdateRange(indexOffset, indexCount)
     indexAttr.needsUpdate = true
 
-    if (quadOffset + quadCount > r.end) this.pendingRanges.shift()
-    else r.start = quadOffset + quadCount
+    if (quadOffset + quadCount > r.end) {
+      this.pendingRanges.shift()
+    } else {
+      r.start = quadOffset + quadCount
+    }
+    this.uploadEpoch++
   }
 
-  setRenderOrigin (renderOrigin: RenderOrigin): void {
+  setRenderOrigin(renderOrigin: RenderOrigin): void {
     this.renderOrigin = { ...renderOrigin }
   }
 
-  rebase (delta: RenderOrigin): void {
+  rebase(delta: RenderOrigin): void {
     if (this.highWatermark === 0) return
     for (const slot of this.sectionSlots.values()) {
       const dstVertBase = slot.start * VERTS_PER_QUAD
@@ -537,7 +636,7 @@ export class GlobalLegacyBuffer {
     this.renderOrigin.z += delta.z
   }
 
-  setCameraOrigin (x: number, y: number, z: number): void {
+  setCameraOrigin(x: number, y: number, z: number): void {
     const { originDelta, cameraOriginFrac } = computeCameraRelativeUniforms(this.renderOrigin, x, y, z)
     const u = this.material.uniforms.u_originDelta
     if (u?.value?.set) u.value.set(originDelta.x, originDelta.y, originDelta.z)
@@ -545,19 +644,11 @@ export class GlobalLegacyBuffer {
     if (uf?.value?.set) uf.value.set(cameraOriginFrac.x, cameraOriginFrac.y, cameraOriginFrac.z)
   }
 
-  raycastSections (
-    raycaster: THREE.Raycaster,
-    sectionKeys: Iterable<string>,
-    out: THREE.Intersection[],
-  ): THREE.Intersection[] {
+  raycastSections(raycaster: THREE.Raycaster, sectionKeys: Iterable<string>, out: THREE.Intersection[]): THREE.Intersection[] {
     const ray = raycaster.ray
     const closest = raycaster.near
     const far = raycaster.far
-    _raycastOrigin.copy(ray.origin).sub(_raycastRenderOrigin.set(
-      this.renderOrigin.x,
-      this.renderOrigin.y,
-      this.renderOrigin.z,
-    ))
+    _raycastOrigin.copy(ray.origin).sub(_raycastRenderOrigin.set(this.renderOrigin.x, this.renderOrigin.y, this.renderOrigin.z))
     _raycastRay.origin.copy(_raycastOrigin)
     _raycastRay.direction.copy(ray.direction)
 
@@ -576,19 +667,14 @@ export class GlobalLegacyBuffer {
         const i2 = this.indices[dstIndexBase + i + 2]!
         if (i0 === i1 && i1 === i2) continue
 
-        const hit = intersectTriangle(
-          _raycastRay,
-          this.positions, this.aOrigin, dstFloatBase,
-          i0, i1, i2,
-          closest, far,
-        )
+        const hit = intersectTriangle(_raycastRay, this.positions, this.aOrigin, dstFloatBase, i0, i1, i2, closest, far)
         if (hit !== null) {
           out.push({
             distance: hit,
             point: ray.at(hit, new THREE.Vector3()),
             object: this.mesh,
             face: null,
-            faceIndex: Math.floor(i / 3),
+            faceIndex: Math.floor(i / 3)
           })
         }
       }
@@ -598,51 +684,53 @@ export class GlobalLegacyBuffer {
     return out
   }
 
-  getHighWatermark (): number {
+  getHighWatermark(): number {
     return this.highWatermark
   }
 
-  getCapacityQuads (): number {
+  getCapacityQuads(): number {
     return this.capacityQuads
   }
 
-  getSectionCount (): number {
+  getSectionCount(): number {
     return this.sectionSlots.size
   }
 
-  getMemoryBytes (): number {
+  getMemoryBytes(): number {
     return this.capacityQuads * LEGACY_BYTES_PER_QUAD
   }
 
-  getUsedMemoryBytes (): number {
+  getUsedMemoryBytes(): number {
     return this.highWatermark * LEGACY_BYTES_PER_QUAD
   }
 
-  reset (): void {
+  reset(): void {
     this.sectionSlots.clear()
     this.freeList.length = 0
     this.highWatermark = 0
     this.pendingRanges.length = 0
     this.pendingMove = null
+    this.pendingReplace.clear()
+    this.uploadEpoch = 0
     this.visibleIndexSpans = []
     this.syncDefaultDrawGroups()
   }
 
-  dispose (): void {
+  dispose(): void {
     this.mesh.parent?.remove(this.mesh)
     this.mesh.geometry.dispose()
     this.reset()
   }
 
-  private markDirty (start: number, end: number): void {
+  private markDirty(start: number, end: number): void {
     this.pendingRanges.push({ start, end })
     this.pendingRanges.sort((a, b) => a.start - b.start)
     this.mergePendingRanges()
   }
 
-  private mergePendingRanges (): void {
+  private mergePendingRanges(): void {
     if (this.pendingRanges.length < 2) return
-    const merged: Array<{ start: number, end: number }> = []
+    const merged: Array<{ start: number; end: number }> = []
     let cur = this.pendingRanges[0]!
     for (let i = 1; i < this.pendingRanges.length; i++) {
       const next = this.pendingRanges[i]!
@@ -657,7 +745,7 @@ export class GlobalLegacyBuffer {
     this.pendingRanges = merged
   }
 
-  private takeFreeSlot (count: number): { start: number, count: number } | undefined {
+  private takeFreeSlot(count: number): { start: number; count: number } | undefined {
     for (let i = 0; i < this.freeList.length; i++) {
       const slot = this.freeList[i]!
       if (slot.count >= count) {
@@ -671,15 +759,15 @@ export class GlobalLegacyBuffer {
     return undefined
   }
 
-  private insertFreeSlot (slot: { start: number, count: number }): void {
+  private insertFreeSlot(slot: { start: number; count: number }): void {
     this.freeList.push(slot)
     this.freeList.sort((a, b) => a.start - b.start)
     this.mergeFreeList()
   }
 
-  private mergeFreeList (): void {
+  private mergeFreeList(): void {
     if (this.freeList.length < 2) return
-    const merged: Array<{ start: number, count: number }> = []
+    const merged: Array<{ start: number; count: number }> = []
     let cur = this.freeList[0]!
     for (let i = 1; i < this.freeList.length; i++) {
       const next = this.freeList[i]!
@@ -694,7 +782,7 @@ export class GlobalLegacyBuffer {
     this.freeList = merged
   }
 
-  private shrinkHighWatermark (): void {
+  private shrinkHighWatermark(): void {
     while (this.highWatermark > 0) {
       const tail = this.highWatermark - 1
       const free = this.freeList.find(s => s.start <= tail && s.start + s.count > tail)
@@ -705,7 +793,7 @@ export class GlobalLegacyBuffer {
     }
   }
 
-  private interiorFreeQuads (): number {
+  private interiorFreeQuads(): number {
     let total = 0
     for (const slot of this.freeList) {
       if (slot.start < this.highWatermark) total += slot.count
@@ -713,8 +801,8 @@ export class GlobalLegacyBuffer {
     return total
   }
 
-  private findMovableSection (maxCount: number): { key: string, start: number, count: number } | undefined {
-    const sections: Array<{ key: string, start: number, count: number }> = []
+  private findMovableSection(maxCount: number): { key: string; start: number; count: number } | undefined {
+    const sections: Array<{ key: string; start: number; count: number }> = []
     for (const [key, slot] of this.sectionSlots) {
       sections.push({ key, start: slot.start, count: slot.count })
     }
@@ -722,7 +810,7 @@ export class GlobalLegacyBuffer {
 
     sections.sort((a, b) => {
       if (b.start !== a.start) return b.start - a.start
-      return (b.start + b.count) - (a.start + a.count)
+      return b.start + b.count - (a.start + a.count)
     })
 
     const tailmost = sections[0]!
@@ -730,9 +818,7 @@ export class GlobalLegacyBuffer {
       return tailmost
     }
 
-    const candidates = sections
-      .filter(s => s.count <= maxCount)
-      .sort((a, b) => b.count - a.count)
+    const candidates = sections.filter(s => s.count <= maxCount).sort((a, b) => b.count - a.count)
 
     for (const s of candidates) {
       if (this.findLowestInteriorHole(s.start, s.count)) return s
@@ -740,10 +826,7 @@ export class GlobalLegacyBuffer {
     return undefined
   }
 
-  private findLowestInteriorHole (
-    sectionStart: number,
-    count: number,
-  ): { start: number, count: number, index: number } | undefined {
+  private findLowestInteriorHole(sectionStart: number, count: number): { start: number; count: number; index: number } | undefined {
     for (let i = 0; i < this.freeList.length; i++) {
       const slot = this.freeList[i]!
       if (slot.start < sectionStart && slot.count >= count) {
@@ -753,7 +836,7 @@ export class GlobalLegacyBuffer {
     return undefined
   }
 
-  private reserveFreeSlotAt (index: number, count: number): { start: number, count: number } {
+  private reserveFreeSlotAt(index: number, count: number): { start: number; count: number } {
     const slot = this.freeList[index]!
     this.freeList.splice(index, 1)
     if (slot.count === count) return { start: slot.start, count }
@@ -762,7 +845,7 @@ export class GlobalLegacyBuffer {
     return used
   }
 
-  private copySectionRange (oldStart: number, newStart: number, quadCount: number): void {
+  private copySectionRange(oldStart: number, newStart: number, quadCount: number): void {
     const oldVertBase = oldStart * VERTS_PER_QUAD
     const newVertBase = newStart * VERTS_PER_QUAD
     const vertCount = quadCount * VERTS_PER_QUAD
@@ -794,35 +877,53 @@ export class GlobalLegacyBuffer {
     }
   }
 
-  private rangeFullyUploaded (start: number, end: number): boolean {
+  private rangeFullyUploaded(start: number, end: number): boolean {
     for (const r of this.pendingRanges) {
       if (r.start <= end && r.end >= start) return false
     }
     return true
   }
 
-  private finalizePendingMove (): void {
-    const move = this.pendingMove
-    if (!move) return
-
-    const { oldStart, count } = move
-    const oldIndexBase = oldStart * INDICES_PER_QUAD
+  private zeroAndFreeSlot(start: number, count: number): void {
+    const oldIndexBase = start * INDICES_PER_QUAD
     const oldIndexLen = count * INDICES_PER_QUAD
     for (let i = 0; i < oldIndexLen; i++) {
       this.indices[oldIndexBase + i] = 0
     }
-    this.insertFreeSlot({ start: oldStart, count })
+    this.markDirty(start, start + count - 1)
+    this.insertFreeSlot({ start, count })
+  }
+
+  private finalizePendingReplace(key: string): void {
+    const pr = this.pendingReplace.get(key)
+    if (!pr) return
+
+    this.zeroAndFreeSlot(pr.oldStart, pr.oldCount)
+    this.pendingReplace.delete(key)
+    this.shrinkHighWatermark()
+    this.syncDefaultDrawGroups()
+    this.layoutVersion++
+    this.uploadEpoch++
+  }
+
+  private finalizePendingMove(): void {
+    const move = this.pendingMove
+    if (!move) return
+
+    const { oldStart, count } = move
+    this.zeroAndFreeSlot(oldStart, count)
     this.shrinkHighWatermark()
-    if (oldStart < this.highWatermark) {
-      this.markDirty(oldStart, oldStart + count - 1)
-    }
     this.syncDefaultDrawGroups()
     this.pendingMove = null
     this.layoutVersion++
+    this.uploadEpoch++
   }
 
-  private growCapacity (minQuads: number): void {
+  private growCapacity(minQuads: number): void {
     if (this.pendingMove) this.finalizePendingMove()
+    for (const key of [...this.pendingReplace.keys()]) {
+      this.finalizePendingReplace(key)
+    }
 
     let newCap = this.capacityQuads
     while (newCap < minQuads) newCap += this.growthIncrementQuads
@@ -890,22 +991,12 @@ const _raycastOrigin = new THREE.Vector3()
 const _raycastRenderOrigin = new THREE.Vector3()
 const _raycastRay = new THREE.Ray()
 
-function readWorldVertex (
-  positions: Float32Array,
-  aOrigin: Float32Array,
-  floatBase: number,
-  vertIndex: number,
-  target: THREE.Vector3,
-): void {
+function readWorldVertex(positions: Float32Array, aOrigin: Float32Array, floatBase: number, vertIndex: number, target: THREE.Vector3): void {
   const f = floatBase + vertIndex * FLOATS_PER_VERT
-  target.set(
-    aOrigin[f]! + positions[f]!,
-    aOrigin[f + 1]! + positions[f + 1]!,
-    aOrigin[f + 2]! + positions[f + 2]!,
-  )
+  target.set(aOrigin[f]! + positions[f]!, aOrigin[f + 1]! + positions[f + 1]!, aOrigin[f + 2]! + positions[f + 2]!)
 }
 
-function intersectTriangle (
+function intersectTriangle(
   ray: THREE.Ray,
   positions: Float32Array,
   aOrigin: Float32Array,
@@ -914,7 +1005,7 @@ function intersectTriangle (
   i1: number,
   i2: number,
   near: number,
-  far: number,
+  far: number
 ): number | null {
   readWorldVertex(positions, aOrigin, floatBase, i0, _vA)
   readWorldVertex(positions, aOrigin, floatBase, i1, _vB)
@@ -935,7 +1026,7 @@ function intersectTriangle (
   return t
 }
 
-function pointInTriangle (p: THREE.Vector3, a: THREE.Vector3, b: THREE.Vector3, c: THREE.Vector3): boolean {
+function pointInTriangle(p: THREE.Vector3, a: THREE.Vector3, b: THREE.Vector3, c: THREE.Vector3): boolean {
   _edge1.subVectors(b, a)
   _edge2.subVectors(c, a)
   const n = _normal.crossVectors(_edge1, _edge2).normalize()