minecraft-renderer 0.1.87 → 0.1.89

package/package.json

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

package/src/mesher-shared/faceOcclusion.ts

@@ -253,19 +253,21 @@ function getBlockFromStateId(version: string, stateId: number) {
   return Block.fromStateId(stateId, 1)
 }
 
-function getAllShapesForState(version: string, stateId: number, blockProvider: WorldBlockProvider): Uint16Array[] {
-  const cacheKey = `${version}:${stateId}`
-  const cached = shapeCache.get(cacheKey)
-  if (cached) return cached
-
-  const shapes = DIR_KEYS.map(() => emptyShape())
-  const blockObj = getBlockFromStateId(version, stateId)
-  if (!blockObj || !blockRendersSolid(blockObj)) {
-    shapeCache.set(cacheKey, shapes)
-    return shapes
+function isFullCubeRenderModel(models: BlockModelPartsResolved | undefined): boolean {
+  try {
+    if (!models?.length || models.length !== 1) return false
+    return models[0]!.every(v =>
+      (v.elements ?? []).every(e => {
+        return e.from[0] === 0 && e.from[1] === 0 && e.from[2] === 0 && e.to[0] === 16 && e.to[1] === 16 && e.to[2] === 16
+      })
+    )
+  } catch {
+    return false
   }
+}
 
-  const models = blockProvider.getAllResolvedModels0_1({ name: blockObj.name, properties: blockObj.getProperties() }, false) as BlockModelPartsResolved
+function buildShapesFromRenderModel(models: BlockModelPartsResolved | undefined): Uint16Array[] {
+  const shapes = DIR_KEYS.map(() => emptyShape())
 
   for (const modelVars of models ?? []) {
     const model = modelVars[0]
@@ -289,10 +291,52 @@ function getAllShapesForState(version: string, stateId: number, blockProvider: W
     }
   }
 
-  shapeCache.set(cacheKey, shapes)
   return shapes
 }
 
+function buildShapesFromCollisionBoxes(boxes: number[][]): Uint16Array[] {
+  const shapes = DIR_KEYS.map(() => emptyShape())
+
+  for (const box of boxes) {
+    const x0 = snapBlockUnit(box[0]! * 16)
+    const y0 = snapBlockUnit(box[1]! * 16)
+    const z0 = snapBlockUnit(box[2]! * 16)
+    const x1 = snapBlockUnit(box[3]! * 16)
+    const y1 = snapBlockUnit(box[4]! * 16)
+    const z1 = snapBlockUnit(box[5]! * 16)
+
+    if (y1 === 16) orRectIntoShape(x0, z0, x1, z1, shapes[dirIndex([0, 1, 0])]!)
+    if (y0 === 0) orRectIntoShape(x0, z0, x1, z1, shapes[dirIndex([0, -1, 0])]!)
+    if (x1 === 16) orRectIntoShape(z0, y0, z1, y1, shapes[dirIndex([1, 0, 0])]!)
+    if (x0 === 0) orRectIntoShape(z0, y0, z1, y1, shapes[dirIndex([-1, 0, 0])]!)
+    if (z1 === 16) orRectIntoShape(x0, y0, x1, y1, shapes[dirIndex([0, 0, 1])]!)
+    if (z0 === 0) orRectIntoShape(x0, y0, x1, y1, shapes[dirIndex([0, 0, -1])]!)
+  }
+
+  return shapes
+}
+
+function getAllShapesForState(version: string, stateId: number, blockProvider: WorldBlockProvider): Uint16Array[] {
+  const cacheKey = `${version}:${stateId}`
+  const cached = shapeCache.get(cacheKey)
+  if (cached) return cached
+
+  const shapes = DIR_KEYS.map(() => emptyShape())
+  const blockObj = getBlockFromStateId(version, stateId)
+  if (!blockObj || !blockRendersSolid(blockObj)) {
+    shapeCache.set(cacheKey, shapes)
+    return shapes
+  }
+
+  const models = blockProvider.getAllResolvedModels0_1({ name: blockObj.name, properties: blockObj.getProperties() }, false) as BlockModelPartsResolved
+  const boxes = blockObj.shapes as number[][] | undefined
+
+  const resolvedShapes = isFullCubeRenderModel(models) ? buildShapesFromRenderModel(models) : boxes?.length ? buildShapesFromCollisionBoxes(boxes) : shapes
+
+  shapeCache.set(cacheKey, resolvedShapes)
+  return resolvedShapes
+}
+
 export function getOcclusionShape(version: string, stateId: number, worldDir: CardinalDir, blockProvider: WorldBlockProvider): Uint16Array {
   return getAllShapesForState(version, stateId, blockProvider)[dirIndex(worldDir)]!
 }

package/src/mesher-shared/tests/faceOcclusion.test.ts

@@ -73,6 +73,42 @@ test('getOcclusionShape: full cube covers entire plane', () => {
   }
 })
 
+test('getOcclusionShape: cactus down occlusion is inset, not full footprint', () => {
+  const mcData = MinecraftData(VERSION)
+  const cactusId = mcData.blocksByName.cactus!.defaultState
+  const downShape = getOcclusionShape(VERSION, cactusId, [0, -1, 0], blockProvider())
+  expect(downShape[0]! & 1).toBe(0)
+  expect(downShape[0]! & (1 << 15)).toBe(0)
+  let covered = 0
+  for (let row = 0; row < 16; row++) {
+    for (let col = 0; col < 16; col++) {
+      if (downShape[row]! & (1 << col)) covered++
+    }
+  }
+  expect(covered).toBe(14 * 14)
+  expect(getOcclusionShape(VERSION, cactusId, [0, 1, 0], blockProvider())[0]).toBe(0)
+})
+
+test('faceIsCulled: grass top not culled by cactus above', () => {
+  const mcData = MinecraftData(VERSION)
+  const grassId = mcData.blocksByName.grass_block!.defaultState
+  const cactusId = mcData.blocksByName.cactus!.defaultState
+  const provider = blockProvider()
+  const blockObj = PrismarineBlockLoader(VERSION).fromStateId(grassId, 1)
+  const models = provider.getAllResolvedModels0_1({ name: blockObj.name, properties: blockObj.getProperties() }, false)
+  const element = models[0]![0]!.elements![0]!
+  expect(faceIsCulled(VERSION, element, 'up', cactusId, { stateId: grassId, name: 'grass_block' }, provider, [0, 1, 0], null)).toBe(false)
+})
+
+test('getOcclusionShape: soul sand keeps full render-model occlusion despite shorter collision', () => {
+  const mcData = MinecraftData(VERSION)
+  const soulSandId = mcData.blocksByName.soul_sand!.defaultState
+  const downShape = getOcclusionShape(VERSION, soulSandId, [0, -1, 0], blockProvider())
+  for (let row = 0; row < 16; row++) {
+    expect(downShape[row]).toBe(0xffff)
+  }
+})
+
 test('getOcclusionShape: farmland side is shorter than full height', () => {
   const mcData = MinecraftData(VERSION)
   const farmlandId = mcData.blocksByName.farmland!.defaultState

package/src/playground/scenes/partialBlockCulling.ts

@@ -1,7 +1,7 @@
 //@ts-nocheck
 import { BasePlaygroundScene } from '../baseScene'
 
-/** Manual check for issue #49: farmland field + cut copper stairs (1.18.2). */
+/** Manual check for issue #49/#73: partial-block culling + cactus on grass (1.18.2). */
 export default class extends BasePlaygroundScene {
   override version = '1.18.2'
   enableCameraOrbitControl = true
@@ -27,5 +27,18 @@ export default class extends BasePlaygroundScene {
       this.addWorldBlock(20 + x, stairY, 4, 'cut_copper_stairs', stairProps)
       this.addWorldBlock(20 + x, stairY + 1, 4, 'cut_copper_stairs', stairProps)
     }
+
+    const cactusY = 64
+    for (let x = 0; x < 4; x++) {
+      this.addWorldBlock(30 + x, cactusY - 1, 8, 'grass_block')
+      this.addWorldBlock(30 + x, cactusY, 8, 'cactus')
+    }
+    this.addWorldBlock(35, cactusY - 1, 8, 'grass_block')
+    this.addWorldBlock(35, cactusY, 8, 'cactus')
+    this.addWorldBlock(35, cactusY + 1, 8, 'cactus')
+
+    this.addWorldBlock(30, cactusY - 1, 10, 'soul_sand')
+    this.addWorldBlock(31, cactusY - 1, 10, 'stone_slab', { type: 'bottom' })
+    this.addWorldBlock(32, cactusY - 1, 10, 'stone_slab', { type: 'bottom' })
   }
 }

package/src/three/chunkMeshManager.ts

@@ -159,6 +159,11 @@ export class ChunkMeshManager {
   private readonly _lastCullCamQuat = new THREE.Quaternion()
   private readonly _cullViewQuat = new THREE.Quaternion()
   private _cullCamInitialized = false
+  /** Visible blend section keys from last cull pass — used by per-quad blend sort. */
+  private _visibleBlendKeys: string[] = []
+  private readonly _lastBlendSortPos = new THREE.Vector3()
+  private _lastBlendSortLayoutVersion = -1
+  private _blendSortPosInitialized = false
   /** One instanced mesh for all shader-cube faces (single draw call). */
   globalBlockBuffer: GlobalBlockBuffer | null = null
   globalLegacyBuffer: GlobalLegacyBuffer | null = null
@@ -328,7 +333,8 @@ export class ChunkMeshManager {
       this.globalLegacyBlendBuffer = new GlobalLegacyBuffer(this.getGlobalLegacyBlendShaderMaterial(), this.scene, {
         name: 'globalLegacyBlend',
         initialCapacityQuads: 32_000,
-        growthIncrementQuads: 32_000
+        growthIncrementQuads: 32_000,
+        sortBlend: true
       })
       this.globalLegacyBlendBuffer.setRenderOrigin(this.renderOrigin)
     }
@@ -459,6 +465,7 @@ export class ChunkMeshManager {
     const blendVisible = visible.filter(v => blendBuf?.hasSection(v.key))
     blendVisible.sort((a, b) => b.distSq - a.distSq)
     const blendKeys = blendVisible.map(v => v.key)
+    this._visibleBlendKeys = blendKeys
 
     const cubeVisibleKeys: string[] = []
     const visibleSlots: Array<{ start: number; count: number }> = []
@@ -532,6 +539,33 @@ export class ChunkMeshManager {
     this.updatePooledLegacyCullState(cameraWorldX, cameraWorldY, cameraWorldZ)
   }
 
+  private static readonly BLEND_RESORT_DISTANCE = 1.0
+
+  /** Per-quad back-to-front reorder within visible blend sections; throttled by camera translation. */
+  sortVisibleBlendSections(camX: number, camY: number, camZ: number): void {
+    const blendBuf = this.globalLegacyBlendBuffer
+    if (!blendBuf || this._visibleBlendKeys.length === 0) return
+
+    const layoutVersion = blendBuf.getLayoutVersion()
+    const layoutChanged = layoutVersion !== this._lastBlendSortLayoutVersion
+    if (this._blendSortPosInitialized && !layoutChanged) {
+      const dx = camX - this._lastBlendSortPos.x
+      const dy = camY - this._lastBlendSortPos.y
+      const dz = camZ - this._lastBlendSortPos.z
+      if (dx * dx + dy * dy + dz * dz < ChunkMeshManager.BLEND_RESORT_DISTANCE * ChunkMeshManager.BLEND_RESORT_DISTANCE) {
+        return
+      }
+    }
+
+    for (const key of this._visibleBlendKeys) {
+      blendBuf.reorderSectionBlendIndices(key, camX, camY, camZ)
+    }
+
+    this._lastBlendSortPos.set(camX, camY, camZ)
+    this._blendSortPosInitialized = true
+    this._lastBlendSortLayoutVersion = layoutVersion
+  }
+
   private bufferStateKey(): string {
     const b = this.globalBlockBuffer
     const o = this.globalLegacyBuffer

package/src/three/cubeDrawSpans.ts

@@ -1,11 +1,5 @@
 //@ts-nocheck
-import {
-  assertDrawSpansWithinLiveRanges,
-  carveSpansAroundPendingRanges,
-  FULL_DRAW_VISIBLE_FRACTION,
-  MAX_OPAQUE_SPANS,
-  type DirtyRange
-} from './globalLegacyBuffer'
+import { carveSpansAroundPendingRanges, FULL_DRAW_VISIBLE_FRACTION, MAX_OPAQUE_SPANS, type DirtyRange } from './globalLegacyBuffer'
 
 export { FULL_DRAW_VISIBLE_FRACTION, MAX_OPAQUE_SPANS as MAX_CUBE_SPANS }
 
@@ -54,10 +48,8 @@ export function buildVisibleCubeSpans(
   } else {
     spans = visibleSlots.map(s => ({ start: s.start, count: s.count }))
     spans.sort((a, b) => a.start - b.start)
-    const liveDrawRanges = spans.map(s => ({ ...s }))
     mergeCubeSpans(spans)
     spans = carveSpansAroundPendingRanges(spans, pendingRanges)
-    assertDrawSpansWithinLiveRanges(spans, liveDrawRanges, 'globalBlockBuffer')
     return spans
   }
   return carveSpansAroundPendingRanges(spans, pendingRanges)

package/src/three/globalBlockBuffer.ts

@@ -711,10 +711,8 @@ export class GlobalBlockBuffer {
       this.finalizePendingReplace(key)
     }
 
-    console.warn('[globalBlockBuffer] growing faces', this.capacityFaces, '->', '(need', minFaces, ')')
     let newCap = this.capacityFaces
     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)

package/src/three/globalLegacyBuffer.ts

@@ -32,33 +32,6 @@ export const FULL_DRAW_VISIBLE_FRACTION = 0.75
 /** 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). */
@@ -96,6 +69,8 @@ export type GlobalLegacyBufferOptions = {
   name?: string
   initialCapacityQuads?: number
   growthIncrementQuads?: number
+  /** When true, pre-sort blend indices on addSection and support per-quad reorder. */
+  sortBlend?: boolean
 }
 
 export type VisibleSectionSpan = { key: string; distSq: number }
@@ -126,6 +101,7 @@ export class GlobalLegacyBuffer {
   readonly material: THREE.ShaderMaterial
 
   private readonly growthIncrementQuads: number
+  private readonly blendSort: boolean
   private capacityQuads: number
   private positions: Float32Array
   private colors: Float32Array
@@ -134,10 +110,15 @@ export class GlobalLegacyBuffer {
   private uvs: Float32Array
   private aOrigin: Float32Array
   private indices: Uint32Array
+  /** Section-relative world centroid per physical quad (3 floats each). */
+  private quadCentroids: Float32Array
+  /** Per-quad local index template (6 bytes each, values 0..3). */
+  private quadIndexTemplate: Uint8Array
   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 indexPendingRanges: 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
@@ -146,12 +127,20 @@ export class GlobalLegacyBuffer {
   private uploadEpoch = 0
   private visibleIndexSpans: LegacyDrawSpan[] = []
   private readonly _drawScratch: LegacyMultiDrawScratch = createLegacyMultiDrawScratch()
+  /** Reusable scratch for applyBlendSort; grown on demand, never allocated per call. */
+  private _sortOrder: Uint32Array = new Uint32Array(0)
+  private _sortDistSq: Float64Array = new Float64Array(0)
   private multiDrawCaps: LegacyMultiDrawCaps | null = null
   private debugOverlay = false
+  private _camX = 0
+  private _camY = 0
+  private _camZ = 0
+  private _camInitialized = false
 
   constructor(material: THREE.ShaderMaterial, scene: THREE.Object3D, opts?: GlobalLegacyBufferOptions) {
     this.material = material
     this.growthIncrementQuads = opts?.growthIncrementQuads ?? DEFAULT_GROWTH_INCREMENT_QUADS
+    this.blendSort = opts?.sortBlend ?? false
     this.capacityQuads = opts?.initialCapacityQuads ?? DEFAULT_INITIAL_CAPACITY_QUADS
     const maxVerts = this.capacityQuads * VERTS_PER_QUAD
     this.positions = new Float32Array(maxVerts * FLOATS_PER_VERT)
@@ -161,6 +150,8 @@ export class GlobalLegacyBuffer {
     this.uvs = new Float32Array(maxVerts * FLOATS_PER_UV_VERT)
     this.aOrigin = new Float32Array(maxVerts * FLOATS_PER_VERT)
     this.indices = new Uint32Array(this.capacityQuads * INDICES_PER_QUAD)
+    this.quadCentroids = new Float32Array(this.capacityQuads * 3)
+    this.quadIndexTemplate = new Uint8Array(this.capacityQuads * INDICES_PER_QUAD)
 
     const geometry = new THREE.BufferGeometry()
     const mkAttr = (arr: Float32Array, itemSize: number, name: string) => {
@@ -305,10 +296,38 @@ export class GlobalLegacyBuffer {
       this.indices[dstIndexBase + i] = geo.indices[i]! + vertexBase
     }
 
+    for (let q = 0; q < quadCount; q++) {
+      const physQuad = slot.start + q
+      const localVertBase = q * VERTS_PER_QUAD
+      const posBase = localVertBase * FLOATS_PER_VERT
+      let cx = 0
+      let cy = 0
+      let cz = 0
+      for (let v = 0; v < VERTS_PER_QUAD; v++) {
+        const p = posBase + v * FLOATS_PER_VERT
+        cx += geo.positions[p]!
+        cy += geo.positions[p + 1]!
+        cz += geo.positions[p + 2]!
+      }
+      const centBase = physQuad * 3
+      this.quadCentroids[centBase] = cx / VERTS_PER_QUAD
+      this.quadCentroids[centBase + 1] = cy / VERTS_PER_QUAD
+      this.quadCentroids[centBase + 2] = cz / VERTS_PER_QUAD
+
+      const idxBase = q * INDICES_PER_QUAD
+      const tmplBase = physQuad * INDICES_PER_QUAD
+      for (let i = 0; i < INDICES_PER_QUAD; i++) {
+        this.quadIndexTemplate[tmplBase + i] = geo.indices[idxBase + i]! - localVertBase
+      }
+    }
+
     this.sectionSlots.set(sectionKey, slot)
     if (isRemesh && previousSlot) {
       this.pendingReplace.set(sectionKey, { oldStart: previousSlot.start, oldCount: previousSlot.count })
     }
+    if (this.blendSort && this._camInitialized && quadCount >= 2) {
+      this.applyBlendSort(slot.start, quadCount, this._camX, this._camY, this._camZ)
+    }
     this.markDirty(slot.start, slot.start + quadCount - 1)
     this.syncDefaultDrawGroups()
     this.layoutVersion++
@@ -435,7 +454,6 @@ export class GlobalLegacyBuffer {
 
     if (mode === 'opaque') {
       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 }]
@@ -445,9 +463,6 @@ export class GlobalLegacyBuffer {
         finalQuads = spans
       }
       finalQuads = carveSpansAroundPendingRanges(finalQuads, this.pendingRanges)
-      if (!usedFullDraw) {
-        assertDrawSpansWithinLiveRanges(finalQuads, liveDrawRanges, this.mesh.name)
-      }
       for (const span of finalQuads) {
         pushIndexSpan(span.start, span.count)
       }
@@ -558,6 +573,70 @@ export class GlobalLegacyBuffer {
     return this.pendingRanges.length > 0
   }
 
+  hasPendingIndexUploads(): boolean {
+    return this.indexPendingRanges.length > 0
+  }
+
+  /**
+   * Reorder a section's index buffer back-to-front by quad centroid distance to camera.
+   * Does not bump layoutVersion or uploadEpoch (draw spans unchanged).
+   */
+  reorderSectionBlendIndices(sectionKey: string, camX: number, camY: number, camZ: number): boolean {
+    const slot = this.sectionSlots.get(sectionKey)
+    if (!slot) return false
+    if (this.pendingMove?.key === sectionKey) return false
+    if (this.pendingReplace.has(sectionKey)) return false
+    if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) return false
+    if (slot.count < 2) return false
+
+    this.applyBlendSort(slot.start, slot.count, camX, camY, camZ)
+    this.markIndexDirty(slot.start, slot.start + slot.count - 1)
+    return true
+  }
+
+  /** Rewrite indices for [slotStart, slotStart+slotCount) back-to-front by quad centroid distance. */
+  private applyBlendSort(slotStart: number, slotCount: number, camX: number, camY: number, camZ: number): void {
+    const dstFloatBase = slotStart * VERTS_PER_QUAD * FLOATS_PER_VERT
+    const sx = this.aOrigin[dstFloatBase]! + this.renderOrigin.x
+    const sy = this.aOrigin[dstFloatBase + 1]! + this.renderOrigin.y
+    const sz = this.aOrigin[dstFloatBase + 2]! + this.renderOrigin.z
+
+    if (this._sortOrder.length < slotCount) {
+      this._sortOrder = new Uint32Array(slotCount)
+      this._sortDistSq = new Float64Array(slotCount)
+    }
+    const order = this._sortOrder
+    const distSq = this._sortDistSq
+    for (let p = 0; p < slotCount; p++) {
+      order[p] = p
+      const physQuad = slotStart + p
+      const centBase = physQuad * 3
+      const wx = sx + this.quadCentroids[centBase]!
+      const wy = sy + this.quadCentroids[centBase + 1]!
+      const wz = sz + this.quadCentroids[centBase + 2]!
+      const dx = wx - camX
+      const dy = wy - camY
+      const dz = wz - camZ
+      distSq[p] = dx * dx + dy * dy + dz * dz
+    }
+    const orderView = order.subarray(0, slotCount)
+    orderView.sort((a, b) => {
+      const d = distSq[b]! - distSq[a]!
+      if (d !== 0) return d
+      return a - b
+    })
+
+    for (let k = 0; k < slotCount; k++) {
+      const src = orderView[k]!
+      const srcVertBase = (slotStart + src) * VERTS_PER_QUAD
+      const dstIdxBase = (slotStart + k) * INDICES_PER_QUAD
+      const tmplBase = (slotStart + src) * INDICES_PER_QUAD
+      for (let i = 0; i < INDICES_PER_QUAD; i++) {
+        this.indices[dstIdxBase + i] = srcVertBase + this.quadIndexTemplate[tmplBase + i]!
+      }
+    }
+  }
+
   uploadDirtyRange(): void {
     const r = this.pendingRanges[0]
     if (!r) return
@@ -613,6 +692,27 @@ export class GlobalLegacyBuffer {
     this.uploadEpoch++
   }
 
+  uploadDirtyIndexRange(): void {
+    const r = this.indexPendingRanges[0]
+    if (!r) return
+
+    const quadOffset = r.start
+    const quadCount = Math.min(r.end - r.start + 1, MAX_UPLOAD_QUADS_PER_FRAME)
+    const indexOffset = quadOffset * INDICES_PER_QUAD
+    const indexCount = quadCount * INDICES_PER_QUAD
+
+    const indexAttr = this.mesh.geometry.index as THREE.BufferAttribute
+    indexAttr.clearUpdateRanges()
+    indexAttr.addUpdateRange(indexOffset, indexCount)
+    indexAttr.needsUpdate = true
+
+    if (quadOffset + quadCount > r.end) {
+      this.indexPendingRanges.shift()
+    } else {
+      r.start = quadOffset + quadCount
+    }
+  }
+
   setRenderOrigin(renderOrigin: RenderOrigin): void {
     this.renderOrigin = { ...renderOrigin }
   }
@@ -637,6 +737,10 @@ export class GlobalLegacyBuffer {
   }
 
   setCameraOrigin(x: number, y: number, z: number): void {
+    this._camX = x
+    this._camY = y
+    this._camZ = z
+    this._camInitialized = true
     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)
@@ -669,6 +773,7 @@ export class GlobalLegacyBuffer {
     this.freeList.length = 0
     this.highWatermark = 0
     this.pendingRanges.length = 0
+    this.indexPendingRanges.length = 0
     this.pendingMove = null
     this.pendingReplace.clear()
     this.uploadEpoch = 0
@@ -688,6 +793,29 @@ export class GlobalLegacyBuffer {
     this.mergePendingRanges()
   }
 
+  private markIndexDirty(start: number, end: number): void {
+    this.indexPendingRanges.push({ start, end })
+    this.indexPendingRanges.sort((a, b) => a.start - b.start)
+    this.mergeIndexPendingRanges()
+  }
+
+  private mergeIndexPendingRanges(): void {
+    if (this.indexPendingRanges.length < 2) return
+    const merged: Array<{ start: number; end: number }> = []
+    let cur = this.indexPendingRanges[0]!
+    for (let i = 1; i < this.indexPendingRanges.length; i++) {
+      const next = this.indexPendingRanges[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.indexPendingRanges = merged
+  }
+
   private mergePendingRanges(): void {
     if (this.pendingRanges.length < 2) return
     const merged: Array<{ start: number; end: number }> = []
@@ -835,6 +963,14 @@ export class GlobalLegacyBuffer {
     for (let i = 0; i < indexLen; i++) {
       this.indices[newIndexBase + i] = this.indices[oldIndexBase + i]! + vertDelta
     }
+
+    const oldCentroidBase = oldStart * 3
+    const newCentroidBase = newStart * 3
+    this.quadCentroids.copyWithin(newCentroidBase, oldCentroidBase, oldCentroidBase + quadCount * 3)
+
+    const oldTemplateBase = oldStart * INDICES_PER_QUAD
+    const newTemplateBase = newStart * INDICES_PER_QUAD
+    this.quadIndexTemplate.copyWithin(newTemplateBase, oldTemplateBase, oldTemplateBase + quadCount * INDICES_PER_QUAD)
   }
 
   private rangeFullyUploaded(start: number, end: number): boolean {
@@ -898,6 +1034,8 @@ export class GlobalLegacyBuffer {
     const nUv = new Float32Array(newMaxVerts * FLOATS_PER_UV_VERT)
     const nOrigin = new Float32Array(newMaxVerts * FLOATS_PER_VERT)
     const nIdx = new Uint32Array(newCap * INDICES_PER_QUAD)
+    const nCentroids = new Float32Array(newCap * 3)
+    const nTemplate = new Uint8Array(newCap * INDICES_PER_QUAD)
 
     nPos.set(this.positions)
     nCol.set(this.colors)
@@ -906,6 +1044,8 @@ export class GlobalLegacyBuffer {
     nUv.set(this.uvs)
     nOrigin.set(this.aOrigin)
     nIdx.set(this.indices)
+    nCentroids.set(this.quadCentroids)
+    nTemplate.set(this.quadIndexTemplate)
 
     this.positions = nPos
     this.colors = nCol
@@ -914,6 +1054,8 @@ export class GlobalLegacyBuffer {
     this.uvs = nUv
     this.aOrigin = nOrigin
     this.indices = nIdx
+    this.quadCentroids = nCentroids
+    this.quadIndexTemplate = nTemplate
     this.capacityQuads = newCap
 
     const geometry = this.mesh.geometry
@@ -938,5 +1080,6 @@ export class GlobalLegacyBuffer {
     geometry.setIndex(indexAttr)
 
     this.pendingRanges.length = 0
+    this.indexPendingRanges.length = 0
   }
 }

package/src/three/shaders/legacyBlockShader.ts

@@ -228,7 +228,7 @@ export function createGlobalLegacyBlendMaterial(): THREE.ShaderMaterial {
     fragmentShader,
     uniforms: THREE.UniformsUtils.merge([THREE.UniformsLib.fog, legacyUniforms]),
     transparent: true,
-    depthWrite: true,
+    depthWrite: false,
     depthTest: true,
     vertexColors: true,
     glslVersion: THREE.GLSL3,

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

@@ -2,6 +2,18 @@
 import { describe, expect, test } from 'vitest'
 import { buildVisibleCubeSpans } from '../cubeDrawSpans'
 
+type DrawSpan = { start: number; count: number }
+
+/** Every index in output spans must lie in the union of input section ranges. */
+function expectEveryIndexInUnion(spans: DrawSpan[], sectionRanges: DrawSpan[]): void {
+  for (const span of spans) {
+    for (let i = span.start; i < span.start + span.count; i++) {
+      const inUnion = sectionRanges.some(r => i >= r.start && i < r.start + r.count)
+      expect(inUnion, `index ${i} not in union of section ranges`).toBe(true)
+    }
+  }
+}
+
 describe('buildVisibleCubeSpans', () => {
   test('contiguous slots merge into one span', () => {
     const spans = buildVisibleCubeSpans(
@@ -100,4 +112,23 @@ describe('buildVisibleCubeSpans', () => {
     expect(buildVisibleCubeSpans([], 10)).toEqual([])
     expect(buildVisibleCubeSpans([{ start: 0, count: 1 }], 0)).toEqual([])
   })
+
+  test('merged adjacent sections stay within union of input ranges', () => {
+    const sectionRanges = [
+      { start: 100, count: 10 },
+      { start: 110, count: 10 }
+    ]
+    const spans = buildVisibleCubeSpans(sectionRanges, 120, false)
+    expect(spans).toEqual([{ start: 100, count: 20 }])
+    expectEveryIndexInUnion(spans, sectionRanges)
+  })
+
+  test('carved merged spans stay within union of input ranges', () => {
+    const sectionRanges = [
+      { start: 0, count: 10 },
+      { start: 10, count: 10 }
+    ]
+    const spans = buildVisibleCubeSpans(sectionRanges, 20, false, undefined, [{ start: 5, end: 14 }])
+    expectEveryIndexInUnion(spans, sectionRanges)
+  })
 })