@woosh/meep-engine 2.138.16 → 2.138.18

package/src/engine/graphics/material/TerrainDepthMaterial.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Custom depth material attached to terrain tile meshes as
+ * `mesh.customDepthMaterial`. Used during the shadow-caster pass to inset
+ * the recorded depth into the terrain surface.
+ *
+ * In the vertex shader, each vertex is sunk along its negative geometric
+ * normal by `shadowBias` units (object space) before projection into the
+ * shadow camera. The resulting shadow map stores the terrain at depths
+ * slightly beyond the true surface, so when the terrain shader samples its
+ * own shadow at a crease the receiver depth is strictly less than the
+ * stored occluder depth and the surface does not self-shadow — sidestepping
+ * VSM over-darkening at depth discontinuities.
+ *
+ * Trade-off: other meshes that *receive* the terrain's cast shadow see the
+ * terrain silhouette shrunk inward by `shadowBias`. For terrain that mostly
+ * self-shadows (hills, cliffs, valleys) this is invisible. For objects
+ * resting on the surface, contact shadows from the terrain become very
+ * slightly smaller. This is the explicit trade-off this material exists
+ * to make.
+ *
+ * Bias is in OBJECT space. If the terrain mesh is scaled non-uniformly the
+ * caller is responsible for scaling the value accordingly.
+ *
+ * The bias is exposed on `material.userData.shadowBias` so callers can
+ * mutate it without reaching into uniforms directly:
+ *     material.userData.shadowBias.value = newBias;
+ *
+ * @param {number} [initialBias=0.1] starting shadowBias, object-space units.
+ *   Chosen as a conservative default that clears typical VSM crease artifacts
+ *   at common shadow-map resolutions while keeping caster-side shrinkage on
+ *   other receivers visually negligible.
+ * @returns {MeshDepthMaterial}
+ */
+export function makeTerrainDepthMaterial(initialBias?: number): MeshDepthMaterial;
+import { MeshDepthMaterial } from 'three';
+//# sourceMappingURL=TerrainDepthMaterial.d.ts.map

package/src/engine/graphics/material/TerrainDepthMaterial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TerrainDepthMaterial.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/material/TerrainDepthMaterial.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,uDANW,MAAM,GAIJ,iBAAiB,CA+B7B;kCAhE+D,OAAO"}

package/src/engine/graphics/material/TerrainDepthMaterial.js

@@ -0,0 +1,65 @@
+import { DoubleSide, MeshDepthMaterial, RGBADepthPacking } from 'three';
+
+/**
+ * Custom depth material attached to terrain tile meshes as
+ * `mesh.customDepthMaterial`. Used during the shadow-caster pass to inset
+ * the recorded depth into the terrain surface.
+ *
+ * In the vertex shader, each vertex is sunk along its negative geometric
+ * normal by `shadowBias` units (object space) before projection into the
+ * shadow camera. The resulting shadow map stores the terrain at depths
+ * slightly beyond the true surface, so when the terrain shader samples its
+ * own shadow at a crease the receiver depth is strictly less than the
+ * stored occluder depth and the surface does not self-shadow — sidestepping
+ * VSM over-darkening at depth discontinuities.
+ *
+ * Trade-off: other meshes that *receive* the terrain's cast shadow see the
+ * terrain silhouette shrunk inward by `shadowBias`. For terrain that mostly
+ * self-shadows (hills, cliffs, valleys) this is invisible. For objects
+ * resting on the surface, contact shadows from the terrain become very
+ * slightly smaller. This is the explicit trade-off this material exists
+ * to make.
+ *
+ * Bias is in OBJECT space. If the terrain mesh is scaled non-uniformly the
+ * caller is responsible for scaling the value accordingly.
+ *
+ * The bias is exposed on `material.userData.shadowBias` so callers can
+ * mutate it without reaching into uniforms directly:
+ *     material.userData.shadowBias.value = newBias;
+ *
+ * @param {number} [initialBias=0.1] starting shadowBias, object-space units.
+ *   Chosen as a conservative default that clears typical VSM crease artifacts
+ *   at common shadow-map resolutions while keeping caster-side shrinkage on
+ *   other receivers visually negligible.
+ * @returns {MeshDepthMaterial}
+ */
+export function makeTerrainDepthMaterial(initialBias = 0.1) {
+    const m = new MeshDepthMaterial({
+        depthPacking: RGBADepthPacking,
+        side: DoubleSide
+    });
+
+    // single uniform reference shared between shader and userData so external
+    // writes via userData.shadowBias.value reach the shader without rebinding
+    const shadowBias = { value: initialBias };
+
+    m.userData.shadowBias = shadowBias;
+
+    m.onBeforeCompile = (shader) => {
+        shader.uniforms.shadowBias = shadowBias;
+
+        shader.vertexShader = shader.vertexShader
+            .replace(
+                '#include <common>',
+                `#include <common>
+uniform float shadowBias;`
+            )
+            .replace(
+                '#include <begin_vertex>',
+                `#include <begin_vertex>
+transformed -= normal * shadowBias;`
+            );
+    };
+
+    return m;
+}

