@woosh/meep-engine 2.169.1 → 2.169.2

package/src/engine/graphics/shaders/chunks/glsl_octahedral_impostor.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared GLSL source fragments for the octahedral-impostor family.
+ *
+ * WHY THIS EXISTS
+ *
+ * The octahedral atlas mapping is a single invariant shared by the bake side
+ * (`impostors/octahedral/grid/OctahedralUvEncoder.js`) and every sampling
+ * shader. Before this module the whole ~90-line library was transcribed nine
+ * times — once per stage of `ImpostorShaderV0`, `...DepthV0`, `...NormalsV0`,
+ * `...ViewportDepthV0`, `...WireframeV0`, `...PerPixelV0` (vertex AND fragment)
+ * and `...LitV0` (vertex AND fragment). Nine transcriptions of one invariant is
+ * nine chances for the sample side to stop agreeing with the bake side, and the
+ * failure mode (subtly wrong atlas frame) is invisible in code review.
+ *
+ * These are plain named string exports rather than a keyed chunk registry: a
+ * shader interpolates exactly the fragments it needs, by name, and an unused
+ * import is a static error rather than a silent miss.
+ *
+ * HOST REQUIREMENTS
+ *
+ * `GLSL_OCTAHEDRAL_GRID` reads `uniform bool uIsFullSphere;` and
+ * `GLSL_IMPOSTOR_BLEND_4_FRAMES` reads `uniform float uFrames;` — the including
+ * shader must declare both. GLSL requires declaration-before-use, so each
+ * fragment must be interpolated above the function that calls it.
+ *
+ * KNOWN DIVERGENCE FROM THE CPU REFERENCE — DO NOT "FIX" IN PASSING
+ *
+ * `VecToSphereOct` below uses the GLSL builtin `sign()`, while the CPU
+ * reference `core/geom/3d/octahedra/octahedral_direction_to_uv.js:24` uses
+ * `sign_not_zero()`. `sign(0.0)` is `0.0` in GLSL, so for a direction with an
+ * exactly-zero component the two disagree: the GPU path shrinks the L1 norm
+ * (`sum`) and folds an axis-aligned direction differently. This module
+ * preserves the GPU behaviour verbatim — reconciling the two conventions
+ * changes rendered output for axis-aligned view directions and must be done as
+ * a deliberate, separately-verified change, not as a side effect of
+ * deduplication.
+ */
+/**
+ * Direction <-> octahedral grid coordinate, both sphere and hemisphere folds.
+ *
+ * `VectorToGrid` returns the grid coordinate in the range -1..+1; callers remap
+ * with `* 0.5 + 0.5`. `GridToVector` is its inverse over the 0..1 range, and
+ * `FrameToRay` turns an integer atlas frame index into the bake-camera
+ * direction that captured it.
+ *
+ * Requires: `uniform bool uIsFullSphere;`
+ *
+ * @type {string}
+ */
+export const GLSL_OCTAHEDRAL_GRID: string;
+/**
+ * Bilinear weights over the four corners of the current atlas cell.
+ *
+ * The impostor family blends a full 2x2 cell rather than interpolating over
+ * three corners: triangle interpolation has a C1-discontinuous "diagonal
+ * switch" whose weight derivative jumps inside the cell, which reads as a snap.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_BILINEAR_WEIGHTS: string;
+/**
+ * Card-UV -> single-frame texture-UV rotation matrix.
+ *
+ * Each atlas frame was baked with its own camera right/up (three.js
+ * `Camera.lookAt` with up=(0,1,0)); near the octahedral pole those right-axes
+ * swing by 90 degrees or more between adjacent frames, so the four blended
+ * corners have to be rotated into a common orientation first.
+ *
+ * The `abs(D_frame.y) > 0.99999` nudge mirrors three.js's own polar
+ * degeneracy handling so the shader basis matches what the baker used.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_COMPUTE_FRAME_XFORM: string;
+/**
+ * Fragment-side application of a `ComputeFrameXform` matrix to a card UV.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_APPLY_FRAME_XFORM: string;
+/**
+ * Sample one card UV from the four cell-corner atlas frames and blend.
+ *
+ * Requires `apply_frame_xform` (see {@link GLSL_IMPOSTOR_APPLY_FRAME_XFORM})
+ * and `uniform float uFrames;`.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_BLEND_4_FRAMES: string;
+/**
+ * Decode an atlas normal (stored in bake-camera view space) back to object
+ * space, given the frame's own bake direction.
+ *
+ * The bake basis reconstruction here MUST match
+ * {@link GLSL_IMPOSTOR_COMPUTE_FRAME_XFORM} and `BakeShaderStandard`'s encode
+ * side, including the polar nudge threshold — a normal decoded in the wrong
+ * basis tilts lighting rather than producing an obvious artefact.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_DECODE_NORMAL_OS: string;
+//# sourceMappingURL=glsl_octahedral_impostor.d.ts.map

package/src/engine/graphics/shaders/chunks/glsl_octahedral_impostor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glsl_octahedral_impostor.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/shaders/chunks/glsl_octahedral_impostor.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;GAWG;AACH,mCAFU,MAAM,CAmFd;AAEF;;;;;;;;GAQG;AACH,6CAFU,MAAM,CAed;AAEF;;;;;;;;;;;;GAYG;AACH,gDAFU,MAAM,CA0Bd;AAEF;;;;GAIG;AACH,8CAFU,MAAM,CAcd;AAEF;;;;;;;GAOG;AACH,2CAFU,MAAM,CA4Bd;AAEF;;;;;;;;;;GAUG;AACH,6CAFU,MAAM,CAgBd"}

package/src/engine/graphics/shaders/chunks/glsl_octahedral_impostor.js

@@ -0,0 +1,277 @@
+/**
+ * Shared GLSL source fragments for the octahedral-impostor family.
+ *
+ * WHY THIS EXISTS
+ *
+ * The octahedral atlas mapping is a single invariant shared by the bake side
+ * (`impostors/octahedral/grid/OctahedralUvEncoder.js`) and every sampling
+ * shader. Before this module the whole ~90-line library was transcribed nine
+ * times — once per stage of `ImpostorShaderV0`, `...DepthV0`, `...NormalsV0`,
+ * `...ViewportDepthV0`, `...WireframeV0`, `...PerPixelV0` (vertex AND fragment)
+ * and `...LitV0` (vertex AND fragment). Nine transcriptions of one invariant is
+ * nine chances for the sample side to stop agreeing with the bake side, and the
+ * failure mode (subtly wrong atlas frame) is invisible in code review.
+ *
+ * These are plain named string exports rather than a keyed chunk registry: a
+ * shader interpolates exactly the fragments it needs, by name, and an unused
+ * import is a static error rather than a silent miss.
+ *
+ * HOST REQUIREMENTS
+ *
+ * `GLSL_OCTAHEDRAL_GRID` reads `uniform bool uIsFullSphere;` and
+ * `GLSL_IMPOSTOR_BLEND_4_FRAMES` reads `uniform float uFrames;` — the including
+ * shader must declare both. GLSL requires declaration-before-use, so each
+ * fragment must be interpolated above the function that calls it.
+ *
+ * KNOWN DIVERGENCE FROM THE CPU REFERENCE — DO NOT "FIX" IN PASSING
+ *
+ * `VecToSphereOct` below uses the GLSL builtin `sign()`, while the CPU
+ * reference `core/geom/3d/octahedra/octahedral_direction_to_uv.js:24` uses
+ * `sign_not_zero()`. `sign(0.0)` is `0.0` in GLSL, so for a direction with an
+ * exactly-zero component the two disagree: the GPU path shrinks the L1 norm
+ * (`sum`) and folds an axis-aligned direction differently. This module
+ * preserves the GPU behaviour verbatim — reconciling the two conventions
+ * changes rendered output for axis-aligned view directions and must be done as
+ * a deliberate, separately-verified change, not as a side effect of
+ * deduplication.
+ */
+
+/**
+ * Direction <-> octahedral grid coordinate, both sphere and hemisphere folds.
+ *
+ * `VectorToGrid` returns the grid coordinate in the range -1..+1; callers remap
+ * with `* 0.5 + 0.5`. `GridToVector` is its inverse over the 0..1 range, and
+ * `FrameToRay` turns an integer atlas frame index into the bake-camera
+ * direction that captured it.
+ *
+ * Requires: `uniform bool uIsFullSphere;`
+ *
+ * @type {string}
+ */
+export const GLSL_OCTAHEDRAL_GRID = `
+    // ----- direction -> octahedral grid coord (range -1..+1) -----
+
+    vec2 VecToSphereOct(vec3 pivotToCamera)
+    {
+        vec3 octant = sign(pivotToCamera);
+        float sum = dot(pivotToCamera, octant);
+        vec3 octahedron = pivotToCamera / sum;
+        if (octahedron.y < 0.0) {
+            vec3 absolute = abs(octahedron);
+            octahedron.xz = octant.xz * vec2(1.0 - absolute.z, 1.0 - absolute.x);
+        }
+        return octahedron.xz;
+    }
+
+    vec2 VecToHemiSphereOct(vec3 v)
+    {
+        v.y = max(v.y, 0.001);
+        v = normalize(v);
+        vec3 octant = sign(v);
+        float sum = dot(v, octant);
+        vec3 octahedron = v / sum;
+        return vec2(
+            octahedron.x + octahedron.z,
+            octahedron.z - octahedron.x
+        );
+    }
+
+    vec2 VectorToGrid(vec3 v)
+    {
+        if (uIsFullSphere) {
+            return VecToSphereOct(v);
+        } else {
+            return VecToHemiSphereOct(v);
+        }
+    }
+
+    // ----- octahedral grid coord (range 0..1) -> direction -----
+    //
+    // Inverse of VectorToGrid (after the 0.5/2.0 remap). Given the
+    // normalised position of a frame in the atlas, return the world-space
+    // direction the bake camera was sitting at when it captured that frame.
+
+    vec3 OctaSphereDec(vec2 coord)
+    {
+        coord = (coord - 0.5) * 2.0;
+        vec3 p = vec3(coord.x, 0.0, coord.y);
+        vec2 a = abs(p.xz);
+        p.y = 1.0 - a.x - a.y;
+        if (p.y < 0.0) {
+            p.xz = sign(p.xz) * vec2(1.0 - a.y, 1.0 - a.x);
+        }
+        return p;
+    }
+
+    vec3 OctaHemiSphereDec(vec2 coord)
+    {
+        vec3 p = vec3(coord.x - coord.y, 0.0, -1.0 + coord.x + coord.y);
+        vec2 a = abs(p.xz);
+        p.y = 1.0 - a.x - a.y;
+        return p;
+    }
+
+    vec3 GridToVector(vec2 coord)
+    {
+        if (uIsFullSphere) {
+            return OctaSphereDec(coord);
+        } else {
+            return OctaHemiSphereDec(coord);
+        }
+    }
+
+    // Frame index (gridFloor + corner offset) -> baked view direction.
+    // Frame coords at the grid border can sit slightly outside the
+    // [0, uFrames-1] range (e.g. gridFloor + (1,1) at the corner); clamp so
+    // we don't feed invalid UVs to the octahedral decoder.
+    vec3 FrameToRay(vec2 frame, vec2 framesMinusOne)
+    {
+        vec2 f = clamp(frame / framesMinusOne, 0.0, 1.0);
+        return normalize(GridToVector(f));
+    }
+`;
+
+/**
+ * Bilinear weights over the four corners of the current atlas cell.
+ *
+ * The impostor family blends a full 2x2 cell rather than interpolating over
+ * three corners: triangle interpolation has a C1-discontinuous "diagonal
+ * switch" whose weight derivative jumps inside the cell, which reads as a snap.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_BILINEAR_WEIGHTS = `
+    // Bilinear weights over the 4 corners of the current cell, in the
+    // order (w00, w10, w01, w11) matching gridFloor + (0,0)/(1,0)/(0,1)/(1,1).
+    vec4 BilinearWeights(vec2 frac_uv)
+    {
+        vec2 omuv = vec2(1.0) - frac_uv;
+        return vec4(
+            omuv.x * omuv.y,      // w00
+            frac_uv.x * omuv.y,   // w10
+            omuv.x * frac_uv.y,   // w01
+            frac_uv.x * frac_uv.y // w11
+        );
+    }
+`;
+
+/**
+ * Card-UV -> single-frame texture-UV rotation matrix.
+ *
+ * Each atlas frame was baked with its own camera right/up (three.js
+ * `Camera.lookAt` with up=(0,1,0)); near the octahedral pole those right-axes
+ * swing by 90 degrees or more between adjacent frames, so the four blended
+ * corners have to be rotated into a common orientation first.
+ *
+ * The `abs(D_frame.y) > 0.99999` nudge mirrors three.js's own polar
+ * degeneracy handling so the shader basis matches what the baker used.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_COMPUTE_FRAME_XFORM = `
+    // Build the 2x2 matrix that maps card-centred UV (vUv - 0.5) into the
+    // texture-centred UV of a single baked frame. The matrix is just the
+    // (tangent_OS, binormal_OS) basis expressed in the frame's own
+    // (bake_right, bake_up) basis — i.e. how a step along the card's local
+    // axes shows up in the texture the frame was rendered into.
+    //
+    // bake_right/bake_up follow three.js Camera.lookAt with up=(0,1,0).
+    // We mirror its polar nudge so our shader basis matches what the
+    // baker actually used when D_frame is parallel to up.
+    vec4 ComputeFrameXform(vec3 D_frame, vec3 tangent_OS, vec3 binormal_OS)
+    {
+        vec3 D = abs(D_frame.y) > 0.99999
+                 ? normalize(D_frame + vec3(0.0, 0.0, 0.0001))
+                 : D_frame;
+        vec3 bake_right = normalize(cross(vec3(0.0, 1.0, 0.0), D));
+        vec3 bake_up    = cross(D, bake_right);
+        return vec4(
+            dot(tangent_OS,  bake_right),
+            dot(binormal_OS, bake_right),
+            dot(tangent_OS,  bake_up),
+            dot(binormal_OS, bake_up)
+        );
+    }
+`;
+
+/**
+ * Fragment-side application of a `ComputeFrameXform` matrix to a card UV.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_APPLY_FRAME_XFORM = `
+    // Apply a per-frame 2x2 rotation matrix to a card UV, rotating around
+    // the texture centre (0.5, 0.5). xform = (a, b, c, d) packs row-major
+    // [a b ; c d].
+    vec2 apply_frame_xform(vec2 card_uv, vec4 xform)
+    {
+        vec2 c = card_uv - 0.5;
+        return vec2(
+            xform.x * c.x + xform.y * c.y,
+            xform.z * c.x + xform.w * c.y
+        ) + 0.5;
+    }
+`;
+
+/**
+ * Sample one card UV from the four cell-corner atlas frames and blend.
+ *
+ * Requires `apply_frame_xform` (see {@link GLSL_IMPOSTOR_APPLY_FRAME_XFORM})
+ * and `uniform float uFrames;`.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_BLEND_4_FRAMES = `
+    // Sample the same card-UV from the 4 cell-corner atlas frames, applying
+    // each frame's own UV rotation so the textures land in a consistent
+    // orientation, then blend with the bilinear weights. Used for both
+    // depth and colour.
+    vec4 blend_4_frames(
+        sampler2D tex, vec2 card_uv,
+        vec2 gridFloor, vec4 w,
+        vec4 x00, vec4 x10, vec4 x01, vec4 x11
+    ) {
+        vec2 frame_size = vec2(1.0 / uFrames);
+        // Clamp inside the unit square AFTER the per-frame rotation: at
+        // sharp angles the rotation can push a corner UV outside [0,1] and
+        // bleed into the neighbouring atlas tile (which is a completely
+        // different bake direction). Clamping keeps the sample inside the
+        // frame it's supposed to belong to.
+        vec2 uv00 = clamp(apply_frame_xform(card_uv, x00), 0.0, 1.0);
+        vec2 uv10 = clamp(apply_frame_xform(card_uv, x10), 0.0, 1.0);
+        vec2 uv01 = clamp(apply_frame_xform(card_uv, x01), 0.0, 1.0);
+        vec2 uv11 = clamp(apply_frame_xform(card_uv, x11), 0.0, 1.0);
+        vec4 s00 = texture(tex, (gridFloor + vec2(0.0, 0.0) + uv00) * frame_size);
+        vec4 s10 = texture(tex, (gridFloor + vec2(1.0, 0.0) + uv10) * frame_size);
+        vec4 s01 = texture(tex, (gridFloor + vec2(0.0, 1.0) + uv01) * frame_size);
+        vec4 s11 = texture(tex, (gridFloor + vec2(1.0, 1.0) + uv11) * frame_size);
+        return s00 * w.x + s10 * w.y + s01 * w.z + s11 * w.w;
+    }
+`;
+
+/**
+ * Decode an atlas normal (stored in bake-camera view space) back to object
+ * space, given the frame's own bake direction.
+ *
+ * The bake basis reconstruction here MUST match
+ * {@link GLSL_IMPOSTOR_COMPUTE_FRAME_XFORM} and `BakeShaderStandard`'s encode
+ * side, including the polar nudge threshold — a normal decoded in the wrong
+ * basis tilts lighting rather than producing an obvious artefact.
+ *
+ * @type {string}
+ */
+export const GLSL_IMPOSTOR_DECODE_NORMAL_OS = `
+    // Decode encoded RGB (bake-view-space normal) back to OBJECT space
+    // using the corner's D_frame direction. Mirrors BakeShaderStandard's
+    // encode side.
+    vec3 decode_normal_OS(vec3 encoded, vec3 D_frame_OS)
+    {
+        vec3 n_bv = encoded * 2.0 - 1.0;
+        vec3 D = abs(D_frame_OS.y) > 0.99999
+                 ? normalize(D_frame_OS + vec3(0.0, 0.0, 0.0001))
+                 : D_frame_OS;
+        vec3 bake_right = normalize(cross(vec3(0.0, 1.0, 0.0), D));
+        vec3 bake_up    = cross(D, bake_right);
+        return bake_right * n_bv.x + bake_up * n_bv.y + D * n_bv.z;
+    }
+`;

