minecraft-renderer 0.1.108 → 0.1.109

package/package.json

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

package/src/three/cloudCover.ts

@@ -0,0 +1,22 @@
+//@ts-nocheck
+import type { CloudCover } from './cloudGeometry'
+
+/** Texels at least this opaque count as cloud. */
+const ALPHA_THRESHOLD = 128
+
+/** Decodes vanilla clouds.png into a per-cell mask (works on the main thread and in workers). */
+export async function loadCloudCover(url: string): Promise<CloudCover> {
+  const blob = await (await fetch(url)).blob()
+  const bitmap = await createImageBitmap(blob, { premultiplyAlpha: 'none' })
+  try {
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height)
+    const ctx = canvas.getContext('2d')!
+    ctx.drawImage(bitmap, 0, 0)
+    const { data } = ctx.getImageData(0, 0, bitmap.width, bitmap.height)
+    const filled = new Uint8Array(bitmap.width * bitmap.height)
+    for (let i = 0; i < filled.length; i++) filled[i] = data[i * 4 + 3] >= ALPHA_THRESHOLD ? 1 : 0
+    return { width: bitmap.width, height: bitmap.height, filled }
+  } finally {
+    bitmap.close()
+  }
+}

package/src/three/cloudGeometry.ts

@@ -0,0 +1,71 @@
+//@ts-nocheck
+/** Which cells of vanilla clouds.png hold cloud (the texture wraps in both directions). */
+export interface CloudCover {
+  width: number
+  height: number
+  /** Row-major, 1 where the cell has a cloud. */
+  filled: Uint8Array
+}
+
+export interface CloudGeometryData {
+  positions: Float32Array
+  /** Per-vertex face brightness. */
+  shades: Float32Array
+  indices: Uint32Array
+}
+
+/** Vanilla: each clouds.png texel is a 12×12 block cell and the slab is 4 blocks thick. */
+export const CLOUD_CELL_SIZE = 12
+export const CLOUD_THICKNESS = 4
+
+// Vanilla fancy-cloud face shading.
+const SHADE_TOP = 1
+const SHADE_BOTTOM = 0.7
+const SHADE_NORTH_SOUTH = 0.8
+const SHADE_EAST_WEST = 0.9
+
+const mod = (n: number, m: number) => ((n % m) + m) % m
+
+/**
+ * Builds the slab geometry for the (2 * radius + 1)² cells around pattern cell (centerX, centerZ).
+ * Positions are relative to that cell's min corner, y spans 0..CLOUD_THICKNESS. Side faces are only
+ * emitted next to empty cells, so the interior of a cloud bank has no hidden geometry.
+ * Every quad is wound counter-clockwise seen from outside.
+ */
+export function buildCloudGeometry(cover: CloudCover, centerX: number, centerZ: number, radius: number): CloudGeometryData {
+  const positions: number[] = []
+  const shades: number[] = []
+  const indices: number[] = []
+
+  const isFilled = (cellX: number, cellZ: number) => cover.filled[mod(cellZ, cover.height) * cover.width + mod(cellX, cover.width)] === 1
+
+  const quad = (shade: number, a: number[], b: number[], c: number[], d: number[]) => {
+    const first = positions.length / 3
+    positions.push(...a, ...b, ...c, ...d)
+    shades.push(shade, shade, shade, shade)
+    indices.push(first, first + 1, first + 2, first, first + 2, first + 3)
+  }
+
+  const h = CLOUD_THICKNESS
+  for (let i = -radius; i <= radius; i++) {
+    for (let j = -radius; j <= radius; j++) {
+      const cellX = centerX + i
+      const cellZ = centerZ + j
+      if (!isFilled(cellX, cellZ)) continue
+
+      const x0 = i * CLOUD_CELL_SIZE
+      const x1 = x0 + CLOUD_CELL_SIZE
+      const z0 = j * CLOUD_CELL_SIZE
+      const z1 = z0 + CLOUD_CELL_SIZE
+
+      quad(SHADE_TOP, [x0, h, z0], [x0, h, z1], [x1, h, z1], [x1, h, z0])
+      quad(SHADE_BOTTOM, [x0, 0, z0], [x1, 0, z0], [x1, 0, z1], [x0, 0, z1])
+      if (!isFilled(cellX + 1, cellZ)) quad(SHADE_EAST_WEST, [x1, 0, z0], [x1, h, z0], [x1, h, z1], [x1, 0, z1])
+      if (!isFilled(cellX - 1, cellZ)) quad(SHADE_EAST_WEST, [x0, 0, z1], [x0, h, z1], [x0, h, z0], [x0, 0, z0])
+      if (!isFilled(cellX, cellZ + 1)) quad(SHADE_NORTH_SOUTH, [x1, 0, z1], [x1, h, z1], [x0, h, z1], [x0, 0, z1])
+      if (!isFilled(cellX, cellZ - 1)) quad(SHADE_NORTH_SOUTH, [x0, 0, z0], [x0, h, z0], [x1, h, z0], [x1, 0, z0])
+    }
+  }
+
+  return { positions: new Float32Array(positions), shades: new Float32Array(shades), indices: new Uint32Array(indices) }
+}

