minecraft-renderer 0.1.72 → 0.1.74

package/src/three/tests/chunkMeshManagerLegacy.test.ts

@@ -0,0 +1,286 @@
+//@ts-nocheck
+import { test, expect, vi } from 'vitest'
+import * as THREE from 'three'
+
+vi.mock('../entity/EntityMesh', () => ({
+  getMesh: vi.fn(),
+}))
+
+import { ChunkMeshManager } from '../chunkMeshManager'
+import type { WorldRendererThree } from '../worldRendererThree'
+import type { MesherGeometryOutput } from '../../mesher-shared/shared'
+
+function makeQuadArrays () {
+  const positions = new Float32Array([
+    -1, -1, -1,
+    -1, 1, -1,
+    -1, 1, 1,
+    -1, -1, 1,
+  ])
+  const colors = new Float32Array(12).fill(1)
+  const skyLights = new Float32Array(4).fill(1)
+  const blockLights = new Float32Array(4).fill(0)
+  const uvs = new Float32Array([0, 0, 1, 0, 1, 1, 0, 1])
+  const indices = new Uint32Array([0, 1, 2, 0, 2, 3])
+  return { positions, colors, skyLights, blockLights, uvs, indices }
+}
+
+function makeBlendOnlyGeometry (): MesherGeometryOutput {
+  const blend = makeQuadArrays()
+  return {
+    sectionYNumber: 0,
+    chunkKey: '0,0',
+    sectionStartY: 0,
+    sectionEndY: 16,
+    sectionStartX: 0,
+    sectionEndX: 16,
+    sectionStartZ: 0,
+    sectionEndZ: 16,
+    sx: 8,
+    sy: 8,
+    sz: 8,
+    positions: new Float32Array(0),
+    normals: new Float32Array(0),
+    colors: new Float32Array(0),
+    skyLights: new Float32Array(0),
+    blockLights: new Float32Array(0),
+    uvs: new Float32Array(0),
+    indices: new Uint32Array(0),
+    indicesCount: 0,
+    using32Array: true,
+    tiles: {},
+    heads: {},
+    signs: {},
+    banners: {},
+    hadErrors: false,
+    blocksCount: 1,
+    blend: {
+      positions: blend.positions,
+      normals: new Float32Array(12),
+      colors: blend.colors,
+      skyLights: blend.skyLights,
+      blockLights: blend.blockLights,
+      uvs: blend.uvs,
+      indices: blend.indices,
+    },
+  }
+}
+
+function makeMixedGeometry (): MesherGeometryOutput {
+  const opaque = makeQuadArrays()
+  const blend = makeQuadArrays()
+  return {
+    sectionYNumber: 0,
+    chunkKey: '0,0',
+    sectionStartY: 0,
+    sectionEndY: 16,
+    sectionStartX: 0,
+    sectionEndX: 16,
+    sectionStartZ: 0,
+    sectionEndZ: 16,
+    sx: 8,
+    sy: 8,
+    sz: 8,
+    positions: opaque.positions,
+    normals: new Float32Array(12),
+    colors: opaque.colors,
+    skyLights: opaque.skyLights,
+    blockLights: opaque.blockLights,
+    uvs: opaque.uvs,
+    indices: opaque.indices,
+    indicesCount: 6,
+    using32Array: true,
+    tiles: {},
+    heads: {},
+    signs: {},
+    banners: {},
+    hadErrors: false,
+    blocksCount: 2,
+    blend: {
+      positions: blend.positions,
+      normals: new Float32Array(12),
+      colors: blend.colors,
+      skyLights: blend.skyLights,
+      blockLights: blend.blockLights,
+      uvs: blend.uvs,
+      indices: blend.indices,
+    },
+  }
+}
+
+function makeInvalidBlendGeometry (): MesherGeometryOutput {
+  const geo = makeBlendOnlyGeometry()
+  const blend = geo.blend!
+  return {
+    ...geo,
+    blend: {
+      ...blend,
+      positions: new Float32Array([0, 0, 0, 1, 0, 0, 2, 0, 0]),
+      indices: new Uint32Array([0, 1, 2, 0, 2, 1, 3]),
+    },
+  }
+}
+
+type ManagerOptions = {
+  revealDefer?: boolean
+}
+
+function createManager (opts: ManagerOptions = {}): ChunkMeshManager {
+  const scene = new THREE.Scene()
+  const material = new THREE.MeshBasicMaterial()
+  const revealModule = opts.revealDefer
+    ? {
+      shouldDeferSectionGeometry: () => true,
+    }
+    : undefined
+  const worldRenderer = {
+    shaderCubeBlocksEnabled: () => false,
+    getModule: (name: string) => (name === 'futuristicReveal' ? revealModule : undefined),
+    sceneOrigin: {
+      track: () => {},
+      removeAndUntrack: () => {},
+      removeAndUntrackAll: () => {},
+    },
+    blockEntities: {},
+    worldRendererConfig: {},
+  } as unknown as WorldRendererThree
+  return new ChunkMeshManager(worldRenderer, scene, material, 256, 1)
+}
+
+test('ChunkMeshManager: blend section routes to global blend buffer', () => {
+  const manager = createManager()
+  const key = '0,0,0'
+  const geo = makeBlendOnlyGeometry()
+
+  manager.updateSection(key, geo)
+
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key)).toBe(true)
+  expect(manager.sectionObjects[key]?.hasBlendMesh).toBe(false)
+  expect(manager.sectionUsesPooledLegacyMesh(key)).toBe(false)
+
+  manager.cleanupSection(key)
+  manager.dispose()
+})
+
+test('ChunkMeshManager: cleanup removes blend from global buffer', () => {
+  const manager = createManager()
+  const key = '0,0,0'
+  manager.updateSection(key, makeBlendOnlyGeometry())
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key)).toBe(true)
+
+  manager.cleanupSection(key)
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key)).toBe(false)
+
+  manager.dispose()
+})
+
+test('ChunkMeshManager: hidden section excluded from draw spans', () => {
+  const manager = createManager()
+  const key = '0,0,0'
+  manager.updateSection(key, makeBlendOnlyGeometry())
+  const section = manager.sectionObjects[key]!
+  section.visible = false
+
+  const camera = new THREE.PerspectiveCamera(60, 1, 0.1, 1000)
+  camera.position.set(8, 8, 20)
+  camera.lookAt(8, 8, 8)
+  camera.updateMatrixWorld()
+
+  manager.updateSectionCullAndSort(camera, 8, 8, 20)
+  expect(manager.globalLegacyBlendBuffer?.mesh.geometry.groups.length).toBe(0)
+
+  section.visible = true
+  manager.updateSectionCullAndSort(camera, 8, 8, 20)
+  expect(manager.globalLegacyBlendBuffer?.mesh.geometry.groups.length).toBeGreaterThan(0)
+
+  manager.cleanupSection(key)
+  manager.dispose()
+})
+
+test('ChunkMeshManager: reveal defer blend migrates to global and releases pool', () => {
+  const manager = createManager({ revealDefer: true })
+  const key = '0,0,0'
+  const geo = makeBlendOnlyGeometry()
+
+  manager.updateSection(key, geo)
+
+  expect(manager.sectionObjects[key]?.hasBlendMesh).toBe(true)
+  expect(manager.sectionObjects[key]?.deferredLegacyBlend).toBeDefined()
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key) ?? false).toBe(false)
+  expect(manager.sectionUsesPooledLegacyMesh(key)).toBe(true)
+
+  manager.migrateDeferredLegacyToGlobal(key)
+
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key)).toBe(true)
+  expect(manager.sectionObjects[key]?.hasBlendMesh).toBe(false)
+  expect(manager.sectionObjects[key]?.deferredLegacyBlend).toBeUndefined()
+  expect(manager.sectionUsesPooledLegacyMesh(key)).toBe(false)
+
+  manager.cleanupSection(key)
+  manager.dispose()
+})
+
+test('ChunkMeshManager: invalid blend geometry falls back to pooled mesh', () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  const manager = createManager()
+  const key = '0,0,0'
+
+  manager.updateSection(key, makeInvalidBlendGeometry())
+
+  expect(warn).toHaveBeenCalledWith(expect.stringContaining('blend invariant violation'))
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key)).toBe(false)
+  expect(manager.sectionObjects[key]?.hasBlendMesh).toBe(true)
+  expect(manager.sectionUsesPooledLegacyMesh(key)).toBe(true)
+
+  warn.mockRestore()
+  manager.cleanupSection(key)
+  manager.dispose()
+})
+
+test('ChunkMeshManager: raycastGlobalLegacySections rejects off-ray sections within center distance', () => {
+  const manager = createManager()
+  const onRayKey = '0,0,0'
+  const offRayKey = '0,2,0'
+
+  manager.updateSection(onRayKey, makeBlendOnlyGeometry())
+
+  const offRayGeo = makeBlendOnlyGeometry()
+  offRayGeo.sz = 40
+  manager.updateSection(offRayKey, offRayGeo)
+
+  expect(manager.globalLegacyBlendBuffer?.hasSection(onRayKey)).toBe(true)
+  expect(manager.globalLegacyBlendBuffer?.hasSection(offRayKey)).toBe(true)
+  expect(manager.sectionObjects[offRayKey]?.worldZ).toBe(40)
+
+  const origin = new THREE.Vector3(4, 8, 8)
+  const direction = new THREE.Vector3(1, 0, 0).normalize()
+  const raycaster = new THREE.Raycaster(origin, direction)
+  raycaster.far = 4
+
+  const hit = manager.raycastGlobalLegacySections(raycaster, origin, 80)
+  expect(hit).toBeDefined()
+  expect(hit!).toBeGreaterThan(2)
+  expect(hit!).toBeLessThan(4)
+
+  manager.cleanupSection(onRayKey)
+  manager.cleanupSection(offRayKey)
+  manager.dispose()
+})
+
+test('ChunkMeshManager: mixed opaque and blend route to separate global buffers', () => {
+  const manager = createManager()
+  const key = '0,0,0'
+
+  manager.updateSection(key, makeMixedGeometry())
+
+  expect(manager.globalLegacyBuffer?.hasSection(key)).toBe(true)
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key)).toBe(true)
+  expect(manager.sectionObjects[key]?.hasBlendMesh).toBe(false)
+  expect(manager.sectionUsesPooledLegacyMesh(key)).toBe(false)
+
+  manager.cleanupSection(key)
+  expect(manager.globalLegacyBuffer?.hasSection(key)).toBe(false)
+  expect(manager.globalLegacyBlendBuffer?.hasSection(key)).toBe(false)
+
+  manager.dispose()
+})

