minecraft-renderer 0.1.107 → 0.1.109

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

@@ -0,0 +1,87 @@
+//@ts-nocheck
+import { expect, test } from 'vitest'
+import { buildCloudGeometry, CLOUD_CELL_SIZE, CLOUD_THICKNESS, type CloudCover } from '../cloudGeometry'
+
+function coverOf(rows: string[]): CloudCover {
+  const height = rows.length
+  const width = rows[0].length
+  const filled = new Uint8Array(width * height)
+  rows.forEach((row, z) => [...row].forEach((ch, x) => (filled[z * width + x] = ch === '#' ? 1 : 0)))
+  return { width, height, filled }
+}
+
+const quadCount = (data: ReturnType<typeof buildCloudGeometry>) => data.indices.length / 6
+
+/** Normal of triangle `tri` from the index buffer. */
+function triangleNormal(data: ReturnType<typeof buildCloudGeometry>, tri: number): [number, number, number] {
+  const p = (k: number) => {
+    const v = data.indices[tri * 3 + k] * 3
+    return [data.positions[v], data.positions[v + 1], data.positions[v + 2]]
+  }
+  const [a, b, c] = [p(0), p(1), p(2)]
+  const u = [b[0] - a[0], b[1] - a[1], b[2] - a[2]]
+  const v = [c[0] - a[0], c[1] - a[1], c[2] - a[2]]
+  return [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]]
+}
+
+test('a lone cell is a closed box of six faces', () => {
+  const data = buildCloudGeometry(coverOf(['....', '.#..', '....', '....']), 1, 1, 0)
+  expect(quadCount(data)).toBe(6)
+  expect(data.positions.length / 3).toBe(24)
+  expect(data.shades.length).toBe(24)
+})
+
+test('empty sky produces no geometry', () => {
+  expect(buildCloudGeometry(coverOf(['....', '....']), 0, 0, 3).indices.length).toBe(0)
+})
+
+test('faces between adjacent cells are not emitted', () => {
+  // top + bottom for each cell, two side faces each along z, and one end cap each along x.
+  const data = buildCloudGeometry(coverOf(['....', '.##.', '....', '....']), 1, 1, 1)
+  expect(quadCount(data)).toBe(2 + 2 + 4 + 2)
+})
+
+test('every face winds counter-clockwise seen from outside the box', () => {
+  const data = buildCloudGeometry(coverOf(['....', '.#..', '....', '....']), 1, 1, 0)
+  const normals = new Set<string>()
+  for (let tri = 0; tri < data.indices.length / 3; tri++) {
+    const n = triangleNormal(data, tri)
+    // Only one axis is non-zero for an axis-aligned face.
+    const nonZero = n.filter(c => Math.abs(c) > 1e-6)
+    expect(nonZero).toHaveLength(1)
+    normals.add(n.map(c => Math.sign(c)).join(','))
+  }
+  expect([...normals].sort()).toEqual(['-1,0,0', '0,-1,0', '0,0,-1', '0,0,1', '0,1,0', '1,0,0'].sort())
+})
+
+test('faces point away from the cell centre', () => {
+  const data = buildCloudGeometry(coverOf(['.#', '..']), 1, 0, 0)
+  const centre = [CLOUD_CELL_SIZE / 2, CLOUD_THICKNESS / 2, CLOUD_CELL_SIZE / 2]
+  for (let tri = 0; tri < data.indices.length / 3; tri++) {
+    const n = triangleNormal(data, tri)
+    const v = data.indices[tri * 3] * 3
+    const toFace = [data.positions[v] - centre[0], data.positions[v + 1] - centre[1], data.positions[v + 2] - centre[2]]
+    expect(n[0] * toFace[0] + n[1] * toFace[1] + n[2] * toFace[2]).toBeGreaterThan(0)
+  }
+})
+
+test('the slab is four blocks thick and cells are 12 blocks wide', () => {
+  const data = buildCloudGeometry(coverOf(['#']), 0, 0, 0)
+  const xs = [...data.positions].filter((_, i) => i % 3 === 0)
+  const ys = [...data.positions].filter((_, i) => i % 3 === 1)
+  expect(Math.max(...ys) - Math.min(...ys)).toBe(4)
+  expect(Math.max(...xs) - Math.min(...xs)).toBe(12)
+})
+
+test('cell lookup wraps like the texture, including negative indices', () => {
+  const cover = coverOf(['#...', '....'])
+  // Cells (-4, 0) and (4, 2) alias texel (0, 0); a lone filled texel yields exactly one box per alias.
+  expect(quadCount(buildCloudGeometry(cover, -4, 0, 0))).toBe(6)
+  expect(quadCount(buildCloudGeometry(cover, 4, 2, 0))).toBe(6)
+  expect(quadCount(buildCloudGeometry(cover, 1, 0, 0))).toBe(0)
+})
+
+test('shading matches vanilla: top brightest, bottom darkest, sides in between', () => {
+  const data = buildCloudGeometry(coverOf(['....', '.#..', '....', '....']), 1, 1, 0)
+  expect([...new Set(data.shades)].sort()).toEqual([0.7, 0.8, 0.9, 1].map(Math.fround).sort())
+})

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