package/src/engine/graphics/shaders/chunks/glsl_packing.d.ts

@@ -0,0 +1,29 @@
+/**
+ * three.js's own `<packing>` GLSL chunk, re-exported as a plain string.
+ *
+ * WHY THIS EXISTS
+ *
+ * `RawShaderMaterial` skips three's automatic prefix and `#include` resolution,
+ * so a raw shader that needs `packDepthToRGBA` cannot write `#include <packing>`
+ * — it has to have the source spliced in. Both octahedral and voxel impostor
+ * depth passes needed it, and both ended up hand-transcribing the function plus
+ * its `PackUpscale` / `PackFactors` / `ShiftRight8` constants.
+ *
+ * That is a copy of three's shadow-map depth ENCODING, read back by three's own
+ * PCF sampler in `<shadowmap_pars_fragment>`. If three ever changes the
+ * encoding, a transcription breaks silently — shadows go subtly wrong rather
+ * than failing to compile. Re-exporting the real chunk means the encoder and the
+ * decoder can never disagree.
+ *
+ * This module is the single boundary where three's chunk table is read; per the
+ * codebase's "confine vendor imports to boundaries" rule, shaders import from
+ * here rather than reaching into `three` themselves.
+ *
+ * The chunk also carries `unpackRGBAToDepth`, the half-float packers and the
+ * viewZ/depth conversions. Unused GLSL functions are dead-stripped by the
+ * driver, so interpolating the whole chunk costs nothing at runtime.
+ *
+ * @type {string}
+ */
+export const GLSL_PACKING: string;
+//# sourceMappingURL=glsl_packing.d.ts.map

