minecraft-renderer 0.1.37 → 0.1.39

package/src/mesher/test/splitColumnWasmOutput.test.ts

@@ -0,0 +1,163 @@
+//@ts-nocheck
+import { test, expect } from 'vitest'
+import {
+  splitColumnWasmOutputToSections,
+  renderWasmOutputToGeometry,
+  WasmGeometryOutput,
+} from '../../wasm-lib/render-from-wasm'
+
+const VERSION = '1.16.5'
+const STONE = 1 // 1.16.5 stone state id
+
+// Face mask layout (matches FACE_DIRS in wasm-mesher / render-from-wasm.ts).
+const FACE_UP = 1 << 0
+const FACE_DOWN = 1 << 1
+const FACE_NORTH = 1 << 2
+const FACE_SOUTH = 1 << 3
+const FACE_WEST = 1 << 4
+const FACE_EAST = 1 << 5
+const SIDE_FACES = FACE_NORTH | FACE_SOUTH | FACE_WEST | FACE_EAST
+
+// Build a synthetic full-column WASM mesher output by hand. This avoids
+// pulling in `wasm-pack`/the Rust crate from this unit test — the helper
+// under test is pure JS, so an in-memory fixture is sufficient.
+//
+// Scenario: two adjacent stone blocks at world Y=15 and Y=16. Because
+// they are stacked and opaque, Rust mesher would emit:
+//   - (x,15,z): bottom face only, top face is suppressed by Y=16
+//   - (x,16,z): top face only,    bottom face is suppressed by Y=15
+// We hand-craft that output here.
+function makeSeamFixture(): WasmGeometryOutput {
+  const blocks: WasmGeometryOutput['blocks'] = []
+  for (let z = 0; z < 16; z++) {
+    for (let x = 0; x < 16; x++) {
+      blocks.push({
+        position: [x, 15, z],
+        block_state_id: STONE,
+        // Y=15 is occluded above by the Y=16 stone — the seam neighbor
+        // info is baked in here at the per-block level.
+        visible_faces: FACE_DOWN | SIDE_FACES,
+        ao_data: [],
+        light_data: [],
+      })
+      blocks.push({
+        position: [x, 16, z],
+        block_state_id: STONE,
+        // Y=16 is occluded below by the Y=15 stone (the seam from the
+        // other side).
+        visible_faces: FACE_UP | SIDE_FACES,
+        ao_data: [],
+        light_data: [],
+      })
+    }
+  }
+  // Add an isolated block in a third section, so we cover a section
+  // that has no seam interaction.
+  blocks.push({
+    position: [0, 64, 0],
+    block_state_id: STONE,
+    visible_faces: FACE_UP | FACE_DOWN | SIDE_FACES,
+    ao_data: [],
+    light_data: [],
+  })
+  return {
+    blocks,
+    block_count: blocks.length,
+    block_iterations: 0,
+  }
+}
+
+test('splitColumnWasmOutputToSections: per-section split is equivalent to manual filter+render at the y=15/16 seam', () => {
+  const fullColumn = makeSeamFixture()
+
+  const requested = [
+    { x: 0, y: 0, z: 0 },   // contains Y=15 row only
+    { x: 0, y: 16, z: 0 },  // contains Y=16 row only
+    { x: 0, y: 32, z: 0 },  // empty section
+    { x: 0, y: 64, z: 0 },  // contains the isolated block at Y=64
+  ]
+
+  const split = splitColumnWasmOutputToSections(fullColumn, requested, { version: VERSION })
+
+  expect(split.size).toBe(4)
+  for (const r of requested) {
+    expect(split.has(`${r.x},${r.y},${r.z}`)).toBe(true)
+  }
+
+  // Reference: do the same split manually (exactly what the helper is
+  // supposed to do internally) and confirm the rendered geometry
+  // matches byte-for-byte.
+  for (const r of requested) {
+    const yLo = r.y
+    const yHi = r.y + 16
+    const sectionBlocks = fullColumn.blocks.filter(b => b.position[1] >= yLo && b.position[1] < yHi)
+    const reference = renderWasmOutputToGeometry(
+      {
+        blocks: sectionBlocks,
+        block_count: sectionBlocks.length,
+        block_iterations: fullColumn.block_iterations,
+      },
+      VERSION,
+      `${r.x},${r.y},${r.z}`,
+      { x: r.x + 8, y: r.y + 8, z: r.z + 8 },
+      undefined
+    )
+    const got = split.get(`${r.x},${r.y},${r.z}`)!.exported
+    expect(got.key).toBe(reference.key)
+    expect(got.position).toEqual(reference.position)
+    expect(got.geometry.positions).toEqual(reference.geometry.positions)
+    expect(got.geometry.normals).toEqual(reference.geometry.normals)
+    expect(got.geometry.colors).toEqual(reference.geometry.colors)
+    expect(got.geometry.uvs).toEqual(reference.geometry.uvs)
+    expect(got.geometry.indices).toEqual(reference.geometry.indices)
+  }
+
+  // Empty section returns a real (non-undefined) entry with empty geometry
+  // buffers and zero blocksCount.
+  const emptyEntry = split.get('0,32,0')!
+  expect(emptyEntry).toBeDefined()
+  expect(emptyEntry.exported.geometry.positions).toEqual([])
+  expect(emptyEntry.exported.geometry.indices).toEqual([])
+  expect(emptyEntry.blocksCount).toBe(0)
+
+  // Seam preservation: the Y=15/16 sections produce non-empty geometry,
+  // and crucially the y=15 section does NOT contain the (Y=15 top-face)
+  // that would have been emitted if the helper failed to honor the
+  // already-baked-in `visible_faces` mask. The cleanest structural
+  // assertion is that the seam-sections each contain only the expected
+  // number of unique vertical faces. With FACE_UP/FACE_DOWN suppressed
+  // at the seam, each block in those sections contributes 1 horizontal
+  // face + 4 side faces = 5 quads; both sections also have identical
+  // block counts (256 blocks), so their vertex/index counts must match.
+  const lower = split.get('0,0,0')!.exported
+  const upper = split.get('0,16,0')!.exported
+  expect(lower.geometry.positions.length).toBeGreaterThan(0)
+  expect(upper.geometry.positions.length).toBeGreaterThan(0)
+  expect(lower.geometry.positions.length).toBe(upper.geometry.positions.length)
+  expect(lower.geometry.indices.length).toBe(upper.geometry.indices.length)
+  // blocksCount must reflect the per-section bucket size, not the column
+  // total. Both seam sections contain 256 blocks each.
+  expect(split.get('0,0,0')!.blocksCount).toBe(256)
+  expect(split.get('0,16,0')!.blocksCount).toBe(256)
+})
+
+test('splitColumnWasmOutputToSections: empty requested-keys list returns empty map', () => {
+  const fullColumn = makeSeamFixture()
+  const out = splitColumnWasmOutputToSections(fullColumn, [], { version: VERSION })
+  expect(out.size).toBe(0)
+})
+
+test('splitColumnWasmOutputToSections: blocks outside requested sections are dropped', () => {
+  const fullColumn = makeSeamFixture()
+  // Only request the empty Y=32 section. Y=15/16/64 blocks must NOT
+  // leak into it.
+  const out = splitColumnWasmOutputToSections(
+    fullColumn,
+    [{ x: 0, y: 32, z: 0 }],
+    { version: VERSION }
+  )
+  const empty = out.get('0,32,0')!
+  expect(empty.exported.geometry.positions).toEqual([])
+  expect(empty.exported.geometry.indices).toEqual([])
+  expect(empty.blocksCount).toBe(0)
+})

