@woosh/meep-engine 2.138.17 → 2.138.19

package/src/engine/graphics/impostors/voxel/bake/voxelize_samples.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Bin every CPU sample produced by {@link read_atlas_to_samples} into a
+ * sparse uniform voxel grid, accumulating position / normal / albedo /
+ * ORM weighted by sample count. Empty cells are dropped, so the output
+ * size scales with surface coverage, not with grid_resolution^3.
+ *
+ * Accumulation rules:
+ *   - position: simple mean of sample positions in the cell (gives a
+ *     slight bias inwards on slanted surfaces but is C0 across cells)
+ *   - normal:   vector sum, normalised at output time (handles
+ *     multiple-orientation surfaces inside one cell — surfels with
+ *     opposing normals cancel, which is what voxel-LOD wants)
+ *   - albedo:   simple mean
+ *   - ORM:      simple mean per channel
+ *
+ * Voxel size is computed from the bounding box and the requested grid
+ * resolution along the longest axis. Cells are addressed by integer
+ * (ix, iy, iz) so two samples in the same cell hash identically.
+ *
+ * @param {object} params
+ * @param {Float32Array} params.samples         interleaved [pos, normal, albedo, orm]
+ * @param {number} params.sample_count          number of valid samples in `samples`
+ * @param {number[]} params.bounds_min          [x, y, z]
+ * @param {number[]} params.bounds_max          [x, y, z]
+ * @param {number} params.grid_resolution       cells along the longest axis
+ * @returns {{
+ *     points: Float32Array,
+ *     point_count: number,
+ *     voxel_size: number
+ * }}
+ */
+export function voxelize_samples({ samples, sample_count, bounds_min, bounds_max, grid_resolution }: {
+    samples: Float32Array;
+    sample_count: number;
+    bounds_min: number[];
+    bounds_max: number[];
+    grid_resolution: number;
+}): {
+    points: Float32Array;
+    point_count: number;
+    voxel_size: number;
+};
+//# sourceMappingURL=voxelize_samples.d.ts.map

package/src/engine/graphics/impostors/voxel/bake/voxelize_samples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voxelize_samples.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/impostors/voxel/bake/voxelize_samples.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAXgC,OAAO,EAA5B,YAAY;IACG,YAAY,EAA3B,MAAM;IACW,UAAU,EAA3B,MAAM,EAAE;IACS,UAAU,EAA3B,MAAM,EAAE;IACO,eAAe,EAA9B,MAAM;;YAEF,YAAY;iBACP,MAAM;gBACP,MAAM;EAwJxB"}

package/src/engine/graphics/impostors/voxel/bake/voxelize_samples.js