package/src/engine/graphics/shaders/chunks/glsl_packing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glsl_packing.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/shaders/chunks/glsl_packing.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,2BAFU,MAAM,CAEgC"}

package/src/engine/graphics/shaders/chunks/glsl_packing.js

@@ -0,0 +1,30 @@
+import { ShaderChunk } from "three";
+
+/**
+ * three.js's own `<packing>` GLSL chunk, re-exported as a plain string.
+ *
+ * WHY THIS EXISTS
+ *
+ * `RawShaderMaterial` skips three's automatic prefix and `#include` resolution,
+ * so a raw shader that needs `packDepthToRGBA` cannot write `#include <packing>`
+ * — it has to have the source spliced in. Both octahedral and voxel impostor
+ * depth passes needed it, and both ended up hand-transcribing the function plus
+ * its `PackUpscale` / `PackFactors` / `ShiftRight8` constants.
+ *
+ * That is a copy of three's shadow-map depth ENCODING, read back by three's own
+ * PCF sampler in `<shadowmap_pars_fragment>`. If three ever changes the
+ * encoding, a transcription breaks silently — shadows go subtly wrong rather
+ * than failing to compile. Re-exporting the real chunk means the encoder and the
+ * decoder can never disagree.
+ *
+ * This module is the single boundary where three's chunk table is read; per the
+ * codebase's "confine vendor imports to boundaries" rule, shaders import from
+ * here rather than reaching into `three` themselves.
+ *
+ * The chunk also carries `unpackRGBAToDepth`, the half-float packers and the
+ * viewZ/depth conversions. Unused GLSL functions are dead-stripped by the
+ * driver, so interpolating the whole chunk costs nothing at runtime.
+ *
+ * @type {string}
+ */
+export const GLSL_PACKING = ShaderChunk.packing;