@@ -1,17 +1,14 @@
 //@ts-nocheck
 import * as THREE from 'three'
-import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+import { expect, test, vi } from 'vitest'
 import { CloudsModule } from '../modules/clouds'
 import { defaultWorldRendererConfig } from '../../graphicsBackend/config'
+import type { CloudCover } from '../cloudGeometry'
 
-beforeEach(() => {
-  // No image decoding in node; the module only needs a texture object.
-  vi.spyOn(THREE.TextureLoader.prototype, 'load').mockImplementation(() => new THREE.Texture())
-})
+const cover: CloudCover = { width: 2, height: 2, filled: new Uint8Array([1, 0, 0, 1]) }
 
-afterEach(() => {
-  vi.restoreAllMocks()
-})
+// No image decoding in node.
+vi.mock('../cloudCover', () => ({ loadCloudCover: vi.fn(async () => cover) }))
 
 function createModule(config: Partial<typeof defaultWorldRendererConfig> = {}) {
   const scene = new THREE.Scene()
@@ -26,6 +23,8 @@ function createModule(config: Partial<typeof defaultWorldRendererConfig> = {}) {
   return { module, scene, worldRenderer }
 }
 
+const cloudMeshes = (scene: THREE.Scene) => scene.getObjectByName('clouds')!.children as THREE.Mesh[]
+
 test('clouds are on by default and auto mode follows the clouds option', () => {
   const { module, worldRenderer } = createModule()
   expect(module.autoEnableCheck()).toBe(true)
@@ -37,18 +36,18 @@ test('clouds stay off in the nether even when enabled', () => {
   expect(createModule({ cardinalLight: 'nether' }).module.autoEnableCheck()).toBe(false)
 })
 
-test('disable hides the cloud layer and enable shows the same mesh again', () => {
+test('disable hides the cloud layer and enable shows the same layer again', () => {
   const { module, scene } = createModule()
   module.enable()
-  const mesh = scene.getObjectByName('clouds')!
-  expect(mesh.visible).toBe(true)
+  const layer = scene.getObjectByName('clouds')!
+  expect(layer.visible).toBe(true)
 
   module.disable()
-  expect(mesh.visible).toBe(false)
+  expect(layer.visible).toBe(false)
 
   module.enable()
-  expect(scene.getObjectByName('clouds')).toBe(mesh)
-  expect(mesh.visible).toBe(true)
+  expect(scene.getObjectByName('clouds')).toBe(layer)
+  expect(layer.visible).toBe(true)
 })
 
 test('dispose removes the cloud layer from the scene', () => {
@@ -57,3 +56,55 @@ test('dispose removes the cloud layer from the scene', () => {
   module.dispose()
   expect(scene.getObjectByName('clouds')).toBeUndefined()
 })
+
+test('renders a depth pre-pass before the colour pass over the same geometry', () => {
+  const { module, scene } = createModule()
+  module.enable()
+  const [depthPass, colorPass] = cloudMeshes(scene)
+  expect(depthPass.material).toMatchObject({ colorWrite: false, depthWrite: true })
+  expect(colorPass.material).toMatchObject({ colorWrite: true, depthWrite: false })
+  expect(depthPass.renderOrder).toBeLessThan(colorPass.renderOrder)
+  expect(depthPass.geometry).toBe(colorPass.geometry)
+})
+
+test('builds volumetric cloud geometry once clouds.png has loaded and follows the camera', async () => {
+  const { module, scene, worldRenderer } = createModule()
+  module.enable()
+  const [depthPass, colorPass] = cloudMeshes(scene)
+  const sync = () => (depthPass.onBeforeRender as any)()
+
+  // Nothing to draw until the texture is decoded.
+  sync()
+  expect(depthPass.geometry.index).toBeNull()
+
+  await vi.waitFor(() => {
+    sync()
+    expect(depthPass.geometry.index).not.toBeNull()
+  })
+  const geometry = depthPass.geometry
+  expect(colorPass.geometry).toBe(geometry)
+  // Side faces and a 4-block thickness: more than a flat sheet's top/bottom quads.
+  const ys = geometry.getAttribute('position').array.filter((_, i) => i % 3 === 1)
+  expect(Math.max(...ys) - Math.min(...ys)).toBe(4)
+  expect(geometry.getAttribute('shade')).toBeDefined()
+
+  // Moving within the same cell keeps the geometry and only moves the layer.
+  const before = scene.getObjectByName('clouds')!.position.x
+  worldRenderer.sceneOrigin.x += 3
+  sync()
+  expect(depthPass.geometry).toBe(geometry)
+  expect(scene.getObjectByName('clouds')!.position.x).toBeCloseTo(before - 3)
+
+  // Crossing a cell boundary rebuilds around the new cell.
+  worldRenderer.sceneOrigin.x += 24
+  sync()
+  expect(depthPass.geometry).not.toBe(geometry)
+})
+
+test('the layer sits at the configured cloud height above the camera', () => {
+  const { module, scene, worldRenderer } = createModule({ cloudHeight: 192 })
+  worldRenderer.sceneOrigin.y = 100
+  module.enable()
+  ;(cloudMeshes(scene)[0].onBeforeRender as any)()
+  expect(scene.getObjectByName('clouds')!.position.y).toBeCloseTo(192.33 - 100)
+})

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

@@ -215,3 +215,101 @@ test('GlobalBlockBuffer: uploadEpoch increments when dirty range drains', () =>
   buffer.dispose()
   mat.dispose()
 })
+
+function faceWords(faceCount: number): Uint32Array {
+  return new Uint32Array(faceCount * 4)
+}
+
+function drawableCubeFaces(buffer: GlobalBlockBuffer, key: string): number {
+  const start = buffer.getSectionDrawStart(key)
+  const count = buffer.getSectionDrawCount(key)
+  if (start === undefined || count === undefined) return 0
+  const spans = buildVisibleCubeSpans([{ start, count }], buffer.getHighWatermark(), false, undefined, buffer.getPendingDirtyRanges())
+  return spans.reduce((sum, span) => sum + span.count, 0)
+}
+
+test('GlobalBlockBuffer: compaction must not hide pending-replace displayed faces', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('H', faceWords(20_000), 20_000)
+  buffer.addSection('A', faceWords(8000), 8000)
+  buffer.addSection('B', faceWords(1000), 1000)
+  drainUploads(buffer)
+  const original = buffer.getSectionDrawStart('A')
+
+  buffer.addSection('A', faceWords(8000), 8000)
+  buffer.removeSection('H')
+  buffer.compactStep()
+  buffer.uploadDirtyRange()
+
+  expect(drawableCubeFaces(buffer, 'A')).toBe(8000)
+  expect(buffer.getSectionDrawStart('A')).toBe(original)
+  const move = buffer.getPendingMove()
+  expect(move?.key === 'A').toBe(false)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: 27 simultaneous remeshes keep 8000 faces on every frame', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+  const n = 27
+  const faces = 8000
+
+  for (let i = 0; i < n; i++) buffer.addSection(String(i), faceWords(faces), faces)
+  drainUploads(buffer)
+  for (let i = 0; i < n; i++) buffer.addSection(String(i), faceWords(faces), faces)
+
+  for (let frame = 1; frame <= 120; frame++) {
+    buffer.compactStep()
+    buffer.uploadDirtyRange()
+    for (let i = 0; i < n; i++) {
+      expect(drawableCubeFaces(buffer, String(i)), `section ${i} on frame ${frame}`).toBe(faces)
+    }
+    if (!buffer.hasPendingUploads() && !buffer.hasPendingReplace() && !buffer.getPendingMove()) break
+  }
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalBlockBuffer: remesh during move keeps original displayed slot', () => {
+  const scene = new THREE.Scene()
+  const mat = createCubeBlockMaterial()
+  const buffer = new GlobalBlockBuffer(mat, scene)
+
+  buffer.addSection('H', faceWords(20_000), 20_000)
+  buffer.addSection('B', faceWords(1000), 1000)
+  buffer.addSection('A', faceWords(8000), 8000)
+  drainUploads(buffer)
+  buffer.removeSection('H')
+  drainUploads(buffer)
+  buffer.compactStep()
+  expect(buffer.getPendingMove()?.key).toBe('A')
+  const displayed = buffer.getSectionDrawStart('A')
+  expect(displayed).toBeDefined()
+
+  buffer.addSection('A', faceWords(8000), 8000)
+  expect(buffer.getSectionDrawStart('A')).toBe(displayed)
+  expect(buffer.getPendingMove()).toBeNull()
+  expect(buffer.hasPendingReplace()).toBe(true)
+  expect(drawableCubeFaces(buffer, 'A')).toBe(8000)
+
+  buffer.compactStep()
+  buffer.uploadDirtyRange()
+  expect(buffer.getSectionDrawStart('A')).toBe(displayed)
+  expect(buffer.getPendingMove()?.key === 'A').toBe(false)
+  expect(drawableCubeFaces(buffer, 'A')).toBe(8000)
+
+  drainUploads(buffer)
+  buffer.compactStep()
+  finishCurrentMove(buffer)
+  expect(drawableCubeFaces(buffer, 'A')).toBe(8000)
+
+  buffer.dispose()
+  mat.dispose()
+})

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

@@ -892,3 +892,111 @@ test('GlobalLegacyBuffer: blend reorder metadata survives compaction', () => {
   buffer.dispose()
   mat.dispose()
 })
+
+function quadGeometry(quadCount: number): ReturnType<typeof makeQuadGeometry> {
+  const indices = new Uint32Array(quadCount * 6)
+  for (let i = 0; i < quadCount; i++) {
+    const v = i * 4
+    indices.set([v, v + 1, v + 2, v, v + 2, v + 3], i * 6)
+  }
+  return {
+    positions: new Float32Array(quadCount * 12),
+    colors: new Float32Array(quadCount * 12),
+    skyLights: new Float32Array(quadCount * 4),
+    blockLights: new Float32Array(quadCount * 4),
+    uvs: new Float32Array(quadCount * 8),
+    indices
+  }
+}
+
+function drawableLegacyIndices(buffer: GlobalLegacyBuffer, key: string): number {
+  buffer.updateDrawSpans([{ key, distSq: 0 }], 'opaque')
+  return buffer.getVisibleIndexSpans().reduce((sum, span) => sum + span.indexCount, 0)
+}
+
+test('GlobalLegacyBuffer: compaction must not hide pending-replace displayed indices', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+
+  buffer.addSection('H', quadGeometry(8000), 0, 0, 0)
+  buffer.addSection('A', quadGeometry(3000), 0, 0, 0)
+  buffer.addSection('B', quadGeometry(500), 0, 0, 0)
+  drainUploads(buffer)
+  const original = buffer.getSectionDrawStart('A')
+
+  buffer.addSection('A', quadGeometry(3000), 0, 0, 0)
+  buffer.removeSection('H')
+  buffer.compactStep()
+  buffer.uploadDirtyRange()
+  buffer.updateDrawSpans([{ key: 'A', distSq: 0 }], 'opaque')
+
+  expect(drawableLegacyIndices(buffer, 'A')).toBe(18_000)
+  expect(buffer.getSectionDrawStart('A')).toBe(original)
+  expect(buffer.getPendingMove()?.key === 'A').toBe(false)
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: 27 simultaneous remeshes keep displayed quads on every frame', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+  const n = 27
+  const quads = 1000
+  const expectedIndices = quads * 6
+
+  for (let i = 0; i < n; i++) buffer.addSection(String(i), quadGeometry(quads), 0, 0, 0)
+  drainUploads(buffer)
+  for (let i = 0; i < n; i++) buffer.addSection(String(i), quadGeometry(quads), 0, 0, 0)
+
+  for (let frame = 1; frame <= 160; frame++) {
+    buffer.compactStep()
+    buffer.uploadDirtyRange()
+    for (let i = 0; i < n; i++) {
+      expect(drawableLegacyIndices(buffer, String(i)), `section ${i} on frame ${frame}`).toBe(expectedIndices)
+    }
+    if (!buffer.hasPendingUploads() && !buffer.hasPendingReplace() && !buffer.getPendingMove()) break
+  }
+
+  buffer.dispose()
+  mat.dispose()
+})
+
+test('GlobalLegacyBuffer: remesh during move keeps original displayed slot', () => {
+  const scene = new THREE.Scene()
+  const mat = createGlobalLegacyBlockMaterial()
+  const buffer = new GlobalLegacyBuffer(mat, scene)
+
+  buffer.addSection('H', quadGeometry(8000), 0, 0, 0)
+  buffer.addSection('B', quadGeometry(500), 0, 0, 0)
+  buffer.addSection('A', quadGeometry(3000), 0, 0, 0)
+  drainUploads(buffer)
+  buffer.removeSection('H')
+  drainUploads(buffer)
+  buffer.compactStep()
+  expect(buffer.getPendingMove()?.key).toBe('A')
+  const displayed = buffer.getSectionDrawStart('A')
+  expect(displayed).toBeDefined()
+
+  buffer.addSection('A', quadGeometry(3000), 0, 0, 0)
+  expect(buffer.getSectionDrawStart('A')).toBe(displayed)
+  expect(buffer.getPendingMove()).toBeNull()
+  expect(buffer.hasPendingReplace()).toBe(true)
+  expect(drawableLegacyIndices(buffer, 'A')).toBe(18_000)
+
+  buffer.compactStep()
+  buffer.uploadDirtyRange()
+  expect(buffer.getSectionDrawStart('A')).toBe(displayed)
+  expect(buffer.getPendingMove()?.key === 'A').toBe(false)
+  expect(drawableLegacyIndices(buffer, 'A')).toBe(18_000)
+
+  drainUploads(buffer)
+  buffer.compactStep()
+  finishCurrentMove(buffer)
+  expect(drawableLegacyIndices(buffer, 'A')).toBe(18_000)
+
+  buffer.dispose()
+  mat.dispose()
+})

package/src/three/worldRendererThree.ts

@@ -40,6 +40,9 @@ import { FireworksManager } from './fireworks'
 import { SceneOrigin } from './sceneOrigin'
 import { downloadWorldGeometry } from './worldGeometryExport'
 import { ChunkMeshManager } from './chunkMeshManager'
+import { selectReadySectionFlushes } from '../lighting/versioning/pendingSectionFlush'
+import { isClientLightTraceEnabled, recordClientLightTrace } from '../lighting/debug/clientLightTrace'
+import { EntityLightController } from '../lighting/entity/entityLightController'
 import { raycastVoxelSolid } from './thirdPersonVoxelRaycast'
 import type { RendererModuleManifest, RegisteredModule, RendererModuleController } from './rendererModuleSystem'
 import { BUILTIN_MODULES } from './modules/index'
@@ -89,6 +92,7 @@ export class WorldRendererThree extends WorldRendererCommon {
   ambientLight = new THREE.AmbientLight(0xcc_cc_cc, WorldRendererThree.LEGACY_TO_PHYSICAL_LIGHT)
   directionalLight = new THREE.DirectionalLight(0xff_ff_ff, 0.5 * WorldRendererThree.LEGACY_TO_PHYSICAL_LIGHT)
   entities = new Entities(this, (globalThis as any).mcData)
+  entityLightController?: EntityLightController
   performanceMonitor!: PerformanceMonitor
   cameraGroupVr?: THREE.Object3D
   material = new THREE.MeshBasicMaterial({ vertexColors: true, transparent: true, alphaTest: 0.1 })
@@ -204,6 +208,14 @@ export class WorldRendererThree extends WorldRendererCommon {
 
     // Initialize chunk mesh manager
     this.chunkMeshManager = new ChunkMeshManager(this, this.scene, this.material, this.worldSizeParams.worldHeight, this.viewDistance)
+    this.entityLightController = new EntityLightController({
+      getLight: (x, y, z) => this.rendererLightCache.getLight(x, y, z),
+      getSkyLevel: () => this.chunkMeshManager.getSkyLevel(),
+      getLightmapParams: () => this.chunkMeshManager.getLightmapParams(),
+      getColumnRevision: (cx, cz) => this.rendererLightCache.getColumnRevision(cx, cz),
+      getGlobalRevision: () => this.rendererLightCache.getGlobalRevision(),
+      lightingEnabled: () => this.worldRendererConfig.enableLighting !== false
+    })
     this.onRenderDistanceChanged = viewDistance => {
       this.chunkMeshManager.updateViewDistance(viewDistance)
     }
@@ -563,6 +575,9 @@ export class WorldRendererThree extends WorldRendererCommon {
       this.cursorBlock.setHighlightCursorBlock(value ? new Vec3(value.x, value.y, value.z) : null, value?.shapes)
     })
     this.onReactivePlayerStateUpdated('diggingBlock', value => {
+      if (value && (value.stage == null || value.stage === 0) && isClientLightTraceEnabled()) {
+        recordClientLightTrace({ phase: 'inputClick', sectionKey: `${value.x},${value.y},${value.z}` })
+      }
       this.cursorBlock.updateBreakAnimation(value ? { x: value.x, y: value.y, z: value.z } : undefined, value?.stage ?? null, value?.mergedShape)
     })
     this.onReactivePlayerStateUpdated('perspective', value => {
@@ -594,6 +609,13 @@ export class WorldRendererThree extends WorldRendererCommon {
     this.onReactiveConfigUpdated('futuristicReveal', () => {
       this.updateModulesFromConfig()
     })
+    this.onReactiveConfigUpdated(
+      'enableLighting',
+      () => {
+        this.rerenderAllChunks()
+      },
+      false
+    )
     this.onReactiveDebugUpdated('disableEntities', () => {
       this.entities.syncSceneAttachment()
     })
@@ -830,6 +852,10 @@ export class WorldRendererThree extends WorldRendererCommon {
         if (camCollisionBytes > 0) {
           text += `CAM: ${formatCompact(camCollisionBytes)}b `
         }
+        const entityLightBytes = this.rendererLightCache.getAllocatedBytes()
+        if (entityLightBytes > 0) {
+          text += `ELIGHT: ${formatCompact(entityLightBytes)}b `
+        }
         const pf = formatPerformanceFactorsDebug(this.reactiveState.world.instabilityFactors)
         if (pf) text += `PF: ${pf} `
         // entities can be seen in F3
@@ -884,45 +910,37 @@ export class WorldRendererThree extends WorldRendererCommon {
     if (this.pendingSectionUpdates.size === 0) return
 
     const now = performance.now()
-    const sectionHeight = this.getSectionHeight()
-    const ready: string[] = []
-
-    for (const key of this.pendingSectionUpdates.keys()) {
-      const startedAt = this.pendingSectionBufferStartTimes.get(key) ?? now
-      const sinceFirst = now - startedAt
-
-      if (sinceFirst < WorldRendererThree.MAX_SECTION_UPDATE_BUFFER_MS) {
-        // Still within this section's grace window — wait if any neighbor is
-        // currently being re-meshed so we don't briefly expose a hole between
-        // the just-updated section and a stale neighbor (sky-flicker bug).
-        const [sx, sy, sz] = key.split(',').map(Number)
-        const neighborKeys = [
-          `${sx - 16},${sy},${sz}`,
-          `${sx + 16},${sy},${sz}`,
-          `${sx},${sy - sectionHeight},${sz}`,
-          `${sx},${sy + sectionHeight},${sz}`,
-          `${sx},${sy},${sz - 16}`,
-          `${sx},${sy},${sz + 16}`
-        ]
-        let neighborBusy = false
-        for (const neighborKey of neighborKeys) {
-          if (this.sectionsWaiting.has(neighborKey) && !this.pendingSectionUpdates.has(neighborKey) && this.sectionObjects[neighborKey]) {
-            neighborBusy = true
-            break
+    // Face-adjacent buffered sections are installed as one group: a lone
+    // install would show the neighbour's faces still culled against the old
+    // block state, i.e. a see-through hole (sky flash) on dig/place.
+    const ready = selectReadySectionFlushes({
+      pendingKeys: this.pendingSectionUpdates.keys(),
+      startedAt: key => this.pendingSectionBufferStartTimes.get(key),
+      now,
+      maxBufferMs: WorldRendererThree.MAX_SECTION_UPDATE_BUFFER_MS,
+      sectionHeight: this.getSectionHeight(),
+      isOutstanding: key => this.sectionsWaiting.has(key) && !this.pendingSectionUpdates.has(key),
+      ...(this.lightCoordinator.isSessionLive()
+        ? {
+            isTopologyOutstanding: (key: string) => this.lightCoordinator.pendingTopologyBySection.has(key) && !this.pendingSectionUpdates.has(key)
           }
-        }
-        if (neighborBusy) continue
-      }
-
-      ready.push(key)
-    }
+        : {}),
+      hasSectionObject: key => !!this.sectionObjects[key]
+    })
 
     if (ready.length === 0) return
 
-    for (const key of ready) {
+    for (const { key, reason } of ready) {
       const update = this.pendingSectionUpdates.get(key)!
       this.pendingSectionUpdates.delete(key)
       this.pendingSectionBufferStartTimes.delete(key)
+      if (isClientLightTraceEnabled()) {
+        recordClientLightTrace({
+          phase: 'flush',
+          sectionKey: key,
+          flushReason: reason
+        })
+      }
 
       const chunkCoords = update.key.split(',')
       const chunkKey = `${chunkCoords[0]},${chunkCoords[2]}`
@@ -932,6 +950,14 @@ export class WorldRendererThree extends WorldRendererCommon {
         continue
       }
 
+      const decision = this.lightCoordinator.evaluateOwnerGeometry(update)
+      if (!decision.accepted || update.geometry?.hadErrors) {
+        this.lightCoordinator.noteRejectedOwnerGeometry(update.key, undefined, { expectLaterFinished: false })
+        continue
+      }
+      this.lightCoordinator.acknowledgeAcceptedTopology(update)
+      if (decision.keepCovering) this.lightCoordinator.maybeDispatchCoveringRemesh(update.key)
+
       if (!this.chunkMeshManager.sectionHasRenderableContent(update.geometry)) {
         this.chunkMeshManager.releaseSection(update.key)
         continue
@@ -966,6 +992,14 @@ export class WorldRendererThree extends WorldRendererCommon {
         return
       }
 
+      const decision = this.lightCoordinator.evaluateOwnerGeometry(data)
+      if (!decision.accepted || data.geometry?.hadErrors) {
+        this.lightCoordinator.noteRejectedOwnerGeometry(data.key, undefined, { expectLaterFinished: true })
+        return
+      }
+      this.lightCoordinator.acknowledgeAcceptedTopology(data)
+      if (decision.keepCovering) this.lightCoordinator.maybeDispatchCoveringRemesh(data.key)
+
       if (this.sectionObjects[data.key]) {
         this.pendingSectionUpdates.set(data.key, data)
         // Per-section deadline: only set if we don't already have one, so
@@ -973,6 +1007,13 @@ export class WorldRendererThree extends WorldRendererCommon {
         if (!this.pendingSectionBufferStartTimes.has(data.key)) {
           this.pendingSectionBufferStartTimes.set(data.key, performance.now())
         }
+        if (isClientLightTraceEnabled()) {
+          recordClientLightTrace({
+            phase: 'pending',
+            sectionKey: data.key,
+            queueDepth: this.pendingSectionUpdates.size
+          })
+        }
         return
       }
 
@@ -1552,8 +1593,8 @@ export class WorldRendererThree extends WorldRendererCommon {
     }
   }
 
-  removeColumn(x, z) {
-    super.removeColumn(x, z)
+  removeColumn(x, z, opts?: { preserveClientLight?: boolean }) {
+    super.removeColumn(x, z, opts)
 
     this.clearPendingSectionUpdatesForChunk(x, z)
     const sectionHeight = this.getSectionHeight()

package/src/wasm-mesher/bridge/render-from-wasm.ts

@@ -3,6 +3,7 @@
 // This file takes WASM output and generates full Three.js buffer geometry
 
 import * as THREE from 'three'
+import { isClientLightProbeBlock } from '../../lighting/debug/clientLightProbe'
 import worldBlockProviderModule, { WorldBlockProvider } from 'mc-assets/dist/worldBlockProvider'
 import blocksAtlasesJson from 'mc-assets/dist/blocksAtlases.json'
 import blockStatesModels from 'mc-assets/dist/blockStatesModels.json'
@@ -692,7 +693,26 @@ export function renderWasmOutputToGeometry(
           },
           shaderWordBuffer
         )
-        if (emitted) continue
+        if (emitted) {
+          if (isClientLightProbeBlock(bx, by, bz)) {
+            console.log('[lightProbe:shaderCube]', {
+              time: Date.now(),
+              position: [bx, by, bz],
+              blockStateId,
+              name: prismBlock.name,
+              useModelLighting: false,
+              wasmSky: block.sky_light_data?.map(values => [...values]),
+              visibleFaces: block.visible_faces,
+              jsNeighborSky: Object.fromEntries(
+                Object.entries(elemFaces).map(([face, info]) => [
+                  face,
+                  world?.getChannelLightNorm(new Vec3(bx, by, bz).offset(info.dir[0], info.dir[1], info.dir[2])).sky
+                ])
+              )
+            })
+          }
+          continue
+        }
       }
     }
 
@@ -842,6 +862,20 @@ export function renderWasmOutputToGeometry(
           const tint = getTint(matchingEFace, cachedModel.blockName, cachedModel.blockProps, biome, world)
 
           const useModelLighting = (!cachedModel.isCube || globalMatrix != null) && world
+          if (isClientLightProbeBlock(bx, by, bz)) {
+            console.log('[lightProbe:face]', {
+              time: Date.now(),
+              position: [bx, by, bz],
+              faceName,
+              blockStateId,
+              name: prismBlock.name,
+              isCube: cachedModel.isCube,
+              rotated: globalMatrix != null,
+              useModelLighting: Boolean(useModelLighting),
+              wasmSky: skyValuesRaw ? [...skyValuesRaw] : null,
+              jsNeighborSky: world?.getChannelLightNorm(new Vec3(bx, by, bz).offset(...transformedDirI)).sky
+            })
+          }
           const baseChannels = useModelLighting
             ? world.getChannelLightNorm(new Vec3(bx, by, bz).offset(transformedDirI[0], transformedDirI[1], transformedDirI[2]))
             : null
@@ -921,6 +955,17 @@ export function renderWasmOutputToGeometry(
             tgtCol.push(tintAo[0], tintAo[1], tintAo[2])
             tgtSky.push(skyLightNorm)
             tgtBlock.push(blockLightNorm)
+            if (isClientLightProbeBlock(bx, by, bz)) {
+              console.log('[lightProbe:vertex]', {
+                time: Date.now(),
+                position: [bx, by, bz],
+                faceName,
+                cornerIdx,
+                useModelLighting: Boolean(useModelLighting),
+                skyLightNorm,
+                blockLightNorm
+              })
+            }
 
             const baseu = (pos[3] - 0.5) * uvcs - (pos[4] - 0.5) * uvsn + 0.5
             const basev = (pos[3] - 0.5) * uvsn + (pos[4] - 0.5) * uvcs + 0.5