package/src/three/tests/cubeDrawSpans.test.ts

@@ -0,0 +1,73 @@
+//@ts-nocheck
+import { describe, expect, test } from 'vitest'
+import {
+  buildVisibleCubeSpans,
+  MAX_CUBE_SPANS,
+  SPAN_GAP_TOLERANCE_FACES,
+} from '../cubeDrawSpans'
+
+describe('buildVisibleCubeSpans', () => {
+  test('contiguous slots merge into one span', () => {
+    const spans = buildVisibleCubeSpans([
+      { start: 0, count: 4 },
+      { start: 4, count: 2 },
+    ], 6)
+    expect(spans.length).toBe(1)
+    expect(spans[0]).toEqual({ start: 0, count: 6 })
+  })
+
+  test('scattered slots stay as multiple spans', () => {
+    const gap = SPAN_GAP_TOLERANCE_FACES + 1
+    const spans = buildVisibleCubeSpans([
+      { start: 0, count: 1 },
+      { start: 1 + gap, count: 1 },
+    ], 1 + gap + 1)
+    expect(spans.length).toBe(2)
+    expect(spans[0]).toEqual({ start: 0, count: 1 })
+    expect(spans[1]).toEqual({ start: 1 + gap, count: 1 })
+  })
+
+  test('full draw when most faces visible', () => {
+    const spans = buildVisibleCubeSpans([
+      { start: 0, count: 3 },
+      { start: 3, count: 3 },
+      { start: 6, count: 2 },
+    ], 8)
+    expect(spans.length).toBe(1)
+    expect(spans[0]).toEqual({ start: 0, count: 8 })
+  })
+
+  test('caps at MAX_CUBE_SPANS with full coverage', () => {
+    const visibleSectionCount = MAX_CUBE_SPANS + 5
+    const padFaces = SPAN_GAP_TOLERANCE_FACES + 1
+    const visibleSlots: Array<{ start: number, count: number }> = []
+    let cursor = 0
+
+    for (let i = 0; i < visibleSectionCount; i++) {
+      visibleSlots.push({ start: cursor, count: 1 })
+      cursor += 1
+      if (i < visibleSectionCount - 1) {
+        cursor += padFaces
+      }
+    }
+
+    const highWatermark = cursor
+    const spans = buildVisibleCubeSpans(visibleSlots, highWatermark)
+    expect(spans.length).toBe(MAX_CUBE_SPANS)
+
+    const covered = new Set<number>()
+    for (const span of spans) {
+      for (let f = span.start; f < span.start + span.count; f++) {
+        covered.add(f)
+      }
+    }
+    for (const slot of visibleSlots) {
+      expect(covered.has(slot.start)).toBe(true)
+    }
+  })
+
+  test('empty input returns empty spans', () => {
+    expect(buildVisibleCubeSpans([], 10)).toEqual([])
+    expect(buildVisibleCubeSpans([{ start: 0, count: 1 }], 0)).toEqual([])
+  })
+})