package/src/engine/graphics/shaders/chunks/glsl_voxel_impostor_splat.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Vertex-stage splat expansion shared by every voxel-impostor material.
+ *
+ * WHY THIS EXISTS
+ *
+ * `VoxelImpostorShaderDepthV0` states the contract in a comment: *"Inward-shift
+ * must match the colour pass exactly so the cast silhouette agrees with the
+ * visible one"*. That invariant used to live in five separate string literals
+ * (`VoxelImpostorShaderV0`, `...NormalsV0`, `...DepthV0`, `...ViewportDepthV0`,
+ * `...LitV0`), so nothing but discipline kept the shadow caster, the colour pass
+ * and the debug visualisers agreeing about where a splat is. Now there is one
+ * definition and the invariant is structural.
+ *
+ * WHAT IT COMPUTES
+ *
+ * The quad is expanded in VIEW space. The view matrix is rigid (rotation +
+ * translation, no scale), so a view-space offset of `world_diameter * 0.5`
+ * is a world-space offset too, and perspective projection shrinks the splat
+ * with distance for free. `uPointDiameter` is in OBJECT (bake) space and is
+ * scaled into world units by the entity's uniform scale, which decouples the
+ * baked impostor data from the runtime entity scale.
+ *
+ * The centre is shifted INWARD along the surface normal by `radius_OS` so the
+ * splat's outer edge lands on the original surface — `iPosition` from the
+ * voxeliser is the un-shifted surface centroid. Without the shift a
+ * camera-facing quad of diameter D centred on the surface would stick out D/2
+ * past it on silhouette voxels and inflate the outline.
+ *
+ * HOST REQUIREMENTS
+ *
+ * Interpolate inside `void main()`. Reads `uniform float uPointDiameter`, the
+ * `iPosition` / `iNormal` per-instance attributes, the quad's `position`
+ * attribute, and `modelMatrix` / `modelViewMatrix`. Declares the locals
+ * `model_scale`, `world_diameter`, `radius_OS`, `centre_OS`, `centre_view`,
+ * `corner` and `pos_view` — project with `projectionMatrix * pos_view`.
+ *
+ * @type {string}
+ */
+export const GLSL_VOXEL_IMPOSTOR_SPLAT_EXPAND_VERTEX: string;
+//# sourceMappingURL=glsl_voxel_impostor_splat.d.ts.map

