minecraft-renderer 0.1.65 → 0.1.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "The most Modular Minecraft world renderer with Three.js WebGL backend",
   "type": "module",
   "main": "./dist/index.js",

package/src/three/globalBlockBuffer.ts

@@ -3,9 +3,16 @@ import * as THREE from 'three'
 import { VERTICES_PER_FACE } from './shaders/cubeBlockShader'
 import { packWord2Empty } from '../wasm-mesher/bridge/shaderCubeBridge'
 
-const INITIAL_CAPACITY_FACES = 2_000_000
+// Linear growth (NOT doubling) to keep iOS allocation spikes bounded to one increment.
+// Reference: prismarine-web-client PR #90 (webgl) and #120 (webgpu) both grow by +1M faces.
+const INITIAL_CAPACITY_FACES = 512_000      // ~8 MB up front (4 words × 4 B), well under 1M
+const GROWTH_INCREMENT_FACES = 1_000_000    // +16 MB per growth step instead of doubling
+const MAX_UPLOAD_FACES_PER_FRAME = 15_000   // face-indexed budget (chunksStorage uses 10k blocks)
+const FRAGMENTATION_THRESHOLD = 0.25
 const EMPTY_W2 = packWord2Empty()
 
+type PendingMove = { key: string, oldStart: number, newStart: number, count: number }
+
 export type GlobalBlockBufferShaderData = {
   words: Uint32Array
   count: number
@@ -26,8 +33,8 @@ export class GlobalBlockBuffer {
   private readonly sectionSlots = new Map<string, { start: number, count: number }>()
   private freeList: Array<{ start: number, count: number }> = []
   private highWatermark = 0
-  private dirtyMin = Infinity
-  private dirtyMax = -1
+  private pendingRanges: Array<{ start: number, end: number }> = []
+  private pendingMove: PendingMove | null = null
 
   constructor (
     material: THREE.ShaderMaterial,
@@ -38,6 +45,7 @@ export class GlobalBlockBuffer {
     this.w1 = new Uint32Array(this.capacityFaces)
     this.w2 = new Uint32Array(this.capacityFaces)
     this.w3 = new Uint32Array(this.capacityFaces)
+    this.w2.fill(EMPTY_W2)
 
     const geometry = new THREE.InstancedBufferGeometry()
     const positions = new Float32Array(VERTICES_PER_FACE * 3)
@@ -138,6 +146,19 @@ export class GlobalBlockBuffer {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return
 
+    if (this.pendingMove?.key === sectionKey) {
+      const { oldStart, count } = this.pendingMove
+      for (let i = oldStart; i < oldStart + count; i++) {
+        this.w0[i] = 0
+        this.w1[i] = 0
+        this.w2[i] = EMPTY_W2
+        this.w3[i] = 0
+      }
+      this.markDirty(oldStart, oldStart + count - 1)
+      this.insertFreeSlot({ start: oldStart, count })
+      this.pendingMove = null
+    }
+
     for (let i = slot.start; i < slot.start + slot.count; i++) {
       this.w0[i] = 0
       this.w1[i] = 0
@@ -152,11 +173,42 @@ export class GlobalBlockBuffer {
     this.mesh.geometry.instanceCount = this.highWatermark
   }
 
+  /** One interior-hole move per frame when fragmentation exceeds threshold; deferred shrink. */
+  compactStep (): void {
+    if (this.pendingMove) {
+      const { newStart, count } = this.pendingMove
+      if (this.rangeFullyUploaded(newStart, newStart + count - 1)) {
+        this.finalizePendingMove()
+      }
+      return
+    }
+
+    if (this.highWatermark === 0) return
+    const interiorFree = this.interiorFreeFaces()
+    if (interiorFree / this.highWatermark <= FRAGMENTATION_THRESHOLD) return
+
+    const section = this.findMovableSection(MAX_UPLOAD_FACES_PER_FRAME)
+    if (!section) return
+
+    const hole = this.findLowestInteriorHole(section.start, section.count)
+    if (!hole) return
+
+    const reserved = this.reserveFreeSlotAt(hole.index, section.count)
+    const oldStart = section.start
+    const newStart = reserved.start
+
+    this.copySectionRange(oldStart, newStart, section.count)
+    this.sectionSlots.set(section.key, { start: newStart, count: section.count })
+    this.markDirty(newStart, newStart + section.count - 1)
+    this.pendingMove = { key: section.key, oldStart, newStart, count: section.count }
+  }
+
   uploadDirtyRange (): void {
-    if (this.dirtyMin > this.dirtyMax) return
+    const r = this.pendingRanges[0]
+    if (!r) return
 
-    const offset = this.dirtyMin
-    const count = this.dirtyMax - this.dirtyMin + 1
+    const offset = r.start
+    const count = Math.min(r.end - r.start + 1, MAX_UPLOAD_FACES_PER_FRAME)
     const geometry = this.mesh.geometry
 
     for (const name of ['a_w0', 'a_w1', 'a_w2', 'a_w3'] as const) {
@@ -166,8 +218,8 @@ export class GlobalBlockBuffer {
       attr.needsUpdate = true
     }
 
-    this.dirtyMin = Infinity
-    this.dirtyMax = -1
+    if (offset + count > r.end) this.pendingRanges.shift()
+    else r.start = offset + count
   }
 
   setCameraOrigin (x: number, y: number, z: number): void {
@@ -189,8 +241,8 @@ export class GlobalBlockBuffer {
     this.sectionSlots.clear()
     this.freeList.length = 0
     this.highWatermark = 0
-    this.dirtyMin = Infinity
-    this.dirtyMax = -1
+    this.pendingRanges.length = 0
+    this.pendingMove = null
     this.w0.fill(0)
     this.w1.fill(0)
     this.w2.fill(EMPTY_W2)
@@ -205,8 +257,26 @@ export class GlobalBlockBuffer {
   }
 
   private markDirty (start: number, end: number): void {
-    if (start < this.dirtyMin) this.dirtyMin = start
-    if (end > this.dirtyMax) this.dirtyMax = end
+    this.pendingRanges.push({ start, end })
+    this.pendingRanges.sort((a, b) => a.start - b.start)
+    this.mergePendingRanges()
+  }
+
+  private mergePendingRanges (): void {
+    if (this.pendingRanges.length < 2) return
+    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]!
+      if (next.start <= cur.end + 1) {
+        cur = { start: cur.start, end: Math.max(cur.end, next.end) }
+      } else {
+        merged.push(cur)
+        cur = next
+      }
+    }
+    merged.push(cur)
+    this.pendingRanges = merged
   }
 
   private takeFreeSlot (count: number): { start: number, count: number } | undefined {
@@ -246,6 +316,97 @@ export class GlobalBlockBuffer {
     this.freeList = merged
   }
 
+  private interiorFreeFaces (): number {
+    let total = 0
+    for (const slot of this.freeList) {
+      if (slot.start < this.highWatermark) total += slot.count
+    }
+    return total
+  }
+
+  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 })
+    }
+    if (sections.length === 0) return undefined
+
+    sections.sort((a, b) => {
+      if (b.start !== a.start) return b.start - a.start
+      return (b.start + b.count) - (a.start + a.count)
+    })
+
+    const tailmost = sections[0]!
+    if (tailmost.count <= maxCount && this.findLowestInteriorHole(tailmost.start, tailmost.count)) {
+      return tailmost
+    }
+
+    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
+    }
+    return 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) {
+        return { start: slot.start, count: slot.count, index: i }
+      }
+    }
+    return undefined
+  }
+
+  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 }
+    const used = { start: slot.start, count }
+    this.insertFreeSlot({ start: slot.start + count, count: slot.count - count })
+    return used
+  }
+
+  private copySectionRange (oldStart: number, newStart: number, count: number): void {
+    this.w0.copyWithin(newStart, oldStart, oldStart + count)
+    this.w1.copyWithin(newStart, oldStart, oldStart + count)
+    this.w2.copyWithin(newStart, oldStart, oldStart + count)
+    this.w3.copyWithin(newStart, oldStart, oldStart + count)
+  }
+
+  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
+    for (let i = oldStart; i < oldStart + count; i++) {
+      this.w0[i] = 0
+      this.w1[i] = 0
+      this.w2[i] = EMPTY_W2
+      this.w3[i] = 0
+    }
+    this.insertFreeSlot({ start: oldStart, count })
+    this.shrinkHighWatermark()
+    if (oldStart < this.highWatermark) {
+      this.markDirty(oldStart, oldStart + count - 1)
+    }
+    this.mesh.geometry.instanceCount = this.highWatermark
+    this.pendingMove = null
+  }
+
   private shrinkHighWatermark (): void {
     while (this.highWatermark > 0) {
       const tail = this.highWatermark - 1
@@ -258,8 +419,13 @@ export class GlobalBlockBuffer {
   }
 
   private growCapacity (minFaces: number): void {
+    // Moved CPU data at newStart survives nw*.set(); pendingRanges cleared below anyway.
+    if (this.pendingMove) this.finalizePendingMove()
+
+    console.warn('[globalBlockBuffer] growing faces', this.capacityFaces, '->', '(need', minFaces, ')')
     let newCap = this.capacityFaces
-    while (newCap < minFaces) newCap *= 2
+    while (newCap < minFaces) newCap += GROWTH_INCREMENT_FACES
+    console.warn('[globalBlockBuffer] growing faces', this.capacityFaces, '->', newCap)
 
     const nw0 = new Uint32Array(newCap)
     const nw1 = new Uint32Array(newCap)
@@ -295,7 +461,6 @@ export class GlobalBlockBuffer {
     mkAttr(this.w2, 'a_w2')
     mkAttr(this.w3, 'a_w3')
 
-    this.dirtyMin = 0
-    this.dirtyMax = this.highWatermark - 1
+    this.pendingRanges.length = 0
   }
 }

package/src/three/worldRendererThree.ts

@@ -1284,6 +1284,7 @@ export class WorldRendererThree extends WorldRendererCommon {
     const globalBuffer = this.chunkMeshManager.globalBlockBuffer
     if (globalBuffer) {
       globalBuffer.setCameraOrigin(this.cameraWorldPos.x, this.cameraWorldPos.y, this.cameraWorldPos.z)
+      globalBuffer.compactStep()
       globalBuffer.uploadDirtyRange()
     }
     this.renderer.render(this.scene, cam)

package/src/wasm-mesher/tests/shaderCubeInstances.test.ts

@@ -359,6 +359,325 @@ test('GlobalBlockBuffer: free-list reuses slot with EMPTY sentinel', () => {
   mat.dispose()
 })
 
+type BufferInternals = {
+  pendingRanges: Array<{ start: number, end: number }>
+  pendingMove: { key: string, oldStart: number, newStart: number, count: number } | null
+}
+
+/** True if some queued (not-yet-uploaded) dirty range covers [start, end] — i.e. it WILL hit the GPU. */
+function rangeQueuedForUpload (buffer: GlobalBlockBuffer, start: number, end: number): boolean {
+  return getBufferInternals(buffer).pendingRanges.some(r => r.start <= end && r.end >= start)
+}
+
+function getBufferInternals (buffer: GlobalBlockBuffer): BufferInternals {
+  return buffer as unknown as BufferInternals
+}
+
+function drainAllUploads (buffer: GlobalBlockBuffer): void {
+  while (getBufferInternals(buffer).pendingRanges.length) buffer.uploadDirtyRange()
+}
+
+function makeSectionWords (faceW0: number[]): Uint32Array {
+  const words = new Uint32Array(faceW0.length * 4)
+  for (let i = 0; i < faceW0.length; i++) {
+    words[i * 4] = faceW0[i]!
+    words[i * 4 + 1] = 0
+    words[i * 4 + 2] = 0
+    words[i * 4 + 3] = packWord3(0, 0)
+  }
+  return words
+}
+
+function readSectionFaceWords (buffer: GlobalBlockBuffer, key: string): number[] {
+  const slot = buffer.getSectionSlot(key)
+  if (!slot) throw new Error(`missing section ${key}`)
+  const geo = buffer.mesh.geometry
+  const w0 = (geo.getAttribute('a_w0') as THREE.InstancedBufferAttribute).array as Uint32Array
+  const w1 = (geo.getAttribute('a_w1') as THREE.InstancedBufferAttribute).array as Uint32Array
+  const w2 = (geo.getAttribute('a_w2') as THREE.InstancedBufferAttribute).array as Uint32Array
+  const w3 = (geo.getAttribute('a_w3') as THREE.InstancedBufferAttribute).array as Uint32Array
+  const out: number[] = []
+  for (let i = 0; i < slot.count; i++) {
+    const idx = slot.start + i
+    out.push(w0[idx]!, w1[idx]!, w2[idx]!, w3[idx]!)
+  }
+  return out
+}
+
+function finishCurrentMove (buffer: GlobalBlockBuffer): void {
+  drainAllUploads(buffer)
+  buffer.compactStep()
+}
+
+function isEmptyFace (buffer: GlobalBlockBuffer, index: number): boolean {
+  const w2 = (buffer.mesh.geometry.getAttribute('a_w2') as THREE.InstancedBufferAttribute).array as Uint32Array
+  return (w2[index]! & (1 << WORD2.EMPTY_SHIFT)) !== 0
+}
+
+test('GlobalBlockBuffer: compaction lowers watermark after interior-hole churn', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('a', makeSectionWords([10]), 1)
+  buffer.addSection('b', makeSectionWords([20]), 1)
+  buffer.addSection('c', makeSectionWords([30]), 1)
+  expect(buffer.mesh.geometry.instanceCount).toBe(3)
+
+  buffer.removeSection('b')
+  drainAllUploads(buffer)
+  expect(buffer.mesh.geometry.instanceCount).toBe(3)
+
+  buffer.compactStep()
+  finishCurrentMove(buffer)
+
+  expect(buffer.mesh.geometry.instanceCount).toBe(2)
+  expect(buffer.getSectionSlot('c')).toEqual({ start: 1, count: 1 })
+  expect(readSectionFaceWords(buffer, 'c')[0]).toBe(30)
+  expect(readSectionFaceWords(buffer, 'a')[0]).toBe(10)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: compaction preserves surviving section data', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('a', makeSectionWords([11, 12]), 2)
+  buffer.addSection('b', makeSectionWords([21]), 1)
+  buffer.addSection('c', makeSectionWords([31, 32, 33]), 3)
+  const expectedA = readSectionFaceWords(buffer, 'a')
+  const expectedC = readSectionFaceWords(buffer, 'c')
+
+  buffer.removeSection('b')
+  drainAllUploads(buffer)
+  buffer.compactStep()
+  finishCurrentMove(buffer)
+
+  expect(readSectionFaceWords(buffer, 'a')).toEqual(expectedA)
+  expect(readSectionFaceWords(buffer, 'c')).toEqual(expectedC)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: compaction defers instanceCount shrink until upload completes', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('a', makeSectionWords([10]), 1)
+  buffer.addSection('b', makeSectionWords([20]), 1)
+  buffer.addSection('c', makeSectionWords([30]), 1)
+  buffer.removeSection('b')
+  drainAllUploads(buffer)
+
+  buffer.compactStep()
+  expect(getBufferInternals(buffer).pendingMove).not.toBeNull()
+  expect(buffer.mesh.geometry.instanceCount).toBe(3)
+
+  finishCurrentMove(buffer)
+  expect(getBufferInternals(buffer).pendingMove).toBeNull()
+  expect(buffer.mesh.geometry.instanceCount).toBe(2)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: compaction runs one move at a time', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('a', makeSectionWords([10]), 1)
+  buffer.addSection('b', makeSectionWords([20]), 1)
+  buffer.addSection('c', makeSectionWords([30]), 1)
+  buffer.addSection('d', makeSectionWords([40]), 1)
+  buffer.addSection('e', makeSectionWords([50]), 1)
+  buffer.removeSection('b')
+  buffer.removeSection('d')
+  drainAllUploads(buffer)
+
+  buffer.compactStep()
+  const moveAfterFirst = getBufferInternals(buffer).pendingMove
+  expect(moveAfterFirst).not.toBeNull()
+
+  buffer.compactStep()
+  expect(getBufferInternals(buffer).pendingMove).toEqual(moveAfterFirst)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: compaction skips when fragmentation is below threshold', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('a', makeSectionWords([10]), 1)
+  buffer.addSection('b', makeSectionWords([20]), 1)
+  buffer.addSection('c', makeSectionWords([30]), 1)
+  buffer.addSection('d', makeSectionWords([40]), 1)
+  buffer.removeSection('b')
+  drainAllUploads(buffer)
+  expect(buffer.mesh.geometry.instanceCount).toBe(4)
+
+  buffer.compactStep()
+  expect(getBufferInternals(buffer).pendingMove).toBeNull()
+  expect(buffer.mesh.geometry.instanceCount).toBe(4)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: interior-fallback move uploads EMPTY over old slot still in draw range', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  // A[0,2) B[2,2) C[4,3) — remove A; C (count 3) cannot fit hole [0,2), so B moves down.
+  buffer.addSection('a', makeSectionWords([10, 11]), 2)
+  buffer.addSection('b', makeSectionWords([20, 21]), 2)
+  buffer.addSection('c', makeSectionWords([30, 31, 32]), 3)
+  expect(buffer.mesh.geometry.instanceCount).toBe(7)
+
+  buffer.removeSection('a')
+  drainAllUploads(buffer)
+
+  buffer.compactStep()
+  expect(getBufferInternals(buffer).pendingMove?.key).toBe('b')
+  expect(getBufferInternals(buffer).pendingMove?.oldStart).toBe(2)
+  finishCurrentMove(buffer)
+
+  // Guards the High fix: the vacated old slot [2,3] is still inside the draw range, so it MUST be
+  // queued for GPU upload (markDirty). Checking isEmptyFace alone is insufficient — the CPU-backed
+  // attribute array is cleared regardless; only the pending upload range proves the GPU is told.
+  expect(rangeQueuedForUpload(buffer, 2, 3)).toBe(true)
+
+  expect(buffer.mesh.geometry.instanceCount).toBe(7)
+  expect(buffer.getSectionSlot('b')).toEqual({ start: 0, count: 2 })
+  expect(readSectionFaceWords(buffer, 'b')[0]).toBe(20)
+  expect(isEmptyFace(buffer, 2)).toBe(true)
+  expect(isEmptyFace(buffer, 3)).toBe(true)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: removeSection during pending move clears old GPU copy', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('a', makeSectionWords([10]), 1)
+  buffer.addSection('b', makeSectionWords([20]), 1)
+  buffer.addSection('c', makeSectionWords([30]), 1)
+  buffer.removeSection('b')
+  drainAllUploads(buffer)
+
+  buffer.compactStep()
+  expect(getBufferInternals(buffer).pendingMove?.key).toBe('c')
+
+  buffer.removeSection('c')
+  expect(getBufferInternals(buffer).pendingMove).toBeNull()
+  // The in-flight old copy at index 2 must be queued for upload, not just cleared in CPU memory.
+  expect(rangeQueuedForUpload(buffer, 2, 2)).toBe(true)
+  drainAllUploads(buffer)
+
+  expect(buffer.hasSection('c')).toBe(false)
+  expect(isEmptyFace(buffer, 2)).toBe(true)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: takeSectionData during pending move clears old GPU copy', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('a', makeSectionWords([10, 11]), 2)
+  buffer.addSection('b', makeSectionWords([20, 21]), 2)
+  buffer.addSection('c', makeSectionWords([30, 31, 32]), 3)
+  buffer.removeSection('a')
+  drainAllUploads(buffer)
+
+  buffer.compactStep()
+  expect(getBufferInternals(buffer).pendingMove?.key).toBe('b')
+
+  const taken = buffer.takeSectionData('b')
+  expect(taken?.words[0]).toBe(20)
+  expect(taken?.words[4]).toBe(21)
+  expect(getBufferInternals(buffer).pendingMove).toBeNull()
+  // The in-flight old copy at [2,3] must be queued for upload, not just cleared in CPU memory.
+  expect(rangeQueuedForUpload(buffer, 2, 3)).toBe(true)
+  drainAllUploads(buffer)
+
+  expect(buffer.hasSection('b')).toBe(false)
+  expect(isEmptyFace(buffer, 2)).toBe(true)
+  expect(isEmptyFace(buffer, 3)).toBe(true)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: takeSectionData reads relocated section slot', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  const cWords = makeSectionWords([30, 31])
+  buffer.addSection('a', makeSectionWords([10]), 1)
+  buffer.addSection('b', makeSectionWords([20]), 1)
+  buffer.addSection('c', cWords, 2)
+  buffer.removeSection('b')
+  drainAllUploads(buffer)
+  buffer.compactStep()
+  finishCurrentMove(buffer)
+
+  const taken = buffer.takeSectionData('c')
+  expect(taken?.count).toBe(2)
+  expect(taken?.words[0]).toBe(30)
+  expect(taken?.words[4]).toBe(31)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: uploadDirtyRange budgets large dirty span across frames', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  const faceCount = 20_000
+  const words = new Uint32Array(faceCount * 4)
+  for (let i = 0; i < faceCount; i++) {
+    const src = i * 4
+    words[src] = i + 1
+    words[src + 1] = 0
+    words[src + 2] = 0
+    words[src + 3] = packWord3(0, 0)
+  }
+  buffer.addSection('big', words, faceCount)
+
+  const w0Attr = buffer.mesh.geometry.getAttribute('a_w0') as THREE.InstancedBufferAttribute
+  buffer.uploadDirtyRange()
+  expect(w0Attr.updateRange.offset).toBe(0)
+  expect(w0Attr.updateRange.count).toBe(15_000)
+
+  buffer.uploadDirtyRange()
+  expect(w0Attr.updateRange.offset).toBe(15_000)
+  expect(w0Attr.updateRange.count).toBe(5_000)
+
+  buffer.uploadDirtyRange()
+  expect((buffer as unknown as { pendingRanges: unknown[] }).pendingRanges).toHaveLength(0)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
 test('getShaderCubeResources: returns null without loadedData.tints (no throw)', () => {
   const prev = (globalThis as any).loadedData
   ;(globalThis as any).loadedData = {}