minecraft-renderer 0.1.47 → 0.1.49

package/src/three/modules/sciFiWorldReveal.ts

@@ -3,6 +3,7 @@ import * as THREE from 'three'
 import type { WorldRendererThree } from '../worldRendererThree'
 import type { RendererModuleController, RendererModuleManifest } from '../rendererModuleSystem'
 import type { MesherGeometryOutput } from '../../mesher-shared/shared'
+import type { GlobalBlockBufferShaderData } from '../globalBlockBuffer'
 
 const SCI_FI_CYAN = new THREE.Color(13 / 255, 234 / 255, 238 / 255)
 const CHUNKS_THRESHOLD = 9
@@ -21,7 +22,10 @@ interface RevealingSection {
   wireframeGroup: THREE.Group
   revealStartTime: number
   phase: 'wireframe' | 'transitioning' | 'complete'
-  originalMeshRef: THREE.Mesh | null
+  /** Legacy + shader render meshes hidden during reveal */
+  renderMeshRefs: THREE.Mesh[]
+  /** Shader cubes temporarily removed from globalBlockBuffer during reveal. */
+  globalShaderRestore?: GlobalBlockBufferShaderData
   wireframeMs: number
   revealMs: number
 }
@@ -44,6 +48,8 @@ export class SciFiWorldRevealModule implements RendererModuleController {
   private onWorldSwitchedCb: (() => void) | null = null
   private patched = false
   private initialWaveDone = false
+  /** True after every section from the first reveal wave has finished animating. */
+  private initialRevealWaveSettled = false
 
   // Wireframe materials
   private readonly wireframeMaterial!: THREE.LineBasicMaterial
@@ -61,11 +67,7 @@ export class SciFiWorldRevealModule implements RendererModuleController {
   private originalSceneAdd: ((...object: THREE.Object3D[]) => THREE.Scene) | null = null
   private originalHandleWorkerMessage: ((data: { geometry: MesherGeometryOutput; key: string; type: string }) => void) | null = null
 
-  private configEnabled = true
-
   constructor(private readonly worldRenderer: WorldRendererThree) {
-    this.configEnabled = this.worldRenderer.worldRendererConfig.futuristicReveal === true
-
     this.wireframeMaterial = new THREE.LineBasicMaterial({
       color: SCI_FI_CYAN,
       transparent: true,
@@ -83,9 +85,27 @@ export class SciFiWorldRevealModule implements RendererModuleController {
     })
   }
 
+  /** Read live config — option may sync after module construction (watchOptions). */
+  isFuturisticRevealConfigured (): boolean {
+    return this.worldRenderer.worldRendererConfig.futuristicReveal === true
+  }
+
+  /** Until the first cinematic wave fully completes, shader sections stay off the global buffer. */
+  isInInitialRevealCampaign (): boolean {
+    return this.enabled && !this.initialRevealWaveSettled
+  }
+
+  autoEnableCheck (): boolean {
+    return this.isFuturisticRevealConfigured()
+  }
+
   enable(): void {
-    if (!this.configEnabled) return
-    if (this.enabled) return
+    if (!this.isFuturisticRevealConfigured()) return
+    if (this.enabled && this.patched) return
+    if (this.enabled && !this.patched) {
+      this.patchWorldRenderer()
+      return
+    }
     this.enabled = true
     this.patchWorldRenderer()
   }
@@ -214,8 +234,7 @@ export class SciFiWorldRevealModule implements RendererModuleController {
    * Check if an object or its children is a mesh that needs reveal effect visibility patch
    */
   private checkAndPatchMesh(obj: THREE.Object3D): void {
-    // Check if this is a mesh with name === 'mesh'
-    if (obj instanceof THREE.Mesh && obj.name === 'mesh') {
+    if (obj instanceof THREE.Mesh && (obj.name === 'mesh' || obj.name === 'shaderMesh')) {
       const sectionKey = this.findSectionKeyForMesh(obj)
       if (sectionKey && this.shouldUseRevealEffect(sectionKey)) {
         obj.visible = false
@@ -280,13 +299,62 @@ export class SciFiWorldRevealModule implements RendererModuleController {
     return this.worldRenderer.getCameraPosition()
   }
 
-  /**
-   * Get original mesh for a section key
-   */
-  private getOriginalMesh(key: string): THREE.Mesh | null {
+  private sectionHasRevealContent(geometry: MesherGeometryOutput): boolean {
+    if ((geometry.wireframePositions?.length ?? 0) > 0) return true
+    if ((geometry.positions?.length ?? 0) > 0) return true
+    return (geometry.shaderCubes?.count ?? 0) > 0
+  }
+
+  /** Legacy `mesh` and instanced `shaderMesh` for a section. */
+  private getSectionRenderMeshes(key: string): THREE.Mesh[] {
     const sectionObject = this.worldRenderer.chunkMeshManager.sectionObjects[key]
-    if (!sectionObject) return null
-    return sectionObject.children.find(child => child.name === 'mesh') as THREE.Mesh | null
+    if (!sectionObject) return []
+    const meshes: THREE.Mesh[] = []
+    for (const name of ['mesh', 'shaderMesh'] as const) {
+      const child = sectionObject.children.find(c => c.name === name)
+      if (child instanceof THREE.Mesh) meshes.push(child)
+    }
+    return meshes
+  }
+
+  private hideSectionRenderMeshes(key: string): THREE.Mesh[] {
+    const meshes = this.getSectionRenderMeshes(key)
+    for (const m of meshes) {
+      m.visible = false
+      ;(m as any).hiddenByReveal = true
+    }
+    return meshes
+  }
+
+  private setMeshFadeOpacity(mesh: THREE.Mesh, opacity: number): void {
+    // ShaderMaterial ignores material.opacity; cloning breaks atlas uniforms.
+    if (mesh.name === 'shaderMesh') {
+      mesh.visible = opacity > 0.001
+      return
+    }
+    const mat = mesh.material
+    if (Array.isArray(mat)) return
+    if (!(mat as any).originalMaterial) {
+      ;(mat as any).originalMaterial = mat
+      const fadeMat = mat.clone()
+      fadeMat.transparent = true
+      fadeMat.opacity = opacity
+      fadeMat.needsUpdate = true
+      mesh.material = fadeMat
+    } else {
+      mat.opacity = opacity
+      mat.transparent = true
+      mat.needsUpdate = true
+    }
+  }
+
+  private restoreMeshMaterial(mesh: THREE.Mesh): void {
+    const originalMat = (mesh as any).originalMaterial as THREE.Material | undefined
+    if (!originalMat) return
+    const currentMat = mesh.material as THREE.Material
+    mesh.material = originalMat
+    if (currentMat !== originalMat) currentMat.dispose()
+    delete (mesh as any).originalMaterial
   }
 
   /**
@@ -307,6 +375,12 @@ export class SciFiWorldRevealModule implements RendererModuleController {
     // If already revealed or currently revealing, skip
     if (this.revealedChunks.has(key) || this.revealingSections.has(key)) return
 
+    // After the initial spawn wave, show streaming sections immediately (no wireframe flash).
+    if (this.revealTriggered && this.initialWaveDone) {
+      this.revealedChunks.add(key)
+      return
+    }
+
     // If reveal already triggered, start effect immediately (don't store in pending)
     if (this.revealTriggered) {
       this.startSectionReveal(key, geometry)
@@ -320,7 +394,10 @@ export class SciFiWorldRevealModule implements RendererModuleController {
    * Check if a section should use the reveal effect
    */
   shouldUseRevealEffect(key: string): boolean {
-    return this.enabled && !this.revealedChunks.has(key) && !this.revealingSections.has(key)
+    if (!this.enabled) return false
+    // Match registerSection: no cinematic hide for chunks loaded while moving.
+    if (this.revealTriggered && this.initialWaveDone) return false
+    return !this.revealedChunks.has(key) && !this.revealingSections.has(key)
   }
 
   /**
@@ -368,7 +445,7 @@ export class SciFiWorldRevealModule implements RendererModuleController {
    * Start the reveal effect for a single section
    */
   private startSectionReveal(key: string, geometry: MesherGeometryOutput): void {
-    if (!geometry.positions?.length) return
+    if (!this.sectionHasRevealContent(geometry)) return
 
     // Don't create if already exists
     if (this.revealingSections.has(key) || this.revealedChunks.has(key)) return
@@ -376,11 +453,10 @@ export class SciFiWorldRevealModule implements RendererModuleController {
     // Create wireframe geometry
     const wireframeGeom = this.createWireframeGeometry(geometry)
 
-    const original = this.getOriginalMesh(key)
-    if (original) {
-      original.visible = false
-        ; (original as any).hiddenByReveal = true
-    }
+    const global = this.worldRenderer.chunkMeshManager.globalBlockBuffer
+    const globalShaderRestore = global?.hasSection(key) ? global.takeSectionData(key) : undefined
+
+    const renderMeshRefs = this.hideSectionRenderMeshes(key)
     // Main wireframe
     const wireframe = new THREE.LineSegments(wireframeGeom, this.wireframeMaterial.clone())
     this.worldRenderer.sceneOrigin.track(wireframe)
@@ -413,25 +489,45 @@ export class SciFiWorldRevealModule implements RendererModuleController {
       wireframeGroup: group,
       revealStartTime: performance.now(),
       phase: 'wireframe',
-      originalMeshRef: null,
+      renderMeshRefs,
+      globalShaderRestore,
       wireframeMs,
       revealMs,
     }
 
     setTimeout(() => {
-      const m = this.getOriginalMesh(key)
-      if (m && !(m as any).hiddenByReveal) {
-        m.visible = false
-          ; (m as any).hiddenByReveal = true
+      for (const m of this.getSectionRenderMeshes(key)) {
+        if (!(m as any).hiddenByReveal) {
+          this.hideSectionRenderMeshes(key)
+        }
       }
     }, 0)
 
     this.revealingSections.set(key, section)
   }
 
-  /**
-   * Create wireframe geometry from mesh geometry
-   */
+  /** 16³ section bounds wireframe in section-local coords (−8…+8). */
+  private createSectionBoundsWireframe(): THREE.BufferGeometry {
+    const min = -8
+    const max = 8
+    const c = [
+      [min, min, min], [max, min, min], [min, max, min], [max, max, min],
+      [min, min, max], [max, min, max], [min, max, max], [max, max, max],
+    ] as const
+    const edges: [number, number][] = [
+      [0, 1], [1, 3], [3, 2], [2, 0],
+      [4, 5], [5, 7], [7, 6], [6, 4],
+      [0, 4], [1, 5], [2, 6], [3, 7],
+    ]
+    const linePositions: number[] = []
+    for (const [a, b] of edges) {
+      linePositions.push(...c[a]!, ...c[b]!)
+    }
+    const wireframeGeom = new THREE.BufferGeometry()
+    wireframeGeom.setAttribute('position', new THREE.Float32BufferAttribute(linePositions, 3))
+    return wireframeGeom
+  }
+
   private createWireframeGeometry(geometry: MesherGeometryOutput): THREE.BufferGeometry {
     if (geometry.wireframePositions && geometry.wireframePositions.length > 0) {
       const wireframeGeom = new THREE.BufferGeometry()
@@ -442,6 +538,10 @@ export class SciFiWorldRevealModule implements RendererModuleController {
     const positions = geometry.positions as Float32Array
     const indices = geometry.indices as Uint32Array | Uint16Array
 
+    if (!positions?.length || !indices?.length) {
+      return this.createSectionBoundsWireframe()
+    }
+
     const linePositions: number[] = []
     const edgeSet = new Set<string>()
 
@@ -529,18 +629,10 @@ export class SciFiWorldRevealModule implements RendererModuleController {
         if (elapsed > section.wireframeMs) {
           section.phase = 'transitioning'
 
-          // Get and show the original mesh with fade-in
-          section.originalMeshRef = this.getOriginalMesh(key)
-          if (section.originalMeshRef) {
-            section.originalMeshRef.visible = true
-            // Store original material and create fade version
-            const originalMat = section.originalMeshRef.material as THREE.MeshLambertMaterial
-            const fadeMat = originalMat.clone()
-            fadeMat.transparent = true
-            fadeMat.opacity = 0
-            fadeMat.needsUpdate = true
-              ; (section.originalMeshRef as any).originalMaterial = originalMat
-            section.originalMeshRef.material = fadeMat
+          section.renderMeshRefs = this.getSectionRenderMeshes(key)
+          for (const mesh of section.renderMeshRefs) {
+            mesh.visible = true
+            this.setMeshFadeOpacity(mesh, 0)
           }
         }
       } else if (section.phase === 'transitioning') {
@@ -564,10 +656,8 @@ export class SciFiWorldRevealModule implements RendererModuleController {
           glowMat.opacity = (1 - eased) * 0.55
         }
 
-        // Fade in original mesh
-        if (section.originalMeshRef?.material) {
-          const fadeMat = section.originalMeshRef.material as THREE.MeshLambertMaterial
-          fadeMat.opacity = eased
+        for (const mesh of section.renderMeshRefs) {
+          this.setMeshFadeOpacity(mesh, eased)
         }
 
         // Complete transition
@@ -592,17 +682,24 @@ export class SciFiWorldRevealModule implements RendererModuleController {
     this.revealingSections.delete(section.key)
     this.revealedChunks.add(section.key)
 
-    // Restore original material first
-    if (section.originalMeshRef) {
-      const originalMat = (section.originalMeshRef as any).originalMaterial
-      if (originalMat) {
-        const currentMat = section.originalMeshRef.material as THREE.Material
-        section.originalMeshRef.material = originalMat
-        currentMat.dispose()
-        delete (section.originalMeshRef as any).originalMaterial
-      }
-      section.originalMeshRef.visible = true
-      delete (section.originalMeshRef as any).hiddenByReveal
+    if (this.revealTriggered && this.revealingSections.size === 0) {
+      this.initialRevealWaveSettled = true
+    }
+
+    for (const mesh of section.renderMeshRefs) {
+      this.restoreMeshMaterial(mesh)
+      mesh.visible = true
+      delete (mesh as any).hiddenByReveal
+    }
+
+    this.worldRenderer.chunkMeshManager.migrateDeferredShaderToGlobal(section.key)
+
+    if (section.globalShaderRestore) {
+      this.worldRenderer.chunkMeshManager.globalBlockBuffer?.addSection(
+        section.key,
+        section.globalShaderRestore.words,
+        section.globalShaderRestore.count,
+      )
     }
 
     // Clean up wireframe group
@@ -655,6 +752,8 @@ export class SciFiWorldRevealModule implements RendererModuleController {
     this.revealedChunks.clear()
     this.finishedChunkCount = 0
     this.revealTriggered = false
+    this.initialWaveDone = false
+    this.initialRevealWaveSettled = false
     this.revealStartTime = 0
     this.pulseTime = 0
   }
@@ -665,16 +764,11 @@ export class SciFiWorldRevealModule implements RendererModuleController {
   forceCompleteAll(): void {
     const sections = [...this.revealingSections.values()]
     for (const section of sections) {
-      // Show original mesh immediately
-      if (!section.originalMeshRef) {
-        section.originalMeshRef = this.getOriginalMesh(section.key)
-      }
-      if (section.originalMeshRef) {
-        const originalMat = (section.originalMeshRef as any).originalMaterial
-        if (originalMat) {
-          section.originalMeshRef.material = originalMat
-        }
-        section.originalMeshRef.visible = true
+      section.renderMeshRefs = this.getSectionRenderMeshes(section.key)
+      for (const mesh of section.renderMeshRefs) {
+        this.restoreMeshMaterial(mesh)
+        mesh.visible = true
+        delete (mesh as any).hiddenByReveal
       }
       this.completeReveal(section)
     }
@@ -736,7 +830,7 @@ export class SciFiWorldRevealModule implements RendererModuleController {
       sections: [...this.revealingSections.entries()].map(([key, s]) => ({
         key,
         phase: s.phase,
-        hasOriginalMesh: !!s.originalMeshRef,
+        renderMeshCount: s.renderMeshRefs.length,
         wireframeInScene: s.wireframeGroup.parent !== null
       }))
     }

package/src/three/modules/starfield.ts

@@ -139,10 +139,18 @@ export class StarfieldModule implements RendererModuleController {
 
     const material = new StarfieldMaterial()
     material.blending = THREE.AdditiveBlending
-    material.depthTest = false
+    // depthTest=true so opaque blocks in front correctly occlude stars (was false, which
+    // made them additively visible THROUGH every opaque mesh — most visible against the
+    // new shader-cube path which renders in the opaque queue). depthWrite=false keeps
+    // stars from clobbering the depth buffer for any transparent meshes drawn after
+    // them in the same pass (clouds, foliage cutouts, particles…).
+    material.depthTest = true
+    material.depthWrite = false
     material.transparent = true
 
     this.points = new THREE.Points(geometry, material)
+    // renderOrder=-1 keeps stars at the FRONT of the transparent queue, so any
+    // transparent foreground (leaves, glass, water) still composites on top of them.
     this.points.renderOrder = -1
     this.worldRenderer.scene.add(this.points)
   }

package/src/three/sectionRaycastAabb.ts

@@ -0,0 +1,167 @@
+//@ts-nocheck
+import { SHADER_CUBES_WORDS_PER_FACE } from '../wasm-mesher/bridge/shaderCubeBridge'
+import { WORD0 } from './shaders/cubeBlockShader'
+
+export type ShaderSectionRaycastBox = {
+  minX: number
+  minY: number
+  minZ: number
+  maxX: number
+  maxY: number
+  maxZ: number
+  cx: number
+  cy: number
+  cz: number
+}
+
+/**
+ * Tight world-space AABB covering occupied shader-cube blocks in a section.
+ * `sectionCenter*` is geometryData.sx/sy/sz (section base + 8).
+ */
+export function computeShaderSectionRaycastAabb (
+  words: Uint32Array,
+  faceCount: number,
+  sectionCenterX: number,
+  sectionCenterY: number,
+  sectionCenterZ: number,
+): ShaderSectionRaycastBox | undefined {
+  if (faceCount <= 0) return undefined
+
+  const baseX = sectionCenterX - 8
+  const baseY = sectionCenterY - 8
+  const baseZ = sectionCenterZ - 8
+  const stride = SHADER_CUBES_WORDS_PER_FACE
+
+  let minLx = 16
+  let minLy = 16
+  let minLz = 16
+  let maxLx = -1
+  let maxLy = -1
+  let maxLz = -1
+
+  for (let i = 0; i < faceCount; i++) {
+    const w0 = words[i * stride]!
+    const lx = w0 & ((1 << WORD0.LX_BITS) - 1)
+    const ly = (w0 >> WORD0.LY_SHIFT) & ((1 << WORD0.LY_BITS) - 1)
+    const lz = (w0 >> WORD0.LZ_SHIFT) & ((1 << WORD0.LZ_BITS) - 1)
+    if (lx < minLx) minLx = lx
+    if (ly < minLy) minLy = ly
+    if (lz < minLz) minLz = lz
+    if (lx > maxLx) maxLx = lx
+    if (ly > maxLy) maxLy = ly
+    if (lz > maxLz) maxLz = lz
+  }
+
+  if (maxLx < 0) return undefined
+
+  const minX = baseX + minLx
+  const minY = baseY + minLy
+  const minZ = baseZ + minLz
+  const maxX = baseX + maxLx + 1
+  const maxY = baseY + maxLy + 1
+  const maxZ = baseZ + maxLz + 1
+
+  return {
+    minX,
+    minY,
+    minZ,
+    maxX,
+    maxY,
+    maxZ,
+    cx: (minX + maxX) * 0.5,
+    cy: (minY + maxY) * 0.5,
+    cz: (minZ + maxZ) * 0.5,
+  }
+}
+
+function isPointInsideAabb (
+  ox: number,
+  oy: number,
+  oz: number,
+  minX: number,
+  minY: number,
+  minZ: number,
+  maxX: number,
+  maxY: number,
+  maxZ: number,
+): boolean {
+  return ox >= minX && ox <= maxX && oy >= minY && oy <= maxY && oz >= minZ && oz <= maxZ
+}
+
+/** Ray–AABB entry distance, or undefined. Ignores hits when origin is inside the box. */
+export function raycastAabb (
+  ox: number,
+  oy: number,
+  oz: number,
+  dx: number,
+  dy: number,
+  dz: number,
+  minX: number,
+  minY: number,
+  minZ: number,
+  maxX: number,
+  maxY: number,
+  maxZ: number,
+  maxDist: number,
+): number | undefined {
+  if (isPointInsideAabb(ox, oy, oz, minX, minY, minZ, maxX, maxY, maxZ)) {
+    return undefined
+  }
+
+  let tmin = 0
+  let tmax = maxDist
+
+  if (Math.abs(dx) < 1e-8) {
+    if (ox < minX || ox > maxX) return undefined
+  } else {
+    const inv = 1 / dx
+    let t1 = (minX - ox) * inv
+    let t2 = (maxX - ox) * inv
+    if (t1 > t2) { const tmp = t1; t1 = t2; t2 = tmp }
+    tmin = Math.max(tmin, t1)
+    tmax = Math.min(tmax, t2)
+    if (tmin > tmax) return undefined
+  }
+
+  if (Math.abs(dy) < 1e-8) {
+    if (oy < minY || oy > maxY) return undefined
+  } else {
+    const inv = 1 / dy
+    let t1 = (minY - oy) * inv
+    let t2 = (maxY - oy) * inv
+    if (t1 > t2) { const tmp = t1; t1 = t2; t2 = tmp }
+    tmin = Math.max(tmin, t1)
+    tmax = Math.min(tmax, t2)
+    if (tmin > tmax) return undefined
+  }
+
+  if (Math.abs(dz) < 1e-8) {
+    if (oz < minZ || oz > maxZ) return undefined
+  } else {
+    const inv = 1 / dz
+    let t1 = (minZ - oz) * inv
+    let t2 = (maxZ - oz) * inv
+    if (t1 > t2) { const tmp = t1; t1 = t2; t2 = tmp }
+    tmin = Math.max(tmin, t1)
+    tmax = Math.min(tmax, t2)
+    if (tmin > tmax) return undefined
+  }
+
+  return tmin <= tmax && tmin >= 0 ? tmin : undefined
+}
+
+/** 16³ section box centered at (cx, cy, cz) — tests / legacy helper. */
+export function raycastSectionAabb (
+  ox: number,
+  oy: number,
+  oz: number,
+  dx: number,
+  dy: number,
+  dz: number,
+  cx: number,
+  cy: number,
+  cz: number,
+  maxDist: number,
+): number | undefined {
+  return raycastAabb(ox, oy, oz, dx, dy, dz, cx - 8, cy - 8, cz - 8, cx + 8, cy + 8, cz + 8, maxDist)
+}

package/src/three/shaderCubeMesh.ts

@@ -0,0 +1,93 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { VERTICES_PER_FACE } from './shaders/cubeBlockShader'
+import { SHADER_CUBES_WORDS_PER_FACE } from '../wasm-mesher/bridge/shaderCubeBridge'
+
+export type ShaderCubeInstanceData = {
+  words: Uint32Array
+  count: number
+}
+
+/**
+ * Build InstancedBufferGeometry for full-cube shader faces.
+ * One instance = one visible face; vertex shader uses gl_VertexID (6 verts/face).
+ */
+export function buildShaderCubeGeometry(
+  words: Uint32Array,
+  faceCount: number,
+): THREE.InstancedBufferGeometry {
+  const geometry = new THREE.InstancedBufferGeometry()
+
+  const positions = new Float32Array(VERTICES_PER_FACE * 3)
+  geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3))
+
+  const w0 = new Uint32Array(faceCount)
+  const w1 = new Uint32Array(faceCount)
+  const w2 = new Uint32Array(faceCount)
+  const w3 = new Uint32Array(faceCount)
+  const stride = SHADER_CUBES_WORDS_PER_FACE
+  for (let i = 0; i < faceCount; i++) {
+    w0[i] = words[i * stride]!
+    w1[i] = words[i * stride + 1]!
+    w2[i] = words[i * stride + 2]!
+    w3[i] = words[i * stride + 3]!
+  }
+
+  geometry.setAttribute('a_w0', new THREE.InstancedBufferAttribute(w0, 1))
+  geometry.setAttribute('a_w1', new THREE.InstancedBufferAttribute(w1, 1))
+  geometry.setAttribute('a_w2', new THREE.InstancedBufferAttribute(w2, 1))
+  geometry.setAttribute('a_w3', new THREE.InstancedBufferAttribute(w3, 1))
+
+  geometry.instanceCount = faceCount
+  geometry.boundingBox = new THREE.Box3(
+    new THREE.Vector3(-8, -8, -8),
+    new THREE.Vector3(8, 8, 8),
+  )
+  geometry.boundingSphere = new THREE.Sphere(
+    new THREE.Vector3(0, 0, 0),
+    Math.sqrt(3 * 8 ** 2),
+  )
+
+  return geometry
+}
+
+const _raycastBox = new THREE.Box3()
+const _raycastPoint = new THREE.Vector3()
+
+/**
+ * CPU raycast uses section AABB (geometry.boundingBox), not GPU-generated faces.
+ * Enough for third-person camera collision; block pick uses mineflayer, not mesh raycast.
+ */
+export function attachShaderCubeRaycast(
+  mesh: THREE.Mesh<THREE.BufferGeometry, THREE.Material>,
+): void {
+  mesh.raycast = (raycaster, intersects) => {
+    const { geometry } = mesh
+    if (!geometry.boundingBox) return
+    _raycastBox.copy(geometry.boundingBox).applyMatrix4(mesh.matrixWorld)
+    if (!raycaster.ray.intersectBox(_raycastBox, _raycastPoint)) return
+    const distance = raycaster.ray.origin.distanceTo(_raycastPoint)
+    intersects.push({
+      distance,
+      point: _raycastPoint.clone(),
+      object: mesh,
+    })
+  }
+}
+
+export function createShaderCubeMesh(
+  data: ShaderCubeInstanceData,
+  material: THREE.ShaderMaterial,
+): THREE.Mesh<THREE.InstancedBufferGeometry, THREE.ShaderMaterial> {
+  const geometry = buildShaderCubeGeometry(data.words, data.count)
+  const mesh = new THREE.Mesh(geometry, material)
+  mesh.name = 'shaderMesh'
+  mesh.matrixAutoUpdate = false
+  mesh.frustumCulled = false
+  attachShaderCubeRaycast(mesh)
+  return mesh
+}
+
+export function disposeShaderCubeMesh(mesh: THREE.Mesh): void {
+  mesh.geometry.dispose()
+}