package/src/engine/graphics/shaders/chunks/glsl_voxel_impostor_splat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glsl_voxel_impostor_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/shaders/chunks/glsl_voxel_impostor_splat.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,sDAFU,MAAM,CAoBd"}

package/src/engine/graphics/shaders/chunks/glsl_voxel_impostor_splat.js

@@ -0,0 +1,57 @@
+/**
+ * Vertex-stage splat expansion shared by every voxel-impostor material.
+ *
+ * WHY THIS EXISTS
+ *
+ * `VoxelImpostorShaderDepthV0` states the contract in a comment: *"Inward-shift
+ * must match the colour pass exactly so the cast silhouette agrees with the
+ * visible one"*. That invariant used to live in five separate string literals
+ * (`VoxelImpostorShaderV0`, `...NormalsV0`, `...DepthV0`, `...ViewportDepthV0`,
+ * `...LitV0`), so nothing but discipline kept the shadow caster, the colour pass
+ * and the debug visualisers agreeing about where a splat is. Now there is one
+ * definition and the invariant is structural.
+ *
+ * WHAT IT COMPUTES
+ *
+ * The quad is expanded in VIEW space. The view matrix is rigid (rotation +
+ * translation, no scale), so a view-space offset of `world_diameter * 0.5`
+ * is a world-space offset too, and perspective projection shrinks the splat
+ * with distance for free. `uPointDiameter` is in OBJECT (bake) space and is
+ * scaled into world units by the entity's uniform scale, which decouples the
+ * baked impostor data from the runtime entity scale.
+ *
+ * The centre is shifted INWARD along the surface normal by `radius_OS` so the
+ * splat's outer edge lands on the original surface — `iPosition` from the
+ * voxeliser is the un-shifted surface centroid. Without the shift a
+ * camera-facing quad of diameter D centred on the surface would stick out D/2
+ * past it on silhouette voxels and inflate the outline.
+ *
+ * HOST REQUIREMENTS
+ *
+ * Interpolate inside `void main()`. Reads `uniform float uPointDiameter`, the
+ * `iPosition` / `iNormal` per-instance attributes, the quad's `position`
+ * attribute, and `modelMatrix` / `modelViewMatrix`. Declares the locals
+ * `model_scale`, `world_diameter`, `radius_OS`, `centre_OS`, `centre_view`,
+ * `corner` and `pos_view` — project with `projectionMatrix * pos_view`.
+ *
+ * @type {string}
+ */
+export const GLSL_VOXEL_IMPOSTOR_SPLAT_EXPAND_VERTEX = `
+        float model_scale = length(modelMatrix[0].xyz);
+        float world_diameter = uPointDiameter * model_scale;
+        float radius_OS = uPointDiameter * 0.5;
+
+        // Inward-shift along the surface normal so the splat's OUTER
+        // edge (= centre + radius along normal) lands at the original
+        // surface position (iPosition is the un-shifted surface
+        // centroid the voxeliser produced). Silhouette voxels then
+        // render edge-on exactly at the mesh outline; inside voxels are
+        // pushed slightly below the surface (sub-pixel at design
+        // distance). Every voxel-impostor pass MUST use this same shift
+        // or the shadow caster's silhouette stops matching the visible one.
+        vec3 centre_OS = iPosition - iNormal * radius_OS;
+
+        vec4 centre_view = modelViewMatrix * vec4(centre_OS, 1.0);
+        vec2 corner = position.xy * world_diameter;
+        vec4 pos_view = centre_view + vec4(corner, 0.0, 0.0);
+`;