@@ -0,0 +1,192 @@
+import { convert_channel_linear_to_sRGB } from "../../../../../core/color/sRGB/linear_to_sRGB.js";
+import {
+    VOXEL_POINT_OFFSET_ALBEDO,
+    VOXEL_POINT_OFFSET_NORMAL,
+    VOXEL_POINT_OFFSET_ORM,
+    VOXEL_POINT_OFFSET_POSITION,
+    VOXEL_POINT_STRIDE
+} from "../VoxelImpostorDescription.js";
+import { ATLAS_SAMPLE_STRIDE } from "./read_atlas_to_samples.js";
+
+
+/**
+ * Bin every CPU sample produced by {@link read_atlas_to_samples} into a
+ * sparse uniform voxel grid, accumulating position / normal / albedo /
+ * ORM weighted by sample count. Empty cells are dropped, so the output
+ * size scales with surface coverage, not with grid_resolution^3.
+ *
+ * Accumulation rules:
+ *   - position: simple mean of sample positions in the cell (gives a
+ *     slight bias inwards on slanted surfaces but is C0 across cells)
+ *   - normal:   vector sum, normalised at output time (handles
+ *     multiple-orientation surfaces inside one cell — surfels with
+ *     opposing normals cancel, which is what voxel-LOD wants)
+ *   - albedo:   simple mean
+ *   - ORM:      simple mean per channel
+ *
+ * Voxel size is computed from the bounding box and the requested grid
+ * resolution along the longest axis. Cells are addressed by integer
+ * (ix, iy, iz) so two samples in the same cell hash identically.
+ *
+ * @param {object} params
+ * @param {Float32Array} params.samples         interleaved [pos, normal, albedo, orm]
+ * @param {number} params.sample_count          number of valid samples in `samples`
+ * @param {number[]} params.bounds_min          [x, y, z]
+ * @param {number[]} params.bounds_max          [x, y, z]
+ * @param {number} params.grid_resolution       cells along the longest axis
+ * @returns {{
+ *     points: Float32Array,
+ *     point_count: number,
+ *     voxel_size: number
+ * }}
+ */
+export function voxelize_samples({
+                                     samples,
+                                     sample_count,
+                                     bounds_min,
+                                     bounds_max,
+                                     grid_resolution
+                                 }) {
+
+    // 1. Voxel cell size = longest axis / grid_resolution. Keeps cells
+    //    isotropic; the grid extents on the shorter axes round up to
+    //    cover the bounds.
+    const extent_x = bounds_max[0] - bounds_min[0];
+    const extent_y = bounds_max[1] - bounds_min[1];
+    const extent_z = bounds_max[2] - bounds_min[2];
+    const max_extent = Math.max(extent_x, extent_y, Math.max(extent_z, 1e-6));
+
+    const voxel_size = max_extent / grid_resolution;
+    const inv_voxel_size = 1 / voxel_size;
+
+    // Per-axis cell counts after isotropic cell sizing — used to pack
+    // (ix, iy, iz) into a single integer key without collisions inside
+    // the bounding region.
+    const cells_x = Math.max(1, Math.ceil(extent_x * inv_voxel_size) + 1);
+    const cells_y = Math.max(1, Math.ceil(extent_y * inv_voxel_size) + 1);
+    const cells_z = Math.max(1, Math.ceil(extent_z * inv_voxel_size) + 1);
+
+    // 2. Sparse accumulator keyed on a packed cell index. Each value is
+    //    a 13-float record: [px, py, pz, nx, ny, nz, ar, ag, ab, o, r, m, count].
+    //    Using a flat Float32Array inside the map keeps allocation
+    //    pressure low for big sample sets.
+    /** @type {Map<number, Float32Array>} */
+    const cell_map = new Map();
+
+    const CELL_STRIDE = 13;
+
+    for (let i = 0; i < sample_count; i++) {
+        const src = i * ATLAS_SAMPLE_STRIDE;
+
+        const sx = samples[src];
+        const sy = samples[src + 1];
+        const sz = samples[src + 2];
+
+        // Skip samples that fell outside the captured bounds (can happen
+        // with depth quantisation at the very edge of the bounding sphere).
+        if (sx < bounds_min[0] || sx > bounds_max[0]) continue;
+        if (sy < bounds_min[1] || sy > bounds_max[1]) continue;
+        if (sz < bounds_min[2] || sz > bounds_max[2]) continue;
+
+        const ix = Math.floor((sx - bounds_min[0]) * inv_voxel_size);
+        const iy = Math.floor((sy - bounds_min[1]) * inv_voxel_size);
+        const iz = Math.floor((sz - bounds_min[2]) * inv_voxel_size);
+
+        // Key needs ~10 bits per axis for typical grids (1024^3 max);
+        // bit-packing keeps us under JS's safe integer range easily.
+        const key = ix + iy * cells_x + iz * cells_x * cells_y;
+
+        let acc = cell_map.get(key);
+        if (acc === undefined) {
+            acc = new Float32Array(CELL_STRIDE);
+            cell_map.set(key, acc);
+        }
+
+        acc[0]  += sx;
+        acc[1]  += sy;
+        acc[2]  += sz;
+
+        acc[3]  += samples[src + 3];
+        acc[4]  += samples[src + 4];
+        acc[5]  += samples[src + 5];
+
+        acc[6]  += samples[src + 6];
+        acc[7]  += samples[src + 7];
+        acc[8]  += samples[src + 8];
+
+        acc[9]  += samples[src + 9];
+        acc[10] += samples[src + 10];
+        acc[11] += samples[src + 11];
+
+        acc[12] += 1;
+    }
+
+    // 3. Pack the surviving cells into the final interleaved point
+    //    buffer. Cell ordering is whatever Map iteration gives us; the
+    //    runtime renderer doesn't care because each instance is
+    //    self-contained.
+    //
+    //    Position-finding: arithmetic mean of sample positions —
+    //    the centroid, which sits roughly on the original mesh
+    //    surface. The silhouette-tightening inward-shift is applied
+    //    at render time (see VoxelImpostorShaderV0 etc.) rather than
+    //    baked in, because the shift amount depends on the splat
+    //    diameter the renderer chooses — keeping the bake output
+    //    representation-neutral lets a renderer override the
+    //    description's recommended diameter (eg for tighter fit /
+    //    bigger overlap) without re-baking.
+    const point_count = cell_map.size;
+    const points = new Float32Array(point_count * VOXEL_POINT_STRIDE);
+
+    let dst = 0;
+    for (const acc of cell_map.values()) {
+        const count = acc[12];
+        const inv_count = 1 / count;
+
+        // normal: normalise the vector sum so cells that saw conflicting
+        // orientations (eg both sides of a thin wall) end up with a
+        // length-shorter normal — the lit shader can renormalise but it
+        // never sees a 'wrong' average orientation.
+        let nx = acc[3];
+        let ny = acc[4];
+        let nz = acc[5];
+        const nlen = Math.sqrt(nx * nx + ny * ny + nz * nz);
+        if (nlen > 1e-6) {
+            nx /= nlen;
+            ny /= nlen;
+            nz /= nlen;
+        }
+        points[dst + VOXEL_POINT_OFFSET_NORMAL]     = nx;
+        points[dst + VOXEL_POINT_OFFSET_NORMAL + 1] = ny;
+        points[dst + VOXEL_POINT_OFFSET_NORMAL + 2] = nz;
+
+        // position: centroid of samples (raw surface position).
+        points[dst + VOXEL_POINT_OFFSET_POSITION]     = acc[0] * inv_count;
+        points[dst + VOXEL_POINT_OFFSET_POSITION + 1] = acc[1] * inv_count;
+        points[dst + VOXEL_POINT_OFFSET_POSITION + 2] = acc[2] * inv_count;
+
+        // albedo: arithmetic mean (samples were linearised in
+        // read_atlas_to_samples so this average is physically
+        // correct), then re-encode to sRGB so the runtime shaders see
+        // the same "sRGB bytes labelled linear" format the octahedral
+        // path uses. Lit shader's sRGBToLinear() decodes back to
+        // linear for PBR; unlit shader writes the sRGB-encoded bytes
+        // through to the framebuffer.
+        points[dst + VOXEL_POINT_OFFSET_ALBEDO]     = convert_channel_linear_to_sRGB(acc[6] * inv_count);
+        points[dst + VOXEL_POINT_OFFSET_ALBEDO + 1] = convert_channel_linear_to_sRGB(acc[7] * inv_count);
+        points[dst + VOXEL_POINT_OFFSET_ALBEDO + 2] = convert_channel_linear_to_sRGB(acc[8] * inv_count);
+
+        // orm: arithmetic mean (each channel independent)
+        points[dst + VOXEL_POINT_OFFSET_ORM]     = acc[9]  * inv_count;
+        points[dst + VOXEL_POINT_OFFSET_ORM + 1] = acc[10] * inv_count;
+        points[dst + VOXEL_POINT_OFFSET_ORM + 2] = acc[11] * inv_count;
+
+        dst += VOXEL_POINT_STRIDE;
+    }
+
+    return {
+        points,
+        point_count,
+        voxel_size
+    };
+}