package/src/three/tests/globalLegacyBuffer.test.ts

@@ -0,0 +1,360 @@
+//@ts-nocheck
+import { describe, expect, test } from 'vitest'
+import * as THREE from 'three'
+import { GlobalLegacyBuffer, MAX_OPAQUE_SPANS } from '../globalLegacyBuffer'
+import { createGlobalLegacyBlockMaterial } from '../shaders/legacyBlockShader'
+
+function makeQuadGeometry (): {
+  positions: Float32Array
+  colors: Float32Array
+  skyLights: Float32Array
+  blockLights: Float32Array
+  uvs: Float32Array
+  indices: Uint32Array
+} {
+  return {
+    positions: new Float32Array([
+      -1, 0, -1,
+      1, 0, -1,
+      1, 0, 1,
+      -1, 0, 1,
+    ]),
+    colors: new Float32Array([
+      1, 1, 1,
+      1, 1, 1,
+      1, 1, 1,
+      1, 1, 1,
+    ]),
+    skyLights: new Float32Array([1, 1, 1, 1]),
+    blockLights: new Float32Array([0, 0, 0, 0]),
+    uvs: new Float32Array([
+      0, 0,
+      1, 0,
+      1, 1,
+      0, 1,
+    ]),
+    indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+  }
+}
+
+type BufferInternals = {
+  pendingRanges: Array<{ start: number, end: number }>
+}
+
+function getInternals (buffer: GlobalLegacyBuffer): BufferInternals {
+  return buffer as unknown as BufferInternals
+}
+
+function drainUploads (buffer: GlobalLegacyBuffer): void {
+  while (getInternals(buffer).pendingRanges.length) buffer.uploadDirtyRange()
+}
+
+test('GlobalLegacyBuffer: slot reuse and a_origin fill', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 100, 64, 200)
+  const originAttr = buffer.mesh.geometry.getAttribute('a_origin') as THREE.BufferAttribute
+  expect(originAttr.array[0]).toBe(100)
+  expect(originAttr.array[1]).toBe(64)
+  expect(originAttr.array[2]).toBe(200)
+
+  buffer.removeSection('a')
+  drainUploads(buffer)
+
+  buffer.addSection('b', geo, 8, 8, 8)
+  const indexAttr = buffer.mesh.geometry.index!.array as Uint32Array
+  expect(indexAttr[0]).toBe(0)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: a_origin stores world minus render origin', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  buffer.setRenderOrigin({ x: 16, y: 0, z: 16 })
+  buffer.addSection('a', geo, 100, 64, 200)
+  const originAttr = buffer.mesh.geometry.getAttribute('a_origin') as THREE.BufferAttribute
+  expect(originAttr.array[0]).toBe(84)
+  expect(originAttr.array[1]).toBe(64)
+  expect(originAttr.array[2]).toBe(184)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: rebase shifts all a_origin and marks dirty', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 100, 64, 200)
+  buffer.addSection('b', geo, 16, 8, 16)
+
+  buffer.rebase({ x: 16, y: 0, z: 16 })
+  const originAttr = buffer.mesh.geometry.getAttribute('a_origin') as THREE.BufferAttribute
+  expect(originAttr.array[0]).toBe(84)
+  expect(originAttr.array[1]).toBe(64)
+  expect(originAttr.array[2]).toBe(184)
+
+  const slotB = buffer.getSectionSlot('b')!
+  const baseB = slotB.start * 4 * 3
+  expect(originAttr.array[baseB]).toBe(0)
+  expect(originAttr.array[baseB + 1]).toBe(8)
+  expect(originAttr.array[baseB + 2]).toBe(0)
+
+  expect(getInternals(buffer).pendingRanges.length).toBeGreaterThan(0)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: index rebase on copy', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 0, 0, 0)
+  buffer.addSection('b', geo, 16, 8, 16)
+
+  const slot = buffer.getSectionSlot('b')!
+  const indexAttr = buffer.mesh.geometry.index!.array as Uint32Array
+  const base = slot.start * 4
+  expect(indexAttr[slot.start * 6]).toBe(base)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: upload budget splits large dirty span', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  for (let i = 0; i < 12; i++) {
+    buffer.addSection(`s${i}`, geo, i, 0, i)
+  }
+
+  const pendingBefore = getInternals(buffer).pendingRanges.length
+  expect(pendingBefore).toBeGreaterThan(0)
+
+  buffer.uploadDirtyRange()
+  expect(getInternals(buffer).pendingRanges.length).toBeGreaterThanOrEqual(0)
+
+  drainUploads(buffer)
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: removeSection zero-fills indices', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 0, 0, 0)
+  const indexAttr = buffer.mesh.geometry.index!.array as Uint32Array
+  expect(indexAttr[1]).toBe(1)
+
+  buffer.removeSection('a')
+  expect(indexAttr[0]).toBe(0)
+  expect(indexAttr[1]).toBe(0)
+  expect(indexAttr[2]).toBe(0)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: material array on mesh', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  expect(Array.isArray(buffer.mesh.material)).toBe(true)
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: updateDrawSpans opaque merges nearby spans', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene, { initialCapacityQuads: 16, growthIncrementQuads: 16 })
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 0, 0, 0)
+  buffer.addSection('b', geo, 16, 0, 0)
+  buffer.updateDrawSpans([{ key: 'a', distSq: 1 }, { key: 'b', distSq: 4 }], 'opaque')
+
+  const groups = buffer.mesh.geometry.groups
+  expect(groups.length).toBe(1)
+  expect(groups[0]!.count).toBe(12)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: updateDrawSpans opaque full draw when most quads visible', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene, { initialCapacityQuads: 4, growthIncrementQuads: 4 })
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 0, 0, 0)
+  buffer.addSection('b', geo, 16, 0, 0)
+  buffer.addSection('c', geo, 32, 0, 0)
+  buffer.updateDrawSpans([{ key: 'a', distSq: 1 }, { key: 'b', distSq: 2 }, { key: 'c', distSq: 3 }], 'opaque')
+
+  const groups = buffer.mesh.geometry.groups
+  expect(groups.length).toBe(1)
+  expect(groups[0]!.start).toBe(0)
+  expect(groups[0]!.count).toBe(18)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: updateDrawSpans sortedBlend orders back-to-front', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene, { initialCapacityQuads: 16, growthIncrementQuads: 16 })
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('near', geo, 0, 0, 0)
+  buffer.addSection('far', geo, 16, 0, 0)
+  buffer.updateDrawSpans([
+    { key: 'near', distSq: 1 },
+    { key: 'far', distSq: 100 },
+  ], 'sortedBlend')
+
+  const groups = buffer.mesh.geometry.groups
+  expect(groups.length).toBe(2)
+  expect(groups[0]!.start).toBe(6)
+  expect(groups[1]!.start).toBe(0)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: updateDrawSpans skips missing keys', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 0, 0, 0)
+  buffer.updateDrawSpans([{ key: 'missing', distSq: 1 }], 'opaque')
+
+  expect(buffer.mesh.geometry.groups.length).toBe(0)
+  expect(buffer.mesh.geometry.drawRange.count).toBe(0)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: reset clears groups', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const geo = makeQuadGeometry()
+
+  buffer.addSection('a', geo, 0, 0, 0)
+  buffer.updateDrawSpans([{ key: 'a', distSq: 1 }], 'opaque')
+  expect(buffer.mesh.geometry.groups.length).toBeGreaterThan(0)
+
+  buffer.reset()
+  expect(buffer.mesh.geometry.groups.length).toBe(0)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: updateDrawSpans opaque caps at MAX_OPAQUE_SPANS with full coverage', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const visibleSectionCount = MAX_OPAQUE_SPANS + 5
+  const padQuads = 257
+  const buffer = new GlobalLegacyBuffer(mat, scene, {
+    initialCapacityQuads: visibleSectionCount * (padQuads + 1) + padQuads,
+    growthIncrementQuads: 1024,
+  })
+  const geo = makeQuadGeometry()
+  const padGeo = {
+    ...makeQuadGeometry(),
+    positions: new Float32Array(padQuads * 4 * 3),
+    colors: new Float32Array(padQuads * 4 * 3).fill(1),
+    skyLights: new Float32Array(padQuads * 4).fill(1),
+    blockLights: new Float32Array(padQuads * 4).fill(0),
+    uvs: new Float32Array(padQuads * 4 * 2),
+    indices: new Uint32Array(padQuads * 6),
+  }
+  for (let q = 0; q < padQuads; q++) {
+    const vb = q * 4
+    padGeo.indices.set([vb, vb + 1, vb + 2, vb, vb + 2, vb + 3], q * 6)
+  }
+  const visible: Array<{ key: string, distSq: number }> = []
+
+  for (let i = 0; i < visibleSectionCount; i++) {
+    const key = `s${i}`
+    buffer.addSection(key, geo, i * 16, 0, 0)
+    visible.push({ key, distSq: i })
+    if (i < visibleSectionCount - 1) {
+      buffer.addSection(`pad${i}`, padGeo, 0, 0, 0)
+    }
+  }
+
+  for (let i = 0; i < visibleSectionCount - 1; i++) {
+    const cur = buffer.getSectionSlot(`s${i}`)!
+    const next = buffer.getSectionSlot(`s${i + 1}`)!
+    expect(next.start - (cur.start + cur.count)).toBeGreaterThan(256)
+  }
+
+  buffer.updateDrawSpans(visible, 'opaque')
+
+  const groups = buffer.mesh.geometry.groups
+  expect(groups.length).toBe(MAX_OPAQUE_SPANS)
+
+  const covered = new Set<number>()
+  for (const group of groups) {
+    for (let idx = group.start; idx < group.start + group.count; idx++) {
+      covered.add(idx)
+    }
+  }
+  for (let i = 0; i < visibleSectionCount; i++) {
+    const slot = buffer.getSectionSlot(`s${i}`)!
+    const startIdx = slot.start * 6
+    const endIdx = startIdx + slot.count * 6
+    for (let idx = startIdx; idx < endIdx; idx++) {
+      expect(covered.has(idx)).toBe(true)
+    }
+  }
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: addSection rejects non-quad geometry', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+
+  const bad = {
+    positions: new Float32Array([0, 0, 0, 1, 0, 0, 2, 0, 0]),
+    colors: new Float32Array(9),
+    skyLights: new Float32Array(3).fill(1),
+    blockLights: new Float32Array(3).fill(0),
+    uvs: new Float32Array(6),
+    indices: new Uint32Array([0, 1, 2]),
+  }
+  expect(buffer.addSection('bad', bad, 0, 0, 0)).toBe(false)
+
+  buffer.dispose()
+  mat.dispose()
+})