package/src/engine/graphics/shaders/lib/make_clouds_uniforms.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Uniform block consumed by the `clouds_*` GLSL chunks in `ShaderChunks.js`, which implement the
+ * animated cloud-shadow overlay guarded by the `SHADOWMAP_CLOUDS` define.
+ *
+ * This lives next to those chunks on purpose: the GLSL half of the feature was already centralised
+ * while the JS half was declared verbatim in {@link SplatMaterial} and {@link WaterMaterial}
+ * (13 uniforms each, differing only in the `f_CloudsIntensity` default). Renaming or adding a
+ * cloud uniform therefore needed matching edits in three files with nothing tying them together.
+ *
+ * A fresh object is returned on every call - three's `UniformsUtils.merge` clones values, but the
+ * `Vector2` instances must not be shared across materials regardless.
+ *
+ * @param {number} intensity how much the clouds darken direct diffuse light, `0` disables the effect
+ * @returns {Object<string,{type:string,value:*}>}
+ */
+export function make_clouds_uniforms(intensity: number): {
+    [x: string]: {
+        type: string;
+        value: any;
+    };
+};
+//# sourceMappingURL=make_clouds_uniforms.d.ts.map

package/src/engine/graphics/shaders/lib/make_clouds_uniforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_clouds_uniforms.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/shaders/lib/make_clouds_uniforms.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,gDAHW,MAAM;QACG,MAAM,GAAC;QAAC,IAAI,EAAC,MAAM,CAAC;QAAA,KAAK,MAAE;KAAC;EAsB/C"}