package/src/three/modules/clouds.ts

@@ -4,30 +4,28 @@ import cloudsPng from 'mc-assets/dist/other-textures/latest/environment/clouds.p
 import type { WorldRendererThree } from '../worldRendererThree'
 import type { RendererModuleController, RendererModuleManifest } from '../rendererModuleSystem'
 import { vanillaCelestialAngle, vanillaDayBrightness } from '../../lib/skyLight'
+import { loadCloudCover } from '../cloudCover'
+import { buildCloudGeometry, CLOUD_CELL_SIZE, type CloudCover } from '../cloudGeometry'
 
-// Vanilla: clouds.png is 256×256, each texel a 12×12 block cell, slab 4 blocks thick.
-const CELL_SIZE = 12
-const TEXTURE_CELLS = 256
-const PATTERN_PERIOD = CELL_SIZE * TEXTURE_CELLS
-const THICKNESS = 4
 /** Vanilla drifts the pattern 0.03 blocks per tick (20 TPS) toward -X. */
 const DRIFT_BLOCKS_PER_SECOND = 0.03 * 20
 /** Vanilla offsets the slab bottom by +0.33 from the dimension's cloud height. */
 const HEIGHT_BIAS = 0.33
 const MIN_RADIUS = 256
-const MAX_RADIUS = 768
+const MAX_RADIUS = 576
 const OPACITY = 0.8