package/src/engine/graphics/impostors/voxel/prototype_voxel_impostors.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prototype_voxel_impostors.d.ts.map

package/src/engine/graphics/impostors/voxel/prototype_voxel_impostors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prototype_voxel_impostors.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/impostors/voxel/prototype_voxel_impostors.js"],"names":[],"mappings":""}

package/src/engine/graphics/impostors/voxel/prototype_voxel_impostors.js

@@ -0,0 +1,343 @@
+import Quaternion from "../../../../core/geom/Quaternion.js";
+import Vector2 from "../../../../core/geom/Vector2.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../../core/math/DEG_TO_RAD.js";
+import { GameAssetType } from "../../../asset/GameAssetType.js";
+import { GLTFAssetLoader } from "../../../asset/loaders/GLTFAssetLoader.js";
+import Entity from "../../../ecs/Entity.js";
+import GUIElementSystem from "../../../ecs/gui/GUIElementSystem.js";
+import ViewportPositionSystem from "../../../ecs/gui/position/ViewportPositionSystem.js";
+import { TransformAttachmentSystem } from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { EngineHarness } from "../../../EngineHarness.js";
+import { BehaviorComponent } from "../../../intelligence/behavior/ecs/BehaviorComponent.js";
+import { BehaviorSystem } from "../../../intelligence/behavior/ecs/BehaviorSystem.js";
+import { RotationBehavior } from "../../../intelligence/behavior/util/RotationBehavior.js";
+import { SGMesh } from "../../ecs/mesh-v2/aggregate/SGMesh.js";
+import { SGMeshSystem } from "../../ecs/mesh-v2/aggregate/SGMeshSystem.js";
+import { ShadedGeometry } from "../../ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../ecs/mesh-v2/ShadedGeometryFlags.js";
+import { ShadedGeometrySystem } from "../../ecs/mesh-v2/ShadedGeometrySystem.js";
+import { ImpostorCaptureType } from "../octahedral/ImpostorCaptureType.js";
+import { load_mesh_for_bake } from "../octahedral/util/load_mesh_for_bake.js";
+import { VoxelImpostorShaderDepthV0 } from "./shader/VoxelImpostorShaderDepthV0.js";
+import { VoxelImpostorShaderLitV0 } from "./shader/VoxelImpostorShaderLitV0.js";
+import { VoxelImpostorShaderNormalsV0 } from "./shader/VoxelImpostorShaderNormalsV0.js";
+import { VoxelImpostorShaderV0 } from "./shader/VoxelImpostorShaderV0.js";
+import { VoxelImpostorShaderViewportDepthV0 } from "./shader/VoxelImpostorShaderViewportDepthV0.js";
+import { make_voxel_impostor_geometry } from "./util/make_voxel_impostor_geometry.js";
+import { VoxelImpostorBaker } from "./VoxelImpostorBaker.js";
+
+
+/**
+ * Prototype harness for the voxel impostor system. Mirrors the
+ * structure of the octahedral system's prototypeBaker.js — load a GLTF
+ * mesh, bake it through {@link VoxelImpostorBaker}, then lay out a
+ * lineup of variants side-by-side so visual differences are easy to
+ * compare against the truth mesh.
+ *
+ * Slot layout (along +X from x=10 to x=25):
+ *   0  : V0 unlit (square splats)
+ *   1  : V0 unlit with disc mask (shows splat shape clearly)
+ *   2  : Lit V0 — only one that receives shadows
+ *   3  : Normals viz (debug pair for the lit variant)
+ *   4  : Viewport-depth viz
+ *   5  : True mesh (ground-truth reference)
+ *
+ * @param {Engine} engine
+ * @return {Promise<void>}
+ */
+async function main(engine) {
+    await EngineHarness.buildBasics({
+        engine,
+        enableWater: false,
+        cameraFieldOfView: 45,
+        showFps: false,
+        enableLights: true,
+        enableShadows: true,
+        cameraAutoClip: true,
+        // Mirror the octahedral prototype's terrain layout so the same
+        // EngineHarness defaults give us a sensible camera framing.
+        terrainSize: new Vector2(18, 12),
+        focus: new Vector3(17, 0, 10),
+    });
+
+    const ecd = engine.entityManager.dataset;
+
+    const baker = new VoxelImpostorBaker();
+    const renderer = engine.graphics.renderer;
+    baker.renderer = renderer;
+
+    // const path = 'data/models/LowPolyTownshipSet/Small_house/Small_house.gltf';
+    // const path = 'data/models/samples/textured_unit_cube.gltf';
+    // const path = 'data/models/samples/teapot.gltf';
+    // const path = 'data/models/LowPolyTownshipSet/Barrel/model.gltf';
+    // const path = 'data/models/LowPolyTownshipSet/Town_Hall/model.gltf';
+    // const path = 'data/models/MOBA and Tower Defense/Tree_01.gltf';
+    const path = 'data/models/samples/just_a_girl/scene.gltf';
+    // const path = 'data/models/road_bike/road_bike.gltf'; //large CAD-type model
+
+    const objects = await load_mesh_for_bake(engine, path);
+
+    const id = baker.bake({
+        objects,
+        point_budget: 4096,
+        // Atlas frame/resolution are conservative defaults — they
+        // control how dense the SAMPLE cloud is, not the OUTPUT point
+        // count. The budget is what caps the output. Tweak `frames`
+        // up for hard-to-cover shapes (think: deep concavities) and
+        // `resolution` up if voxels look noisy in their averaged colour.
+        frames: 16,
+        resolution: 1024,
+        capture_type: ImpostorCaptureType.FullSphere
+    });
+
+    console.log(id);
+
+    const t0 = Transform.fromJSON({
+        position: { x: 10, y: 0.5, z: 10 },
+        scale: 3,
+        rotation: Quaternion.fromEulerAngles(0, 90 * DEG_TO_RAD, 0)
+    });
+
+    // Match the octahedral prototype's sizing: 3 world units across the
+    // bounding sphere diameter. The voxel point cloud occupies the
+    // same volume as the source mesh (each splat is sized in world
+    // space — see the shaders' uPointDiameter doc — and the bounding
+    // sphere comes straight from the bake), so the same Transform
+    // scale that fits the octahedral card here also fits the voxel
+    // cloud.
+    t0.scale.setScalar(3 / (id.sphere_radius * 2));
+
+    // Splat diameter in OBJECT space, auto-tuned by the baker —
+    // sqrt(2) * voxel_size, which covers worst-case oblique
+    // projections of each voxel cell. The shaders apply a render-time
+    // inward-shift of half this value along the surface normal, so
+    // even with the overlap the silhouette stays tight against the
+    // original mesh outline. Override here for tighter (= voxel_size)
+    // or looser (~ 1.5+ * voxel_size) fits per asset.
+    const point_diameter_OS = id.point_diameter;
+
+    // Slot 0: V0 unlit, square splats.
+    make_voxel_entity({ id, t: t0, point_diameter: point_diameter_OS }).build(ecd);
+
+    // Slot 1: V0 unlit with disc mask — shows splat shape directly,
+    // useful for seeing the underlying point distribution.
+    const t_disc = new Transform();
+    t_disc.copy(t0);
+    t_disc.position._add(3, 0, 0);
+    make_voxel_entity({ id, t: t_disc, disc_mask: true, point_diameter: point_diameter_OS }).build(ecd);
+
+    // Slot 2: lit variant — only one that receives shadows.
+    const t_lit = new Transform();
+    t_lit.copy(t0);
+    t_lit.position._add(6, 0, 0);
+    make_voxel_lit_entity({ id, t: t_lit, point_diameter: point_diameter_OS }).build(ecd);
+
+    // Slot 3: world-space-normal viz — diagnostics for the lit shader.
+    const t_normals = new Transform();
+    t_normals.copy(t0);
+    t_normals.position._add(9, 0, 0);
+    make_voxel_normals_entity({ id, t: t_normals, point_diameter: point_diameter_OS }).build(ecd);
+
+    // Slot 4: viewport-depth viz — diagnostics for the depth caster.
+    const t_depth = new Transform();
+    t_depth.copy(t0);
+    t_depth.position._add(12, 0, 0);
+    make_voxel_viewport_depth_entity({ id, t: t_depth, point_diameter: point_diameter_OS }).build(ecd);
+
+    // Slot 5: true mesh ground truth.
+    const t_truth = new Transform();
+    t_truth.copy(t0);
+    t_truth.position._add(15, 0, 0);
+
+    const sg_mesh = SGMesh.fromURL(path);
+    sg_mesh.castShadow = true;
+    sg_mesh.receiveShadow = true;
+
+    new Entity()
+        .add(sg_mesh)
+        .add(t_truth)
+        .build(ecd);
+
+    // [entity_impostor].forEach(e => make_spin(e));
+}
+
+
+/**
+ * Apply a rotation behavior to an entity — useful for visually
+ * confirming the impostor stays consistent under rotation. Off by
+ * default, see the line at the end of main().
+ *
+ * @param {Entity} entity
+ * @param {number} [speed]
+ * @param {Vector3} [axis]
+ */
+function make_spin(entity, speed = 1, axis = Vector3.up) {
+    /**
+     * @type {Transform}
+     */
+    const t = entity.getComponent(Transform);
+
+    if (t === null) {
+        return;
+    }
+
+    entity.add(BehaviorComponent.from(RotationBehavior.fromJSON({
+        axis, speed
+    })));
+}
+
+
+/**
+ * Build a paired depth material whose point diameter and disc mask
+ * agree with the colour material. ShadedGeometry uses depth_material
+ * for the shadow pass, so this keeps the cast silhouette aligned
+ * with the visible one.
+ *
+ * @param {number} point_diameter   object-space splat diameter
+ * @param {boolean} disc_mask
+ */
+function make_voxel_depth_material(point_diameter, disc_mask) {
+    const m = new VoxelImpostorShaderDepthV0();
+    m.uniforms.uPointDiameter.value = point_diameter;
+    m.uniforms.uDiscMask.value = disc_mask;
+    return m;
+}
+
+
+/**
+ * Slot 0/1 factory: unlit voxel splats. Each instance is a
+ * world-space-sized camera-facing billboard; the depth-caster
+ * mirrors the same world size so the shadow silhouette agrees.
+ *
+ * @param {object} params
+ * @param {VoxelImpostorDescription} params.id
+ * @param {Transform} [params.t]
+ * @param {boolean} [params.disc_mask]
+ * @param {number} params.point_diameter   object-space splat diameter
+ * @returns {Entity}
+ */
+function make_voxel_entity({ id, t = new Transform(), disc_mask = false, point_diameter }) {
+    const mat = new VoxelImpostorShaderV0();
+    mat.uniforms.uPointDiameter.value = point_diameter;
+    mat.uniforms.uDiscMask.value = disc_mask;
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(make_voxel_impostor_geometry(id), mat);
+    sg.depth_material = make_voxel_depth_material(point_diameter, disc_mask);
+    // Unlit splats don't receive shadow, same convention as the
+    // octahedral V0 (its lit shader is the only receiver).
+    sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
+
+    return new Entity()
+        .add(transform)
+        .add(sg);
+}
+
+
+/**
+ * Slot 2 factory: lit voxel splats. Casts AND receives shadows. The
+ * lighting equations consume the per-instance baked normal directly,
+ * so each splat's shading follows the surface orientation at the
+ * sampled voxel.
+ *
+ * @param {object} params
+ * @param {VoxelImpostorDescription} params.id
+ * @param {Transform} [params.t]
+ * @param {number} params.point_diameter
+ * @returns {Entity}
+ */
+function make_voxel_lit_entity({ id, t = new Transform(), point_diameter }) {
+    const mat = new VoxelImpostorShaderLitV0();
+    mat.uniforms.uPointDiameter.value = point_diameter;
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(make_voxel_impostor_geometry(id), mat);
+    sg.depth_material = make_voxel_depth_material(point_diameter, false);
+    // CastShadow + ReceiveShadow on by default.
+
+    return new Entity()
+        .add(transform)
+        .add(sg);
+}
+
+
+/**
+ * Slot 3 factory: per-voxel normal as RGB. Reads the same iNormal
+ * attribute the lit shader feeds its lighting equations.
+ *
+ * @param {object} params
+ * @param {VoxelImpostorDescription} params.id
+ * @param {Transform} [params.t]
+ * @param {number} params.point_diameter
+ * @returns {Entity}
+ */
+function make_voxel_normals_entity({ id, t = new Transform(), point_diameter }) {
+    const mat = new VoxelImpostorShaderNormalsV0();
+    mat.uniforms.uPointDiameter.value = point_diameter;
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(make_voxel_impostor_geometry(id), mat);
+    sg.depth_material = make_voxel_depth_material(point_diameter, false);
+    // Viz pass: don't participate in shadow casting/receiving, same as
+    // the octahedral normals viz — keeps it from influencing neighbours.
+    sg.clearFlag(ShadedGeometryFlags.CastShadow);
+    sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
+
+    return new Entity()
+        .add(transform)
+        .add(sg);
+}
+
+
+/**
+ * Slot 4 factory: viewport-depth viz. Helpful for verifying the splat
+ * cloud's depth matches the truth mesh (eg before bumping into a
+ * receiving wall).
+ *
+ * @param {object} params
+ * @param {VoxelImpostorDescription} params.id
+ * @param {Transform} [params.t]
+ * @param {number} params.point_diameter
+ * @returns {Entity}
+ */
+function make_voxel_viewport_depth_entity({ id, t = new Transform(), point_diameter }) {
+    const mat = new VoxelImpostorShaderViewportDepthV0();
+    mat.uniforms.uPointDiameter.value = point_diameter;
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(make_voxel_impostor_geometry(id), mat);
+    sg.depth_material = make_voxel_depth_material(point_diameter, false);
+    sg.clearFlag(ShadedGeometryFlags.CastShadow);
+    sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
+
+    return new Entity()
+        .add(transform)
+        .add(sg);
+}
+
+
+new EngineHarness().initialize({
+    configuration(config, engine) {
+        config.addSystem(new GUIElementSystem(engine.gui.view, engine));
+        config.addSystem(new ViewportPositionSystem(engine.graphics.viewport.size));
+        config.addSystem(new ShadedGeometrySystem(engine));
+        config.addSystem(new SGMeshSystem(engine));
+        config.addSystem(new TransformAttachmentSystem());
+        config.addSystem(new BehaviorSystem(engine));
+
+        const gltfAssetLoader = new GLTFAssetLoader();
+
+        config.addLoader(GameAssetType.ModelGLTF, gltfAssetLoader);
+        config.addLoader(GameAssetType.ModelGLTF_JSON, gltfAssetLoader);
+    }
+}).then(main);

package/src/engine/graphics/impostors/voxel/shader/VoxelImpostorShaderDepthV0.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Depth-pass companion to {@link VoxelImpostorShaderLitV0}. Wire as
+ * ShadedGeometry.depth_material so the impostor casts a shadow whose
+ * silhouette matches the visible splat cloud (modulo the half-splat
+ * normal bias the lit shader applies on the receiver side).
+ *
+ * Keep `uPointDiameter` and `uDiscMask` aligned with the colour pass.
+ */
+export class VoxelImpostorShaderDepthV0 extends RawShaderMaterial {
+    constructor();
+}
+import { RawShaderMaterial } from "three";
+//# sourceMappingURL=VoxelImpostorShaderDepthV0.d.ts.map

package/src/engine/graphics/impostors/voxel/shader/VoxelImpostorShaderDepthV0.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VoxelImpostorShaderDepthV0.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/impostors/voxel/shader/VoxelImpostorShaderDepthV0.js"],"names":[],"mappings":"AA4EA;;;;;;;GAOG;AACH;IACI,cAYC;CACJ;kCAlGoD,OAAO"}