package/src/engine/graphics/shaders/lib/make_clouds_uniforms.js

@@ -0,0 +1,39 @@
+import { Vector2 } from "three";
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Uniform block consumed by the `clouds_*` GLSL chunks in `ShaderChunks.js`, which implement the
+ * animated cloud-shadow overlay guarded by the `SHADOWMAP_CLOUDS` define.
+ *
+ * This lives next to those chunks on purpose: the GLSL half of the feature was already centralised
+ * while the JS half was declared verbatim in {@link SplatMaterial} and {@link WaterMaterial}
+ * (13 uniforms each, differing only in the `f_CloudsIntensity` default). Renaming or adding a
+ * cloud uniform therefore needed matching edits in three files with nothing tying them together.
+ *
+ * A fresh object is returned on every call - three's `UniformsUtils.merge` clones values, but the
+ * `Vector2` instances must not be shared across materials regardless.
+ *
+ * @param {number} intensity how much the clouds darken direct diffuse light, `0` disables the effect
+ * @returns {Object<string,{type:string,value:*}>}
+ */
+export function make_clouds_uniforms(intensity) {
+    assert.isNumber(intensity, 'intensity');
+
+    return {
+        "f_CloudsTime": { type: "f", value: 0 },
+        "f_CloudsAmount": { type: "f", value: 0.9 },
+        "f_CloudsIntensity": { type: "f", value: intensity },
+
+        "v_CloudsSpeed_0": { type: "v2", value: new Vector2(0.03, -0.03) },
+        "v_CloudsSpeed_1": { type: "v2", value: new Vector2(0.011, -0.011) },
+        "v_CloudsSpeed_2": { type: "v2", value: new Vector2(0.023, -0.023) },
+
+        "v_CloudsSize_0": { type: "v2", value: new Vector2(40, 40) },
+        "v_CloudsSize_1": { type: "v2", value: new Vector2(20, 20) },
+        "v_CloudsSize_2": { type: "v2", value: new Vector2(10, 10) },
+
+        "t_Clouds_0": { type: "t", value: null },
+        "t_Clouds_1": { type: "t", value: null },
+        "t_Clouds_2": { type: "t", value: null }
+    };
+}