package/src/engine/graphics/shaders/AmbientOcclusionShader.d.ts

@@ -1,27 +1,84 @@
 export default AmbientOcclusionShader;
-declare function AmbientOcclusionShader(): {
+/**
+ * Lightmap baker for heightfield terrain.
+ *
+ * Per output texel, traces `NUM_RAYS` cosine-weighted rays into the
+ * hemisphere around the surface normal and counts how many are occluded by
+ * the heightfield. The output channel is visibility ∈ [0, 1]:
+ *   1 = fully lit (no occlusion)
+ *   0 = fully occluded
+ *
+ * Architecture
+ * ------------
+ *
+ *   1. Pre-pass (orchestrator side): a max-reduction mipmap pyramid is built
+ *      from the heightmap — see `build_max_height_pyramid`. Each mip stores
+ *      per-cell upper bounds on height. The whole pyramid is one DataTexture
+ *      with `tex.mipmaps[]`, sampled by `textureLod`.
+ *
+ *   2. Sampling: directions are drawn from a cosine-weighted hemisphere using
+ *      Shirley's concentric disk mapping. Cosine-weighting matches the
+ *      Lambertian diffuse assumption — each sample's contribution to the AO
+ *      integral has unit weight, and the estimator collapses to a simple
+ *      hits/total ratio.
+ *
+ *   3. Random seeding: a PCG hash (pcg3d on the fragment coordinate) seeds an
+ *      independent stream per output texel. Subsequent rays draw from `pcg`
+ *      on the running state. White noise — no Halton/blue-noise sequences —
+ *      keeps the implementation simple and the noise spectrum unbiased; a
+ *      bilateral denoise pass downstream cleans up the speckle.
+ *
+ *   4. Tracing: Hi-Z traversal in world space. The ray's XZ projection walks
+ *      texture-space cells; per cell, the max-height at the current mip is
+ *      compared against the ray's min height across the cell. Above max:
+ *      advance to the next cell and try to coarsen the mip. Below max:
+ *      refine the mip; at mip 0, record a hit. Bounded by MAX_HIZ_ITER per
+ *      ray as a safety net for pathological convergence.
+ *
+ * World space
+ * -----------
+ *
+ *   Convention: X and Z are horizontal (UV-aligned), Y is up. The heightmap's
+ *   UV maps linearly to world (x, z) ∈ [0, worldSize.x] × [0, worldSize.y],
+ *   and the heightmap value at any UV is the world Y coordinate of the
+ *   surface. Surface normals are recomputed in-shader by central differences
+ *   on the heightmap, removing any dependency on an external normal map.
+ *
+ * Inputs (uniforms — plumbing, not user-facing)
+ * ---------------------------------------------
+ *
+ *   heightMap     R32F texture with a max-reduction mipmap chain
+ *   worldSize     XZ extent of the terrain in world units
+ *   heightMapSize Resolution of heightMap mip 0 in texels
+ *   maxMipLevel   Index of the coarsest mip in heightMap
+ *
+ * The single user-facing parameter is `NUM_RAYS`, configured by the factory
+ * argument.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.numRays=64] number of rays per output texel
+ */
+declare function AmbientOcclusionShader({ numRays }?: {
+    numRays?: number;
+}): {
     uniforms: {
-        normalMap: {
-            type: string;
-            value: any;
-        };
         heightMap: {
-            type: string;
             value: any;
         };
-        world_size: {
-            type: string;
+        worldSize: {
+            value: Vector2;
+        };
+        heightMapSize: {
             value: Vector2;
         };
-        rayLength: {
-            type: string;
+        maxMipLevel: {
             value: number;
         };
     };
     defines: {
-        NUM_SAMPLES: number;
-        NUM_RINGS: number;
+        NUM_RAYS: number;
     };
+    glslVersion: import("three").GLSLVersion;
     vertexShader: string;
     fragmentShader: string;
 };

package/src/engine/graphics/shaders/AmbientOcclusionShader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AmbientOcclusionShader.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/shaders/AmbientOcclusionShader.js"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;EA4HC;wBA9HuB,OAAO"}
+{"version":3,"file":"AmbientOcclusionShader.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/shaders/AmbientOcclusionShader.js"],"names":[],"mappings":";AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH;IAFyB,OAAO,GAArB,MAAM;;;;;;;;;;;;;;;;;;;;;;EA4ThB;wBA/X8B,OAAO"}