package/src/three/chunkMeshManager.ts

@@ -28,17 +28,60 @@ export interface SectionObject extends THREE.Group {
   headsContainer?: THREE.Group
   bannersContainer?: THREE.Group
   boxHelper?: THREE.BoxHelper
+  /**
+   * World-space coordinates of the section origin. Cached so that
+   * {@link ChunkMeshManager.updateBoxHelper} can position lazily-created
+   * border helpers correctly under camera-relative rendering, where
+   * `mesh.position` is proxied to (world - sceneOrigin) and cannot be
+   * reused directly for objects that are tracked separately.
+   */
+  worldX?: number
+  worldY?: number
+  worldZ?: number
   foutain?: boolean
+  /**
+   * True while the section is held invisible by the "Batch Chunks Display"
+   * (`_renderByChunks`) feature, waiting for the parent chunk to finish meshing
+   * before being shown together with the rest of the chunk.
+   */
+  _waitingForChunkDisplay?: boolean
 }
 
 export class ChunkMeshManager {
   private readonly meshPool: ChunkMeshPool[] = []
   private readonly activeSections = new Map<string, ChunkMeshPool>()
   readonly sectionObjects: Record<string, SectionObject> = {}
+  /**
+   * Sections kept invisible because the "Batch Chunks Display" option is on
+   * and their parent chunk hasn't finished meshing yet. Keyed by chunk key
+   * (`x,z`); flushed by `WorldRendererThree.finishChunk(chunkKey)`.
+   */
+  readonly waitingChunksToDisplay: Record<string, string[]> = {}
+  /**
+   * Chunks whose mesh batch is fully ready but kept invisible by the
+   * WASM near-first reveal gate because at least one nearer column is
+   * not yet finished. Value = enqueue timestamp (ms), used by the
+   * expected-delivery grace window in `isBlockedByNearer`.
+   */
+  readonly pendingNearReveal = new Map<string, number>()
+  private readonly nearRevealTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  private readonly nearRevealGraceTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  // Force-flush pending reveal after this many ms (last-resort safety).
+  private static readonly NEAR_REVEAL_TIMEOUT_MS = 5000
+  // Soft window during which the gate also waits for *expected* nearer
+  // columns that have not arrived yet (covers far-worker-beats-near-worker).
+  private static readonly EXPECTED_NEAR_GRACE_MS = 1500
   private poolSize!: number
   private maxPoolSize!: number
   private minPoolSize!: number
   private readonly signHeadsRenderer: SignHeadsRenderer
+  /**
+   * Shared transparent material used as the basis for the wireframe chunk
+   * border `BoxHelper` created lazily in {@link updateBoxHelper}. Kept on the
+   * manager so the BoxHelper machinery doesn't allocate a new material per
+   * section.
+   */
+  private readonly chunkBoxMaterial = new THREE.MeshBasicMaterial({ color: 0x00_00_00, transparent: true, opacity: 0 })
 
   // Performance tracking
   private hits = 0
@@ -156,6 +199,17 @@ export class ChunkMeshManager {
     // Store metadata
     sectionObject.tilesCount = geometryData.positions.length / 3 / 4
     sectionObject.blocksCount = geometryData.blocksCount
+    sectionObject.worldX = geometryData.sx
+    sectionObject.worldY = geometryData.sy
+    sectionObject.worldZ = geometryData.sz
+    // Stamp the section key so modules (e.g. sciFiWorldReveal) can resolve
+    // mesh -> section without falling back to sceneOrigin world-position math.
+    ;(sectionObject as any).sectionKey = sectionKey
+    // Tag the group so `WorldRendererThree.getThirdPersonCamera` raycast can
+    // still find chunk meshes — the old `WorldBlockGeometry` set this name
+    // unconditionally; the pooling port lost that and only the border-helper
+    // path used to restore it.
+    sectionObject.name = 'chunk'
 
     try {
       // Add signs container
@@ -218,13 +272,220 @@ export class ChunkMeshManager {
     this.scene.add(sectionObject)
     sectionObject.matrixAutoUpdate = false
 
+    // Create chunk border helper eagerly when the option is on so freshly
+    // streamed sections immediately get the F3+G yellow wireframe instead of
+    // appearing only on the next toggle.
+    if (this.worldRenderer.displayOptions?.inWorldRenderingConfig?.showChunkBorders) {
+      this.updateBoxHelper(sectionKey, true)
+    }
+
+    // Honor "Batch Chunks Display" (`_renderByChunks`): keep this section's
+    // mesh hidden until the whole chunk has finished meshing, so users see a
+    // chunk appear as a single 16xHx16 tile instead of streaming per-section.
+    // Updates to chunks that are already finished bypass batching to avoid
+    // flickering on block changes / lighting updates.
+    // For the WASM column path we force batching ON regardless of the user
+    // setting so the near-first reveal gate has sections to hold.
+    const chunkCoords = sectionKey.split(',')
+    const chunkKey = `${chunkCoords[0]},${chunkCoords[2]}`
+    const renderByChunks = !!this.worldRenderer.displayOptions
+      ?.inWorldRenderingConfig?._renderByChunks
+    const forceBatchForWasm = !!this.worldRenderer.worldRendererConfig?.wasmMesher
+    if ((renderByChunks || forceBatchForWasm) && !this.worldRenderer.finishedChunks[chunkKey]) {
+      sectionObject.visible = false
+      sectionObject._waitingForChunkDisplay = true
+      const list = this.waitingChunksToDisplay[chunkKey] ?? (this.waitingChunksToDisplay[chunkKey] = [])
+      if (!list.includes(sectionKey)) list.push(sectionKey)
+    }
+
     return sectionObject
   }
 
+  /**
+   * Reveal all sections of a chunk that were held invisible by the
+   * "Batch Chunks Display" option. Called from `WorldRendererThree.finishChunk`.
+   *
+   * For the WASM path: if any nearer column is not yet finished, the
+   * reveal is deferred (parked in `pendingNearReveal`) and re-checked on
+   * the next chunkFinished / player-move / grace-expiry.
+   */
+  finishChunkDisplay (chunkKey: string): void {
+    const sectionKeys = this.waitingChunksToDisplay[chunkKey]
+    if (!sectionKeys) {
+      // No held sections (empty column / non-batched path) — but the
+      // chunk just transitioned to finished, so re-check pending farther.
+      this.tryRevealPending()
+      return
+    }
+    if (this.isWasmGateActive() && this.isBlockedByNearer(chunkKey, 0)) {
+      this.pendingNearReveal.set(chunkKey, Date.now())
+      this.armNearRevealTimer(chunkKey)
+      this.armExpectedGraceTimer(chunkKey)
+      return
+    }
+    this.flushChunkDisplay(chunkKey)
+    this.tryRevealPending()
+  }
+
+  private flushChunkDisplay (chunkKey: string): void {
+    const sectionKeys = this.waitingChunksToDisplay[chunkKey]
+    this.pendingNearReveal.delete(chunkKey)
+    this.clearNearRevealTimer(chunkKey)
+    this.clearExpectedGraceTimer(chunkKey)
+    if (!sectionKeys) return
+    for (const sectionKey of sectionKeys) {
+      const sectionObject = this.sectionObjects[sectionKey]
+      if (!sectionObject) continue
+      sectionObject._waitingForChunkDisplay = false
+      sectionObject.visible = true
+    }
+    delete this.waitingChunksToDisplay[chunkKey]
+  }
+
+  // Re-check every parked entry; each has its own grace window via `ageMs`.
+  // Single pass is enough — pending entries are already finished, so flushing
+  // one cannot un-block another via this code path (cascading happens via
+  // chunkFinished events and per-pending grace timers).
+  tryRevealPending (): void {
+    if (this.pendingNearReveal.size === 0) return
+    const now = Date.now()
+    for (const [chunkKey, enqueuedAt] of [...this.pendingNearReveal]) {
+      if (!this.isBlockedByNearer(chunkKey, now - enqueuedAt)) {
+        this.flushChunkDisplay(chunkKey)
+      }
+    }
+  }
+
+  // Drop gate state for an unloaded column and re-evaluate any farther
+  // chunks that may have been blocked by it.
+  onChunkRemovedFromGate (chunkKey: string): void {
+    this.pendingNearReveal.delete(chunkKey)
+    this.clearNearRevealTimer(chunkKey)
+    this.clearExpectedGraceTimer(chunkKey)
+    delete this.waitingChunksToDisplay[chunkKey]
+    this.tryRevealPending()
+  }
+
+  private isWasmGateActive (): boolean {
+    return !!this.worldRenderer.worldRendererConfig?.wasmMesher
+  }
+
+  /**
+   * True if some chunk-grid position strictly closer to the viewer than
+   * `chunkKey` is not yet `finishedChunks=true`.
+   *
+   * Two regimes by `ageMs` (time spent in `pendingNearReveal`):
+   * - Within `EXPECTED_NEAR_GRACE_MS`: walks every expected position in
+   *   the view-distance circle; missing-and-not-finished counts as a
+   *   blocker (catches "far worker beats near worker").
+   * - After grace: only actually-loaded-but-not-finished columns block,
+   *   so a never-arriving column does not freeze the view.
+   */
+  private isBlockedByNearer (chunkKey: string, ageMs: number): boolean {
+    const viewer = this.worldRenderer.viewerChunkPosition
+    if (!viewer) return false
+    const ownParts = chunkKey.split(',')
+    if (ownParts.length !== 2) return false
+    const ownX = Number(ownParts[0])
+    const ownZ = Number(ownParts[1])
+    const playerCx = Math.floor(viewer.x / 16)
+    const playerCz = Math.floor(viewer.z / 16)
+    const myDx = (ownX >> 4) - playerCx
+    const myDz = (ownZ >> 4) - playerCz
+    const myDist = myDx * myDx + myDz * myDz
+    if (myDist === 0) return false
+    const finishedChunks = this.worldRenderer.finishedChunks
+    const loadedChunks = this.worldRenderer.loadedChunks
+    const viewDist = this.worldRenderer.viewDistance
+    const inGrace = ageMs < ChunkMeshManager.EXPECTED_NEAR_GRACE_MS && viewDist > 0
+
+    if (inGrace) {
+      const viewDistSq = viewDist * viewDist
+      const limit = Math.min(viewDist, Math.ceil(Math.sqrt(Math.max(0, myDist - 1))))
+      for (let dCx = -limit; dCx <= limit; dCx++) {
+        for (let dCz = -limit; dCz <= limit; dCz++) {
+          const oDistSq = dCx * dCx + dCz * dCz
+          if (oDistSq >= myDist || oDistSq > viewDistSq) continue
+          const ox = (playerCx + dCx) << 4
+          const oz = (playerCz + dCz) << 4
+          const otherKey = `${ox},${oz}`
+          if (otherKey === chunkKey) continue
+          if (!finishedChunks[otherKey]) return true
+        }
+      }
+      return false
+    }
+
+    for (const otherKey in loadedChunks) {
+      if (otherKey === chunkKey || finishedChunks[otherKey]) continue
+      const parts = otherKey.split(',')
+      if (parts.length !== 2) continue
+      const odx = (Number(parts[0]) >> 4) - playerCx
+      const odz = (Number(parts[1]) >> 4) - playerCz
+      if (odx * odx + odz * odz < myDist) return true
+    }
+    return false
+  }
+
+  private armNearRevealTimer (chunkKey: string): void {
+    if (this.nearRevealTimers.has(chunkKey)) return
+    const timer = setTimeout(() => {
+      this.nearRevealTimers.delete(chunkKey)
+      if (!this.pendingNearReveal.has(chunkKey)) return
+      console.warn(`[chunk-reveal] safety timeout for ${chunkKey} — a nearer pending column never finished, force-revealing`)
+      this.flushChunkDisplay(chunkKey)
+      this.tryRevealPending()
+    }, ChunkMeshManager.NEAR_REVEAL_TIMEOUT_MS)
+    this.nearRevealTimers.set(chunkKey, timer)
+  }
+
+  private clearNearRevealTimer (chunkKey: string): void {
+    const timer = this.nearRevealTimers.get(chunkKey)
+    if (timer) {
+      clearTimeout(timer)
+      this.nearRevealTimers.delete(chunkKey)
+    }
+  }
+
+  /**
+   * Schedule a re-evaluation just after the grace window expires so that
+   * "expected but never arrived" positions stop blocking promptly,
+   * without waiting for the next chunkFinished / player-move event.
+   */
+  private armExpectedGraceTimer (chunkKey: string): void {
+    if (this.nearRevealGraceTimers.has(chunkKey)) return
+    const timer = setTimeout(() => {
+      this.nearRevealGraceTimers.delete(chunkKey)
+      if (!this.pendingNearReveal.has(chunkKey)) return
+      this.tryRevealPending()
+    }, ChunkMeshManager.EXPECTED_NEAR_GRACE_MS + 50)
+    this.nearRevealGraceTimers.set(chunkKey, timer)
+  }
+
+  private clearExpectedGraceTimer (chunkKey: string): void {
+    const timer = this.nearRevealGraceTimers.get(chunkKey)
+    if (timer) {
+      clearTimeout(timer)
+      this.nearRevealGraceTimers.delete(chunkKey)
+    }
+  }
+
   cleanupSection (sectionKey: string) {
     // Remove section object from scene
     const sectionObject = this.sectionObjects[sectionKey]
     if (sectionObject) {
+      // Drop from any pending "batch display" queue so we don't try to flip
+      // visibility on a stale (released) object later.
+      if (sectionObject._waitingForChunkDisplay) {
+        const chunkCoords = sectionKey.split(',')
+        const chunkKey = `${chunkCoords[0]},${chunkCoords[2]}`
+        const list = this.waitingChunksToDisplay[chunkKey]
+        if (list) {
+          const idx = list.indexOf(sectionKey)
+          if (idx !== -1) list.splice(idx, 1)
+          if (list.length === 0) delete this.waitingChunksToDisplay[chunkKey]
+        }
+      }
       // Cleanup banner textures before disposing
       if (sectionObject.bannersContainer) {
         sectionObject.bannersContainer.traverse((child) => {
@@ -243,6 +504,21 @@ export class ChunkMeshManager {
       }
       this.worldRenderer.sceneOrigin.removeAndUntrackAll(sectionObject)
       this.scene.remove(sectionObject)
+      // boxHelper lives directly on the scene (so it stays world-anchored
+      // under camera-relative rendering), so it must be cleaned up explicitly
+      // — `removeAndUntrackAll` above only walks `sectionObject` descendants.
+      if (sectionObject.boxHelper) {
+        this.worldRenderer.sceneOrigin.removeAndUntrack(sectionObject.boxHelper)
+        this.scene.remove(sectionObject.boxHelper)
+        sectionObject.boxHelper.geometry.dispose()
+        const helperMat = sectionObject.boxHelper.material as THREE.Material | THREE.Material[]
+        if (Array.isArray(helperMat)) {
+          for (const m of helperMat) m.dispose()
+        } else {
+          helperMat.dispose()
+        }
+        sectionObject.boxHelper = undefined
+      }
       delete this.sectionObjects[sectionKey]
     }
   }
@@ -285,19 +561,28 @@ export class ChunkMeshManager {
   /**
    * Update box helper for a section
    */
-  updateBoxHelper (sectionKey: string, showChunkBorders: boolean, chunkBoxMaterial: THREE.Material) {
+  updateBoxHelper (sectionKey: string, showChunkBorders: boolean, chunkBoxMaterial: THREE.Material = this.chunkBoxMaterial) {
     const sectionObject = this.sectionObjects[sectionKey]
     if (!sectionObject?.mesh) return
 
     if (showChunkBorders) {
       if (!sectionObject.boxHelper) {
-        // mesh with static dimensions: 16x16x16
+        // Build a 16x16x16 reference mesh in world coordinates so BoxHelper's
+        // `setFromObject` produces the correct geometry. The reference mesh is
+        // not added to the scene; only the resulting BoxHelper is.
         const staticChunkMesh = new THREE.Mesh(new THREE.BoxGeometry(16, 16, 16), chunkBoxMaterial)
-        staticChunkMesh.position.copy(sectionObject.mesh.position)
         const boxHelper = new THREE.BoxHelper(staticChunkMesh, 0xff_ff_00)
         boxHelper.name = 'helper'
-        sectionObject.add(boxHelper)
-        sectionObject.name = 'chunk'
+        // Add directly to the scene and track it through sceneOrigin so that
+        // camera-relative rendering (floating origin) keeps the helper pinned
+        // to its world coordinates instead of following the camera.
+        const sx = sectionObject.worldX ?? 0
+        const sy = sectionObject.worldY ?? 0
+        const sz = sectionObject.worldZ ?? 0
+        this.worldRenderer.sceneOrigin.track(boxHelper, { updateMatrix: true })
+        boxHelper.position.set(sx, sy, sz)
+        boxHelper.updateMatrix()
+        this.scene.add(boxHelper)
         sectionObject.boxHelper = boxHelper
       }
       sectionObject.boxHelper.visible = true
@@ -306,6 +591,28 @@ export class ChunkMeshManager {
     }
   }
 
+  /**
+   * Create / toggle chunk border helpers for every active section. Used by
+   * `WorldRendererThree.updateShowChunksBorder` so the F3+G hotkey works
+   * after the move from `WorldBlockGeometry` (which created the helpers
+   * eagerly per section) to the pooled `ChunkMeshManager`.
+   */
+  updateAllBoxHelpers (showChunkBorders: boolean) {
+    for (const sectionKey of Object.keys(this.sectionObjects)) {
+      this.updateBoxHelper(sectionKey, showChunkBorders)
+    }
+  }
+
+  /**
+   * Forward to {@link SignHeadsRenderer.cleanChunkTextures} so callers in
+   * `WorldRendererThree` (which historically owned the sign-texture cache)
+   * can invalidate cached sign textures when a section is marked dirty,
+   * without reaching into the manager's private members.
+   */
+  cleanSignChunkTextures (x: number, z: number) {
+    this.signHeadsRenderer.cleanChunkTextures(x, z)
+  }
+
   /**
    * Get mesh for section if it exists
    */
@@ -459,6 +766,13 @@ export class ChunkMeshManager {
 
     this.meshPool.length = 0
     this.activeSections.clear()
+    this.chunkBoxMaterial.dispose()
+    // Drop any pending near-first reveal state and cancel safety timers.
+    this.pendingNearReveal.clear()
+    for (const timer of this.nearRevealTimers.values()) clearTimeout(timer)
+    this.nearRevealTimers.clear()
+    for (const timer of this.nearRevealGraceTimers.values()) clearTimeout(timer)
+    this.nearRevealGraceTimers.clear()
   }
 
   // Private helper methods
@@ -667,6 +981,12 @@ export class ChunkMeshManager {
   updateSectionsVisibility (): void {
     const cameraPos = this.worldRenderer.cameraSectionPos
     for (const [sectionKey, sectionObject] of Object.entries(this.sectionObjects)) {
+      // Don't override "Batch Chunks Display" hiding — those sections must
+      // stay invisible until their chunk finishes meshing.
+      if (sectionObject._waitingForChunkDisplay) {
+        sectionObject.visible = false
+        continue
+      }
       if (!this.performanceOverrideDistance) {
         sectionObject.visible = true
         continue
@@ -805,4 +1125,21 @@ class SignHeadsRenderer {
     textures[texturekey] = tex
     return tex
   }
+
+  /**
+   * Dispose all cached sign textures for the chunk containing world coords
+   * (x, z). Called from `WorldRendererThree.cleanChunkTextures` so that
+   * re-meshes triggered by `setSectionDirty` (e.g. a player edits a sign)
+   * pick up fresh block-entity NBT instead of returning the stale cached
+   * texture from {@link SignHeadsRenderer.getSignTexture}.
+   */
+  cleanChunkTextures (x: number, z: number) {
+    const key = `${Math.floor(x / 16)},${Math.floor(z / 16)}`
+    const textures = this.chunkTextures.get(key)
+    if (!textures) return
+    for (const k of Object.keys(textures)) {
+      textures[k].dispose()
+      delete textures[k]
+    }
+  }
 }

package/src/three/modules/cameraBobbing.ts

@@ -26,8 +26,15 @@ export class CameraBobbingModule implements RendererModuleController {
     if (!this.enabled) return
     const config = this.worldRenderer.displayOptions.inWorldRenderingConfig
     const { perspective } = this.worldRenderer.playerStateReactive
+    // Spectator (gm3) flies through blocks and does not "walk" — view bobbing
+    // there only makes the camera feel jittery/unstable. Keep it gated even
+    // when the user has `viewBobbing` enabled in settings.
+    const shouldBobCamera =
+      config.viewBobbing
+      && perspective === 'first_person'
+      && !this.worldRenderer.playerStateUtils.isSpectator()
 
-    if (config.viewBobbing && perspective === 'first_person') {
+    if (shouldBobCamera) {
       if (this.worldRenderer.playerStateReactive.walkDist !== this.lastBobWalkDist) {
         this.lastBobTickTime = performance.now()
         this.lastBobWalkDist = this.worldRenderer.playerStateReactive.walkDist