package/src/engine/graphics/texture/attribute_spec_to_three_format.d.ts

@@ -1,4 +1,10 @@
 /**
+ * Pick the three.js texture format for an {@link AttributeSpec}.
+ *
+ * The only thing this adds over {@link computeThreeTextureFormat} is the `normalized` pre-branch:
+ * normalized integer data is read as float by the sampler, so it takes the float format. The
+ * numeric-type dispatch below it used to be a second copy of `computeThreeTextureFormat`, throw
+ * message included.
  *
  * @param {AttributeSpec} spec
  * @returns {number}

package/src/engine/graphics/texture/attribute_spec_to_three_format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attribute_spec_to_three_format.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/texture/attribute_spec_to_three_format.js"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,qEAFa,MAAM,CAgBlB"}
+{"version":3,"file":"attribute_spec_to_three_format.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/texture/attribute_spec_to_three_format.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,qEAFa,MAAM,CAWlB"}

package/src/engine/graphics/texture/attribute_spec_to_three_format.js

@@ -1,10 +1,15 @@
 import { assert } from "../../../core/assert.js";
-import { NumericType } from "../../../core/math/NumericType.js";
 import { channelCountToThreeTextureFormat } from "./channelCountToThreeTextureFormat.js";
-import { channelCountToThreIntegerTextureType } from "./channelCountToThreIntegerTextureType.js";
+import { computeThreeTextureFormat } from "./computeThreeTextureFormat.js";
 import { numericTypeFromBinaryDataType } from "./numericTypeFromBinaryDataType.js";
 
 /**
+ * Pick the three.js texture format for an {@link AttributeSpec}.
+ *
+ * The only thing this adds over {@link computeThreeTextureFormat} is the `normalized` pre-branch:
+ * normalized integer data is read as float by the sampler, so it takes the float format. The
+ * numeric-type dispatch below it used to be a second copy of `computeThreeTextureFormat`, throw
+ * message included.
  *
  * @param {AttributeSpec} spec
  * @returns {number}
@@ -13,14 +18,9 @@ export function attribute_spec_to_three_format(spec) {
     assert.defined(spec, 'spec');
     assert.notNull(spec, 'spec');
 
-    const numeric_type = numericTypeFromBinaryDataType(spec.type);
-
-    if (spec.normalized || numeric_type === NumericType.Float) {
+    if (spec.normalized) {
         return channelCountToThreeTextureFormat(spec.itemSize);
-    } else if (numeric_type === NumericType.Int || numeric_type === NumericType.Uint) {
-        return channelCountToThreIntegerTextureType(spec.itemSize);
-    } else {
-        throw new Error(`Unsupported numeric type '${numeric_type}'`);
     }
 
+    return computeThreeTextureFormat(numericTypeFromBinaryDataType(spec.type), spec.itemSize);
 }