-/** Vanilla shades the underside darker than the top. */
-const BOTTOM_SHADE = 0.7
 
 const threeVersion = parseInt(THREE.REVISION.replaceAll(/\D+/g, ''), 10)
 
 const vertexShader = /* glsl */ `
   #include <common>
   #include <logdepthbuf_pars_vertex>
+  attribute float shade;
   varying vec2 vLocal;
+  varying float vShade;
   void main() {
     vLocal = (modelMatrix * vec4(position, 1.0)).xz;
+    vShade = shade;
     gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
     #include <logdepthbuf_vertex>
   }
@@ -36,32 +34,39 @@ const vertexShader = /* glsl */ `
 const fragmentShader = /* glsl */ `
   #include <common>
   #include <logdepthbuf_pars_fragment>
-  uniform sampler2D map;
-  uniform vec2 patternOffset;
   uniform vec3 color;
   uniform float opacity;
   uniform float fadeStart;
   uniform float fadeEnd;
   varying vec2 vLocal;
+  varying float vShade;
   void main() {
     #include <logdepthbuf_fragment>
-    float cover = texture2D(map, (vLocal + patternOffset) / ${PATTERN_PERIOD.toFixed(1)}).a;
-    if (cover < 0.5) discard;
     float alpha = opacity * (1.0 - smoothstep(fadeStart, fadeEnd, length(vLocal)));
     if (alpha <= 0.0) discard;
-    gl_FragColor = vec4(color, alpha);
+    gl_FragColor = vec4(color * vShade, alpha);
     #include <tonemapping_fragment>
     #include <${threeVersion >= 154 ? 'colorspace_fragment' : 'encodings_fragment'}>
   }
 `
 
 /**
- * Flat "fast graphics" clouds: one camera-following quad, the cloud mask is sampled from
- * vanilla clouds.png in the fragment shader, so there is no per-cell geometry to rebuild
- * as the player moves or the pattern drifts.
+ * Vanilla "fancy" clouds: a 4-block-thick slab of 12×12 cells taken from clouds.png, with real top,
+ * bottom and side faces. The cells around the camera are rebuilt only when the camera or the drifting
+ * pattern crosses a cell boundary; everything finer than that is a mesh position offset.
+ * A colour-less depth pre-pass over the same geometry keeps overlapping faces from blending twice.
  */
 export class CloudsModule implements RendererModuleController {
-  private mesh?: THREE.Mesh<THREE.PlaneGeometry, THREE.ShaderMaterial>
+  private readonly group = new THREE.Group()
+  private readonly uniforms = {
+    color: { value: new THREE.Color(1, 1, 1) },
+    opacity: { value: OPACITY },
+    fadeStart: { value: MIN_RADIUS * 0.55 },
+    fadeEnd: { value: MIN_RADIUS }
+  }
+  private meshes?: THREE.Mesh<THREE.BufferGeometry, THREE.ShaderMaterial>[]
+  private cover?: CloudCover
+  private builtKey = ''
   private enabled = false
   private drift = 0
   private timeOfDay: number
@@ -69,19 +74,20 @@ export class CloudsModule implements RendererModuleController {
 
   constructor(private readonly worldRenderer: WorldRendererThree) {
     this.timeOfDay = worldRenderer.timeOfTheDay
+    this.group.name = 'clouds'
   }
 
   enable(): void {
     if (this.enabled) return
     this.enabled = true
-    if (!this.mesh) this.create()
-    this.mesh!.visible = true
+    if (!this.meshes) this.create()
+    this.group.visible = true
   }
 
   disable(): void {
     if (!this.enabled) return
     this.enabled = false
-    if (this.mesh) this.mesh.visible = false
+    this.group.visible = false
   }
 
   autoEnableCheck(): boolean {
@@ -94,78 +100,96 @@ export class CloudsModule implements RendererModuleController {
   }
 
   render?: (deltaTime: number) => void = deltaTime => {
-    this.drift = (this.drift + deltaTime * DRIFT_BLOCKS_PER_SECOND) % PATTERN_PERIOD
+    // Not wrapped: cell indices wrap in the lookup, and wrapping here would force a rebuild.
+    this.drift += deltaTime * DRIFT_BLOCKS_PER_SECOND
   }
 
   dispose(): void {
-    if (!this.mesh) return
-    this.worldRenderer.scene.remove(this.mesh)
-    this.mesh.geometry.dispose()
-    this.mesh.material.uniforms.map.value?.dispose()
-    this.mesh.material.dispose()
-    this.mesh = undefined
+    if (!this.meshes) return
+    this.worldRenderer.scene.remove(this.group)
+    this.meshes[0].geometry.dispose()
+    for (const mesh of this.meshes) mesh.material.dispose()
+    this.meshes = undefined
+    this.cover = undefined
+    this.builtKey = ''
   }
 
   private create(): void {
-    const map = new THREE.TextureLoader().load(cloudsPng)
-    map.wrapS = THREE.RepeatWrapping
-    map.wrapT = THREE.RepeatWrapping
-    map.magFilter = THREE.NearestFilter
-    map.minFilter = THREE.NearestFilter
-    map.generateMipmaps = false
-    // Keep png row 0 at -Z like vanilla's texture-to-world mapping.
-    map.flipY = false
-
-    const material = new THREE.ShaderMaterial({
-      uniforms: {
-        map: { value: map },
-        patternOffset: { value: new THREE.Vector2() },
-        color: { value: new THREE.Color(1, 1, 1) },
-        opacity: { value: OPACITY },
-        fadeStart: { value: MIN_RADIUS * 0.55 },
-        fadeEnd: { value: MIN_RADIUS }
-      },
+    const shared = {
+      uniforms: this.uniforms,
       vertexShader,
       fragmentShader,
-      transparent: true,
-      depthWrite: false,
-      depthTest: true,
       side: THREE.DoubleSide,
+      transparent: true,
       forceSinglePass: true
-    })
+    }
+    const main = new THREE.ShaderMaterial({ ...shared, depthWrite: false })
+    // Same program, so its depth matches the main pass exactly.
+    const depthOnly = new THREE.ShaderMaterial({ ...shared, depthWrite: true, colorWrite: false })
 
-    const geometry = new THREE.PlaneGeometry(2, 2)
-    geometry.rotateX(-Math.PI / 2)
+    const geometry = new THREE.BufferGeometry()
+    geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array(0), 3))
 
-    const mesh = new THREE.Mesh(geometry, material)
-    mesh.name = 'clouds'
-    mesh.frustumCulled = false
     // After sun/moon (-2) and stars (-1), before other transparents so water/glass composite on top.
-    mesh.renderOrder = -0.5
-    mesh.onBeforeRender = () => this.syncToCamera(mesh)
-    this.mesh = mesh
-    this.worldRenderer.scene.add(mesh)
+    const passes: [THREE.ShaderMaterial, number][] = [
+      [depthOnly, -0.6],
+      [main, -0.5]
+    ]
+    this.meshes = passes.map(([material, renderOrder]) => {
+      const mesh = new THREE.Mesh(geometry, material)
+      mesh.frustumCulled = false
+      mesh.renderOrder = renderOrder
+      this.group.add(mesh)
+      return mesh
+    })
+    // The depth pre-pass is drawn first, so syncing there positions both passes.
+    this.meshes[0].onBeforeRender = () => this.syncToCamera()
+    this.worldRenderer.scene.add(this.group)
+
+    loadCloudCover(cloudsPng).then(
+      cover => {
+        this.cover = cover
+      },
+      error => console.warn('Failed to load clouds.png, clouds will not render', error)
+    )
+  }
+
+  private rebuild(centerX: number, centerZ: number, radiusCells: number): void {
+    const data = buildCloudGeometry(this.cover!, centerX, centerZ, radiusCells)
+    const geometry = new THREE.BufferGeometry()
+    geometry.setAttribute('position', new THREE.BufferAttribute(data.positions, 3))
+    geometry.setAttribute('shade', new THREE.BufferAttribute(data.shades, 1))
+    geometry.setIndex(new THREE.BufferAttribute(data.indices, 1))
+
+    const meshes = this.meshes!
+    const old = meshes[0].geometry
+    for (const mesh of meshes) mesh.geometry = geometry
+    old.dispose()
   }
 
-  private syncToCamera(mesh: THREE.Mesh<THREE.PlaneGeometry, THREE.ShaderMaterial>): void {
+  private syncToCamera(): void {
     const { sceneOrigin, viewDistance, worldRendererConfig } = this.worldRenderer
-    const { uniforms } = mesh.material
 
     const radius = THREE.MathUtils.clamp(viewDistance * 16 * 2, MIN_RADIUS, MAX_RADIUS)
-    uniforms.fadeStart.value = radius * 0.55
-    uniforms.fadeEnd.value = radius
+    this.uniforms.fadeStart.value = radius * 0.55
+    this.uniforms.fadeEnd.value = radius
+
+    // Pattern space is world space shifted by the drift, so world x = pattern x - drift.
+    const centerX = Math.floor((sceneOrigin.x + this.drift) / CLOUD_CELL_SIZE)
+    const centerZ = Math.floor(sceneOrigin.z / CLOUD_CELL_SIZE)
+    if (this.cover) {
+      const radiusCells = Math.ceil(radius / CLOUD_CELL_SIZE)
+      const key = `${centerX},${centerZ},${radiusCells}`
+      if (key !== this.builtKey) {
+        this.builtKey = key
+        this.rebuild(centerX, centerZ, radiusCells)
+      }
+    }
 
-    // Show the slab bottom from below and its top from above, like a 4-block-thick cloud.
+    // Compute in doubles so the GPU only ever sees camera-relative offsets.
     const bottom = worldRendererConfig.cloudHeight + HEIGHT_BIAS
-    const fromBelow = sceneOrigin.y < bottom + THICKNESS / 2
-    const planeY = fromBelow ? bottom : bottom + THICKNESS
-    mesh.position.set(0, planeY - sceneOrigin.y, 0)
-    mesh.scale.set(radius, 1, radius)
-    mesh.updateMatrixWorld()
-
-    // Wrap on the CPU in doubles so the shader never sees large world coordinates.
-    const wrap = (v: number) => ((v % PATTERN_PERIOD) + PATTERN_PERIOD) % PATTERN_PERIOD
-    uniforms.patternOffset.value.set(wrap(sceneOrigin.x + this.drift), wrap(sceneOrigin.z))
+    this.group.position.set(centerX * CLOUD_CELL_SIZE - this.drift - sceneOrigin.x, bottom - sceneOrigin.y, centerZ * CLOUD_CELL_SIZE - sceneOrigin.z)
+    this.group.updateMatrixWorld(true)
 
     const day = vanillaDayBrightness(vanillaCelestialAngle(this.timeOfDay))
     let r = day * 0.9 + 0.1
@@ -178,9 +202,8 @@ export class CloudsModule implements RendererModuleController {
       g = g * 0.05 + grey * 0.95
       b = b * 0.05 + grey * 0.95
     }
-    const shade = fromBelow ? BOTTOM_SHADE : 1
-    this.linearColor.setRGB(r * shade, g * shade, b * shade, THREE.SRGBColorSpace)
-    uniforms.color.value.copy(this.linearColor)
+    this.linearColor.setRGB(r, g, b, THREE.SRGBColorSpace)
+    this.uniforms.color.value.copy(this.linearColor)
   }
 }
 

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)
+})