reze-engine 0.22.1 → 0.23.1

package/dist/physics-debug.js

@@ -0,0 +1,526 @@
+// Debug overlay drawing every rigidbody as a wireframe + semitransparent solid
+// primitive (sphere / box / capsule), color-coded by type:
+//   yellow = static (FollowBone)
+//   cyan   = kinematic
+//   red    = dynamic
+//
+// Rendered in its own swapchain pass AFTER composite (see Engine.renderPhysicsDebug),
+// so it sits cleanly on top of the final tonemapped image. No depth, no MSAA,
+// no MRT, no interaction with the HDR alpha gate — bodies are always fully
+// visible regardless of camera angle, model occlusion, or stacking. Reads body
+// transforms straight from RezePhysics' SoA store — zero per-frame allocations.
+import { Mat4 } from "./math";
+import { RigidbodyShape, RigidbodyType } from "./physics";
+import { PHYSICS_DEBUG_SHADER_WGSL } from "./shaders/passes/physics-debug";
+const STRIDE_BYTES = 96; // 4 mat4 cols + size+pad + color = 6 vec4
+const STRIDE_FLOATS = STRIDE_BYTES / 4;
+// Per-instance color.alpha is the WIREFRAME alpha (1.0 for crisp edges). Solid
+// pipelines override the SOLID_ALPHA shader constant to ~0.20 so the fill stays
+// gentle where many bodies overlap.
+// Hues chosen so wire+solid both read against the typical pink/grey reze studio
+// scene background. Red [1, 0.3, 0.3] sat too close to the pink bg's hue —
+// solid fill (α≈0.2) blended into the bg and the wire didn't separate from it.
+// Orange-red shifts ~30° on the hue wheel, giving real chroma against pink.
+const COLOR_STATIC = [1.0, 0.85, 0.15, 1.0]; // yellow
+const COLOR_KINEMATIC = [0.25, 0.7, 1.0, 1.0]; // cyan-blue
+const COLOR_DYNAMIC = [1.0, 0.35, 0.0, 1.0]; // orange-red
+const SOLID_ALPHA = 0.2;
+export class PhysicsDebugRenderer {
+    constructor(device, cameraUniformBuffer, presentationFormat) {
+        this.device = device;
+        const wireSphere = buildSphereWireGeometry();
+        const wireBox = buildBoxWireGeometry();
+        const wireCapsule = buildCapsuleWireGeometry();
+        this.wireSphereCount = wireSphere.length / 4;
+        this.wireBoxCount = wireBox.length / 4;
+        this.wireCapsuleCount = wireCapsule.length / 4;
+        const solidSphere = buildSphereSolidGeometry();
+        const solidBox = buildBoxSolidGeometry();
+        const solidCapsule = buildCapsuleSolidGeometry();
+        this.solidSphereCount = solidSphere.length / 4;
+        this.solidBoxCount = solidBox.length / 4;
+        this.solidCapsuleCount = solidCapsule.length / 4;
+        const upload = (label, data) => {
+            const buf = device.createBuffer({
+                label,
+                size: data.byteLength,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(buf, 0, data.buffer, data.byteOffset, data.byteLength);
+            return buf;
+        };
+        this.wireSphereBuffer = upload("physics-debug wire sphere", wireSphere);
+        this.wireBoxBuffer = upload("physics-debug wire box", wireBox);
+        this.wireCapsuleBuffer = upload("physics-debug wire capsule", wireCapsule);
+        this.solidSphereBuffer = upload("physics-debug solid sphere", solidSphere);
+        this.solidBoxBuffer = upload("physics-debug solid box", solidBox);
+        this.solidCapsuleBuffer = upload("physics-debug solid capsule", solidCapsule);
+        this.instanceCapacity = 512;
+        this.instanceData = new Float32Array(this.instanceCapacity * STRIDE_FLOATS);
+        this.instanceBuffer = device.createBuffer({
+            label: "physics-debug instances",
+            size: this.instanceCapacity * STRIDE_BYTES,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        const bgl = device.createBindGroupLayout({
+            label: "physics-debug bgl",
+            entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } }],
+        });
+        this.bindGroup = device.createBindGroup({
+            label: "physics-debug bg",
+            layout: bgl,
+            entries: [{ binding: 0, resource: { buffer: cameraUniformBuffer } }],
+        });
+        const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bgl] });
+        const shader = device.createShaderModule({
+            label: "physics-debug shader",
+            code: PHYSICS_DEBUG_SHADER_WGSL,
+        });
+        const vertexBuffers = [
+            {
+                arrayStride: 16,
+                attributes: [{ shaderLocation: 0, offset: 0, format: "float32x4" }],
+            },
+            {
+                arrayStride: STRIDE_BYTES,
+                stepMode: "instance",
+                attributes: [
+                    { shaderLocation: 1, offset: 0, format: "float32x4" },
+                    { shaderLocation: 2, offset: 16, format: "float32x4" },
+                    { shaderLocation: 3, offset: 32, format: "float32x4" },
+                    { shaderLocation: 4, offset: 48, format: "float32x4" },
+                    { shaderLocation: 5, offset: 64, format: "float32x4" },
+                    { shaderLocation: 6, offset: 80, format: "float32x4" },
+                ],
+            },
+        ];
+        const targets = [
+            {
+                format: presentationFormat,
+                blend: {
+                    color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                    alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                },
+            },
+        ];
+        const buildPipeline = (label, kind, topology, solidAlpha) => device.createRenderPipeline({
+            label,
+            layout: pipelineLayout,
+            vertex: {
+                module: shader,
+                entryPoint: "vsMain",
+                buffers: vertexBuffers,
+                constants: { SHAPE_KIND: kind },
+            },
+            fragment: {
+                module: shader,
+                entryPoint: "fsMain",
+                targets,
+                constants: { SOLID_ALPHA: solidAlpha },
+            },
+            primitive: { topology, cullMode: "none" },
+            // No depth attachment, single multisample — pass renders straight to
+            // the swapchain after composite, so the overlay sits on top of the
+            // tonemapped scene without interacting with depth/stencil/MSAA.
+            multisample: { count: 1 },
+        });
+        this.wirePipelineSphere = buildPipeline("physics-debug wire sphere", 0, "line-list", 1.0);
+        this.wirePipelineBox = buildPipeline("physics-debug wire box", 1, "line-list", 1.0);
+        this.wirePipelineCapsule = buildPipeline("physics-debug wire capsule", 2, "line-list", 1.0);
+        this.solidPipelineSphere = buildPipeline("physics-debug solid sphere", 0, "triangle-list", SOLID_ALPHA);
+        this.solidPipelineBox = buildPipeline("physics-debug solid box", 1, "triangle-list", SOLID_ALPHA);
+        this.solidPipelineCapsule = buildPipeline("physics-debug solid capsule", 2, "triangle-list", SOLID_ALPHA);
+    }
+    render(pass, physics) {
+        const rigidbodies = physics.getRigidbodies();
+        const N = rigidbodies.length;
+        if (N === 0)
+            return;
+        const store = physics.getStore();
+        const positions = store.positions;
+        const orientations = store.orientations;
+        if (N > this.instanceCapacity) {
+            this.instanceCapacity = Math.max(N, this.instanceCapacity * 2);
+            this.instanceData = new Float32Array(this.instanceCapacity * STRIDE_FLOATS);
+            this.instanceBuffer.destroy();
+            this.instanceBuffer = this.device.createBuffer({
+                label: "physics-debug instances",
+                size: this.instanceCapacity * STRIDE_BYTES,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+        }
+        // Two passes: count per-shape, then fill packed by shape so we can issue
+        // 3 instanced draws with vertex-buffer offsets.
+        let sphereCount = 0;
+        let boxCount = 0;
+        let capsuleCount = 0;
+        for (let i = 0; i < N; i++) {
+            const s = rigidbodies[i].shape;
+            if (s === RigidbodyShape.Sphere)
+                sphereCount++;
+            else if (s === RigidbodyShape.Box)
+                boxCount++;
+            else
+                capsuleCount++;
+        }
+        const sphereOffset = 0;
+        const boxOffset = sphereCount;
+        const capsuleOffset = sphereCount + boxCount;
+        const data = this.instanceData;
+        let sIdx = sphereOffset;
+        let bIdx = boxOffset;
+        let cIdx = capsuleOffset;
+        for (let i = 0; i < N; i++) {
+            const rb = rigidbodies[i];
+            const i3 = i * 3;
+            const i4 = i * 4;
+            let slot;
+            if (rb.shape === RigidbodyShape.Sphere)
+                slot = sIdx++;
+            else if (rb.shape === RigidbodyShape.Box)
+                slot = bIdx++;
+            else
+                slot = cIdx++;
+            const dst = slot * STRIDE_FLOATS;
+            // Model matrix: rotation from quat into [dst..dst+15], then translation.
+            Mat4.fromQuatInto(orientations[i4 + 0], orientations[i4 + 1], orientations[i4 + 2], orientations[i4 + 3], data, dst);
+            data[dst + 12] = positions[i3 + 0];
+            data[dst + 13] = positions[i3 + 1];
+            data[dst + 14] = positions[i3 + 2];
+            // size + pad
+            data[dst + 16] = rb.size.x;
+            data[dst + 17] = rb.size.y;
+            data[dst + 18] = rb.size.z;
+            data[dst + 19] = 0;
+            const c = rb.type === RigidbodyType.Static
+                ? COLOR_STATIC
+                : rb.type === RigidbodyType.Kinematic
+                    ? COLOR_KINEMATIC
+                    : COLOR_DYNAMIC;
+            data[dst + 20] = c[0];
+            data[dst + 21] = c[1];
+            data[dst + 22] = c[2];
+            data[dst + 23] = c[3];
+        }
+        this.device.queue.writeBuffer(this.instanceBuffer, 0, data.buffer, data.byteOffset, N * STRIDE_BYTES);
+        pass.setBindGroup(0, this.bindGroup);
+        // Solid fills first (gentle ~20% alpha for shape ID), wireframe edges on top
+        // (95% alpha for crisp silhouette).
+        if (sphereCount > 0) {
+            const off = sphereOffset * STRIDE_BYTES;
+            const size = sphereCount * STRIDE_BYTES;
+            pass.setPipeline(this.solidPipelineSphere);
+            pass.setVertexBuffer(0, this.solidSphereBuffer);
+            pass.setVertexBuffer(1, this.instanceBuffer, off, size);
+            pass.draw(this.solidSphereCount, sphereCount);
+            pass.setPipeline(this.wirePipelineSphere);
+            pass.setVertexBuffer(0, this.wireSphereBuffer);
+            pass.setVertexBuffer(1, this.instanceBuffer, off, size);
+            pass.draw(this.wireSphereCount, sphereCount);
+        }
+        if (boxCount > 0) {
+            const off = boxOffset * STRIDE_BYTES;
+            const size = boxCount * STRIDE_BYTES;
+            pass.setPipeline(this.solidPipelineBox);
+            pass.setVertexBuffer(0, this.solidBoxBuffer);
+            pass.setVertexBuffer(1, this.instanceBuffer, off, size);
+            pass.draw(this.solidBoxCount, boxCount);
+            pass.setPipeline(this.wirePipelineBox);
+            pass.setVertexBuffer(0, this.wireBoxBuffer);
+            pass.setVertexBuffer(1, this.instanceBuffer, off, size);
+            pass.draw(this.wireBoxCount, boxCount);
+        }
+        if (capsuleCount > 0) {
+            const off = capsuleOffset * STRIDE_BYTES;
+            const size = capsuleCount * STRIDE_BYTES;
+            pass.setPipeline(this.solidPipelineCapsule);
+            pass.setVertexBuffer(0, this.solidCapsuleBuffer);
+            pass.setVertexBuffer(1, this.instanceBuffer, off, size);
+            pass.draw(this.solidCapsuleCount, capsuleCount);
+            pass.setPipeline(this.wirePipelineCapsule);
+            pass.setVertexBuffer(0, this.wireCapsuleBuffer);
+            pass.setVertexBuffer(1, this.instanceBuffer, off, size);
+            pass.draw(this.wireCapsuleCount, capsuleCount);
+        }
+    }
+    destroy() {
+        this.wireSphereBuffer.destroy();
+        this.wireBoxBuffer.destroy();
+        this.wireCapsuleBuffer.destroy();
+        this.solidSphereBuffer.destroy();
+        this.solidBoxBuffer.destroy();
+        this.solidCapsuleBuffer.destroy();
+        this.instanceBuffer.destroy();
+    }
+}
+// ── Geometry builders ─────────────────────────────────────────────────────────
+// Each vertex is vec4(unitPos.xyz, axialAnchor) packed as 4 floats.
+function buildSphereWireGeometry() {
+    const segs = 32;
+    const out = new Float32Array(3 * segs * 2 * 4); // 3 great circles
+    let p = 0;
+    for (let plane = 0; plane < 3; plane++) {
+        for (let i = 0; i < segs; i++) {
+            const a0 = (i / segs) * Math.PI * 2;
+            const a1 = ((i + 1) / segs) * Math.PI * 2;
+            const c0 = Math.cos(a0), s0 = Math.sin(a0);
+            const c1 = Math.cos(a1), s1 = Math.sin(a1);
+            let p0x = 0, p0y = 0, p0z = 0;
+            let p1x = 0, p1y = 0, p1z = 0;
+            if (plane === 0) {
+                p0x = c0;
+                p0y = s0;
+                p1x = c1;
+                p1y = s1;
+            }
+            else if (plane === 1) {
+                p0x = c0;
+                p0z = s0;
+                p1x = c1;
+                p1z = s1;
+            }
+            else {
+                p0y = c0;
+                p0z = s0;
+                p1y = c1;
+                p1z = s1;
+            }
+            out[p++] = p0x;
+            out[p++] = p0y;
+            out[p++] = p0z;
+            out[p++] = 0;
+            out[p++] = p1x;
+            out[p++] = p1y;
+            out[p++] = p1z;
+            out[p++] = 0;
+        }
+    }
+    return out;
+}
+function buildBoxWireGeometry() {
+    const edges = [
+        // 4 along X
+        [-1, -1, -1, +1, -1, -1], [-1, -1, +1, +1, -1, +1],
+        [-1, +1, -1, +1, +1, -1], [-1, +1, +1, +1, +1, +1],
+        // 4 along Y
+        [-1, -1, -1, -1, +1, -1], [+1, -1, -1, +1, +1, -1],
+        [-1, -1, +1, -1, +1, +1], [+1, -1, +1, +1, +1, +1],
+        // 4 along Z
+        [-1, -1, -1, -1, -1, +1], [+1, -1, -1, +1, -1, +1],
+        [-1, +1, -1, -1, +1, +1], [+1, +1, -1, +1, +1, +1],
+    ];
+    const out = new Float32Array(edges.length * 2 * 4);
+    let p = 0;
+    for (const e of edges) {
+        out[p++] = e[0];
+        out[p++] = e[1];
+        out[p++] = e[2];
+        out[p++] = 0;
+        out[p++] = e[3];
+        out[p++] = e[4];
+        out[p++] = e[5];
+        out[p++] = 0;
+    }
+    return out;
+}
+function buildCapsuleWireGeometry() {
+    const ringSegs = 32;
+    const arcSegs = 16;
+    // 2 cap rings + 4 hemisphere arcs + 4 cylinder verticals
+    const lineCount = ringSegs * 2 + arcSegs * 4 + 4;
+    const out = new Float32Array(lineCount * 2 * 4);
+    let p = 0;
+    const push = (x, y, z, axial) => {
+        out[p++] = x;
+        out[p++] = y;
+        out[p++] = z;
+        out[p++] = axial;
+    };
+    // Top ring (axial=+1) in XZ plane
+    for (let i = 0; i < ringSegs; i++) {
+        const a0 = (i / ringSegs) * Math.PI * 2;
+        const a1 = ((i + 1) / ringSegs) * Math.PI * 2;
+        push(Math.cos(a0), 0, Math.sin(a0), +1);
+        push(Math.cos(a1), 0, Math.sin(a1), +1);
+    }
+    // Bottom ring (axial=-1)
+    for (let i = 0; i < ringSegs; i++) {
+        const a0 = (i / ringSegs) * Math.PI * 2;
+        const a1 = ((i + 1) / ringSegs) * Math.PI * 2;
+        push(Math.cos(a0), 0, Math.sin(a0), -1);
+        push(Math.cos(a1), 0, Math.sin(a1), -1);
+    }
+    // Top cap arcs in XY and YZ planes (θ ∈ [0, π], pos = (cosθ, sinθ, 0) etc.)
+    for (let i = 0; i < arcSegs; i++) {
+        const t0 = (i / arcSegs) * Math.PI;
+        const t1 = ((i + 1) / arcSegs) * Math.PI;
+        push(Math.cos(t0), Math.sin(t0), 0, +1);
+        push(Math.cos(t1), Math.sin(t1), 0, +1);
+    }
+    for (let i = 0; i < arcSegs; i++) {
+        const t0 = (i / arcSegs) * Math.PI;
+        const t1 = ((i + 1) / arcSegs) * Math.PI;
+        push(0, Math.sin(t0), Math.cos(t0), +1);
+        push(0, Math.sin(t1), Math.cos(t1), +1);
+    }
+    // Bottom cap arcs
+    for (let i = 0; i < arcSegs; i++) {
+        const t0 = (i / arcSegs) * Math.PI;
+        const t1 = ((i + 1) / arcSegs) * Math.PI;
+        push(Math.cos(t0), -Math.sin(t0), 0, -1);
+        push(Math.cos(t1), -Math.sin(t1), 0, -1);
+    }
+    for (let i = 0; i < arcSegs; i++) {
+        const t0 = (i / arcSegs) * Math.PI;
+        const t1 = ((i + 1) / arcSegs) * Math.PI;
+        push(0, -Math.sin(t0), Math.cos(t0), -1);
+        push(0, -Math.sin(t1), Math.cos(t1), -1);
+    }
+    // 4 cylinder verticals: bottom rim (axial=-1) → top rim (+1) at fixed θ
+    push(+1, 0, 0, -1);
+    push(+1, 0, 0, +1);
+    push(-1, 0, 0, -1);
+    push(-1, 0, 0, +1);
+    push(0, 0, +1, -1);
+    push(0, 0, +1, +1);
+    push(0, 0, -1, -1);
+    push(0, 0, -1, +1);
+    return out;
+}
+// ── Solid (triangle-list) geometry builders ─────────────────────────────────
+// Each vertex is vec4(unitPos.xyz, axialAnchor) — same layout as wireframe.
+// UV sphere — stacks × slices quads, each split into 2 triangles. Polar quads
+// degenerate to triangles, which the GPU silently drops.
+function buildSphereSolidGeometry() {
+    const stacks = 12;
+    const slices = 18;
+    const out = new Float32Array(stacks * slices * 6 * 4);
+    let p = 0;
+    const vert = (phi, theta) => {
+        out[p++] = Math.cos(phi) * Math.cos(theta);
+        out[p++] = Math.sin(phi);
+        out[p++] = Math.cos(phi) * Math.sin(theta);
+        out[p++] = 0;
+    };
+    for (let s = 0; s < stacks; s++) {
+        const phi0 = -Math.PI / 2 + (s / stacks) * Math.PI;
+        const phi1 = -Math.PI / 2 + ((s + 1) / stacks) * Math.PI;
+        for (let l = 0; l < slices; l++) {
+            const th0 = (l / slices) * Math.PI * 2;
+            const th1 = ((l + 1) / slices) * Math.PI * 2;
+            vert(phi0, th0);
+            vert(phi1, th0);
+            vert(phi1, th1);
+            vert(phi0, th0);
+            vert(phi1, th1);
+            vert(phi0, th1);
+        }
+    }
+    return out;
+}
+// 6 cube faces × 2 triangles × 3 verts = 36 verts.
+function buildBoxSolidGeometry() {
+    const faces = [
+        // +X face
+        [+1, -1, -1, +1, +1, -1, +1, +1, +1, +1, -1, +1],
+        // -X face
+        [-1, -1, -1, -1, -1, +1, -1, +1, +1, -1, +1, -1],
+        // +Y face
+        [-1, +1, -1, -1, +1, +1, +1, +1, +1, +1, +1, -1],
+        // -Y face
+        [-1, -1, -1, +1, -1, -1, +1, -1, +1, -1, -1, +1],
+        // +Z face
+        [-1, -1, +1, +1, -1, +1, +1, +1, +1, -1, +1, +1],
+        // -Z face
+        [-1, -1, -1, -1, +1, -1, +1, +1, -1, +1, -1, -1],
+    ];
+    const out = new Float32Array(faces.length * 6 * 4);
+    let p = 0;
+    const v = (x, y, z) => {
+        out[p++] = x;
+        out[p++] = y;
+        out[p++] = z;
+        out[p++] = 0;
+    };
+    for (const f of faces) {
+        // f = [a, b, c, d] as 4 corners; emit tris (a,b,c) (a,c,d)
+        v(f[0], f[1], f[2]);
+        v(f[3], f[4], f[5]);
+        v(f[6], f[7], f[8]);
+        v(f[0], f[1], f[2]);
+        v(f[6], f[7], f[8]);
+        v(f[9], f[10], f[11]);
+    }
+    return out;
+}
+// Capsule: two hemispheres at axial=±1 + cylinder side connecting their equators.
+// Vertex shader does: world.y = unit.y * radius + halfHeight * axial.
+function buildCapsuleSolidGeometry() {
+    const slices = 18;
+    const capStacks = 6;
+    const cylTris = slices * 2; // 1 stack of quads → 2 tris/slice
+    const capTris = capStacks * slices * 2;
+    const totalVerts = (cylTris + capTris * 2) * 3;
+    const out = new Float32Array(totalVerts * 4);
+    let p = 0;
+    const v = (x, y, z, axial) => {
+        out[p++] = x;
+        out[p++] = y;
+        out[p++] = z;
+        out[p++] = axial;
+    };
+    // Cylinder side: two rings at axial=±1, both at unit y=0.
+    for (let l = 0; l < slices; l++) {
+        const th0 = (l / slices) * Math.PI * 2;
+        const th1 = ((l + 1) / slices) * Math.PI * 2;
+        const c0 = Math.cos(th0), s0 = Math.sin(th0);
+        const c1 = Math.cos(th1), s1 = Math.sin(th1);
+        // bottom-left, top-left, top-right
+        v(c0, 0, s0, -1);
+        v(c0, 0, s0, +1);
+        v(c1, 0, s1, +1);
+        // bottom-left, top-right, bottom-right
+        v(c0, 0, s0, -1);
+        v(c1, 0, s1, +1);
+        v(c1, 0, s1, -1);
+    }
+    // Top hemisphere (axial=+1): φ ∈ [0, π/2], pos = (cosφ cosθ, sinφ, cosφ sinθ).
+    for (let s = 0; s < capStacks; s++) {
+        const ph0 = (s / capStacks) * (Math.PI / 2);
+        const ph1 = ((s + 1) / capStacks) * (Math.PI / 2);
+        for (let l = 0; l < slices; l++) {
+            const th0 = (l / slices) * Math.PI * 2;
+            const th1 = ((l + 1) / slices) * Math.PI * 2;
+            const a = (ph, th) => [
+                Math.cos(ph) * Math.cos(th), Math.sin(ph), Math.cos(ph) * Math.sin(th),
+            ];
+            const p00 = a(ph0, th0), p10 = a(ph1, th0), p11 = a(ph1, th1), p01 = a(ph0, th1);
+            v(p00[0], p00[1], p00[2], +1);
+            v(p10[0], p10[1], p10[2], +1);
+            v(p11[0], p11[1], p11[2], +1);
+            v(p00[0], p00[1], p00[2], +1);
+            v(p11[0], p11[1], p11[2], +1);
+            v(p01[0], p01[1], p01[2], +1);
+        }
+    }
+    // Bottom hemisphere (axial=-1): same but y = -sinφ.
+    for (let s = 0; s < capStacks; s++) {
+        const ph0 = (s / capStacks) * (Math.PI / 2);
+        const ph1 = ((s + 1) / capStacks) * (Math.PI / 2);
+        for (let l = 0; l < slices; l++) {
+            const th0 = (l / slices) * Math.PI * 2;
+            const th1 = ((l + 1) / slices) * Math.PI * 2;
+            const a = (ph, th) => [
+                Math.cos(ph) * Math.cos(th), -Math.sin(ph), Math.cos(ph) * Math.sin(th),
+            ];
+            const p00 = a(ph0, th0), p10 = a(ph1, th0), p11 = a(ph1, th1), p01 = a(ph0, th1);
+            v(p00[0], p00[1], p00[2], -1);
+            v(p11[0], p11[1], p11[2], -1);
+            v(p10[0], p10[1], p10[2], -1);
+            v(p00[0], p00[1], p00[2], -1);
+            v(p01[0], p01[1], p01[2], -1);
+            v(p11[0], p11[1], p11[2], -1);
+        }
+    }
+    return out;
+}

package/dist/shaders/passes/composite.d.ts

@@ -1,2 +1,2 @@
-export declare const COMPOSITE_SHADER_WGSL = "\n// Pipeline-override constant: the engine creates two composite pipelines, one\n// with APPLY_GAMMA=false (gamma=1 fast path) and one with APPLY_GAMMA=true.\n// The 'if (APPLY_GAMMA)' below is resolved at pipeline-compile time \u2014 the\n// dead branch is dropped by the shader compiler (no runtime branch, no pow\n// invocation on Safari's Metal backend in the common case).\noverride APPLY_GAMMA: bool = true;\n\n@group(0) @binding(0) var hdrTex: texture_2d<f32>;\n@group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)\n@group(0) @binding(2) var bloomSamp: sampler;\n@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 2>;\n// Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).\n// .g = accumulated canvas alpha (what hdr.a carried before the HDR format\n// became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then\n// re-premultiply the tonemapped color for output so the premultiplied canvas\n// alphaMode composites the WebGPU surface over the page background correctly.\n@group(0) @binding(4) var maskTex: texture_2d<f32>;\n// Filmic tone curve baked to a WIDTH\u00D71 r16float LUT (bakeFilmicLut on the CPU side).\n// Domain: log2(linear) mapped to [0,13]. Replaces the old array<f32,14> that was indexed\n// by a runtime u32 (a Metal-backend smell \u2014 dynamic local-array indexing lowers to a\n// per-invocation copy/switch) and interpolated piecewise-linearly (C0, so segment slope\n// discontinuities showed as Mach bands in smooth skin/shadow gradients). The LUT is a\n// monotone-cubic (Fritsch\u2013Carlson) fit through the same 14 anchors \u2014 same values, C1\n// continuity kills the banding \u2014 sampled with hardware linear filtering.\n@group(0) @binding(5) var filmicLut: texture_2d<f32>;\n// viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)\n// invGamma = 1/gamma precomputed on CPU \u2014 avoids a per-pixel divide.\n\n// Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).\nconst FILMIC_LUT_W: f32 = 256.0;\n\nfn filmic(x: f32) -> f32 {\n  // Reference checkpoints (Blender 3.6 Filmic MHC, sobotka/filmic-blender\n  // look_medium-high-contrast.spi1d): linear 0.18 \u2192 ~0.395, linear 1.0 \u2192 ~0.83.\n  // NOTE: version-pinned to Blender 3.6 \u2014 4.x defaults to AgX, not Filmic.\n  let t = clamp(log2(max(x, 1e-10)) + 10.0, 0.0, 13.0);\n  // Map t\u2208[0,13] to the texel-center of baked sample j = t\u00B7(W-1)/13.\n  let u = (t * (FILMIC_LUT_W - 1.0) / 13.0 + 0.5) / FILMIC_LUT_W;\n  // textureSampleLevel (explicit LOD, no derivatives) is legal in non-uniform flow.\n  return textureSampleLevel(filmicLut, bloomSamp, vec2f(u, 0.5), 0.0).r;\n}\n\n@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {\n  let x = f32((vi & 1u) << 2u) - 1.0;\n  let y = f32((vi & 2u) << 1u) - 1.0;\n  return vec4f(x, y, 0.0, 1.0);\n}\n\n@fragment fn fs(@builtin(position) fragCoord: vec4f) -> @location(0) vec4f {\n  let coord = vec2<i32>(fragCoord.xy);\n  let hdr = textureLoad(hdrTex, coord, 0);\n  let alpha = textureLoad(maskTex, coord, 0).g;\n  let a = max(alpha, 1e-6);\n  let straight = hdr.rgb / a;\n  let fullSz = vec2f(textureDimensions(hdrTex));\n  // Bloom is at half-res (pyramid mip 0). Sampler interpolates back to full-res UVs.\n  // fragCoord.xy is already at pixel center (e.g. 0.5, 0.5 for first pixel).\n  let bloomUv = fragCoord.xy / max(fullSz, vec2f(1.0));\n  let tint = viewU[1].xyz;\n  let intensity = viewU[1].w;\n  let bloom = textureSampleLevel(bloomTex, bloomSamp, bloomUv, 0.0).rgb * tint * intensity;\n  let combined = straight + bloom;\n  let exposed = combined * exp2(viewU[0].x);\n  let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));\n  var disp = max(tm, vec3f(0.0));\n  if (APPLY_GAMMA) {\n    disp = pow(disp, vec3f(viewU[0].y));\n  }\n  return vec4f(disp * alpha, alpha);\n}\n";
+export declare const COMPOSITE_SHADER_WGSL = "\n// Pipeline-override constant: the engine creates two composite pipelines, one\n// with APPLY_GAMMA=false (gamma=1 fast path) and one with APPLY_GAMMA=true.\n// The 'if (APPLY_GAMMA)' below is resolved at pipeline-compile time \u2014 the\n// dead branch is dropped by the shader compiler (no runtime branch, no pow\n// invocation on Safari's Metal backend in the common case).\noverride APPLY_GAMMA: bool = true;\n\n@group(0) @binding(0) var hdrTex: texture_2d<f32>;\n@group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)\n@group(0) @binding(2) var bloomSamp: sampler;\n@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 6>;\n// Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).\n// .g = accumulated canvas alpha (what hdr.a carried before the HDR format\n// became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then\n// re-premultiply the tonemapped color for output so the premultiplied canvas\n// alphaMode composites the WebGPU surface over the page background correctly.\n@group(0) @binding(4) var maskTex: texture_2d<f32>;\n// Filmic tone curve baked to a WIDTH\u00D71 r16float LUT (bakeFilmicLut on the CPU side).\n// Domain: log2(linear) mapped to [0,13]. Replaces the old array<f32,14> that was indexed\n// by a runtime u32 (a Metal-backend smell \u2014 dynamic local-array indexing lowers to a\n// per-invocation copy/switch) and interpolated piecewise-linearly (C0, so segment slope\n// discontinuities showed as Mach bands in smooth skin/shadow gradients). The LUT is a\n// monotone-cubic (Fritsch\u2013Carlson) fit through the same 14 anchors \u2014 same values, C1\n// continuity kills the banding \u2014 sampled with hardware linear filtering.\n@group(0) @binding(5) var filmicLut: texture_2d<f32>;\n// viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)\n// viewU[2] = (background.rgb, mode) \u2014 display-space sRGB, composited UNDER the\n//            scene post-tonemap. mode: 0 transparent (DOM shows), 1 solid color,\n//            2 = 360 equirect skybox sampled by view ray.\n// viewU[3] = (camera right, tanHalfFov\u00B7aspect); viewU[4] = (camera up, tanHalfFov);\n// viewU[5] = (camera forward, _) \u2014 refreshed per frame while the skybox is active.\n// invGamma = 1/gamma precomputed on CPU \u2014 avoids a per-pixel divide.\n@group(0) @binding(6) var bgEquirect: texture_2d<f32>;\n\n// Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).\nconst FILMIC_LUT_W: f32 = 256.0;\n\nfn filmic(x: f32) -> f32 {\n  // Reference checkpoints (Blender 3.6 Filmic MHC, sobotka/filmic-blender\n  // look_medium-high-contrast.spi1d): linear 0.18 \u2192 ~0.395, linear 1.0 \u2192 ~0.83.\n  // NOTE: version-pinned to Blender 3.6 \u2014 4.x defaults to AgX, not Filmic.\n  let t = clamp(log2(max(x, 1e-10)) + 10.0, 0.0, 13.0);\n  // Map t\u2208[0,13] to the texel-center of baked sample j = t\u00B7(W-1)/13.\n  let u = (t * (FILMIC_LUT_W - 1.0) / 13.0 + 0.5) / FILMIC_LUT_W;\n  // textureSampleLevel (explicit LOD, no derivatives) is legal in non-uniform flow.\n  return textureSampleLevel(filmicLut, bloomSamp, vec2f(u, 0.5), 0.0).r;\n}\n\n@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {\n  let x = f32((vi & 1u) << 2u) - 1.0;\n  let y = f32((vi & 2u) << 1u) - 1.0;\n  return vec4f(x, y, 0.0, 1.0);\n}\n\n@fragment fn fs(@builtin(position) fragCoord: vec4f) -> @location(0) vec4f {\n  let coord = vec2<i32>(fragCoord.xy);\n  let hdr = textureLoad(hdrTex, coord, 0);\n  let alpha = textureLoad(maskTex, coord, 0).g;\n  let a = max(alpha, 1e-6);\n  let straight = hdr.rgb / a;\n  let fullSz = vec2f(textureDimensions(hdrTex));\n  // Bloom is at half-res (pyramid mip 0). Sampler interpolates back to full-res UVs.\n  // fragCoord.xy is already at pixel center (e.g. 0.5, 0.5 for first pixel).\n  let bloomUv = fragCoord.xy / max(fullSz, vec2f(1.0));\n  let tint = viewU[1].xyz;\n  let intensity = viewU[1].w;\n  let bloom = textureSampleLevel(bloomTex, bloomSamp, bloomUv, 0.0).rgb * tint * intensity;\n  let combined = straight + bloom;\n  let exposed = combined * exp2(viewU[0].x);\n  let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));\n  var disp = max(tm, vec3f(0.0));\n  if (APPLY_GAMMA) {\n    disp = pow(disp, vec3f(viewU[0].y));\n  }\n  // Composite over the background in display space (premultiplied out).\n  let bg = viewU[2];\n  var bgRgb = bg.rgb;\n  var bgA = select(0.0, 1.0, bg.w > 0.5);\n  if (bg.w > 1.5) {\n    // 360 equirect: rebuild this pixel's world-space view ray from the camera\n    // basis, then latitude/longitude-map into the panorama. The dome sits at\n    // infinity (no parallax) \u2014 PhotoDome-style, display-only.\n    let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.y / fullSz.y * 2.0);\n    let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);\n    // LH world (+Z forward): longitude = atan2(x, z), Babylon-PhotoDome convention.\n    let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2\u03C0)\n    let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/\u03C0\n    bgRgb = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;\n  }\n  return vec4f(disp * alpha + bgRgb * bgA * (1.0 - alpha), alpha + bgA * (1.0 - alpha));\n}\n";
 //# sourceMappingURL=composite.d.ts.map

package/dist/shaders/passes/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,qBAAqB,s0HAuEjC,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,qBAAqB,yvKA4FjC,CAAA"}

package/dist/shaders/passes/composite.js

@@ -11,7 +11,7 @@ override APPLY_GAMMA: bool = true;
 @group(0) @binding(0) var hdrTex: texture_2d<f32>;
 @group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)
 @group(0) @binding(2) var bloomSamp: sampler;
-@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 2>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 6>;
 // Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).
 // .g = accumulated canvas alpha (what hdr.a carried before the HDR format
 // became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then
@@ -27,7 +27,13 @@ override APPLY_GAMMA: bool = true;
 // continuity kills the banding — sampled with hardware linear filtering.
 @group(0) @binding(5) var filmicLut: texture_2d<f32>;
 // viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)
+// viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
+//            scene post-tonemap. mode: 0 transparent (DOM shows), 1 solid color,
+//            2 = 360 equirect skybox sampled by view ray.
+// viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
+// viewU[5] = (camera forward, _) — refreshed per frame while the skybox is active.
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
+@group(0) @binding(6) var bgEquirect: texture_2d<f32>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
@@ -69,6 +75,21 @@ fn filmic(x: f32) -> f32 {
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }
-  return vec4f(disp * alpha, alpha);
+  // Composite over the background in display space (premultiplied out).
+  let bg = viewU[2];
+  var bgRgb = bg.rgb;
+  var bgA = select(0.0, 1.0, bg.w > 0.5);
+  if (bg.w > 1.5) {
+    // 360 equirect: rebuild this pixel's world-space view ray from the camera
+    // basis, then latitude/longitude-map into the panorama. The dome sits at
+    // infinity (no parallax) — PhotoDome-style, display-only.
+    let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.y / fullSz.y * 2.0);
+    let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);
+    // LH world (+Z forward): longitude = atan2(x, z), Babylon-PhotoDome convention.
+    let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2π)
+    let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/π
+    bgRgb = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;
+  }
+  return vec4f(disp * alpha + bgRgb * bgA * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
 }
 `;

package/dist/shaders/passes/ground.d.ts

@@ -1,2 +1,2 @@
-export declare const GROUND_SHADOW_SHADER_WGSL = "\nstruct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };\nstruct Light { direction: vec4f, color: vec4f, };\nstruct LightUniforms { ambientColor: vec4f, lights: array<Light, 4>, };\nstruct GroundShadowMat {\n  diffuseColor: vec3f, fadeStart: f32,\n  fadeEnd: f32, shadowStrength: f32, pcfTexel: f32, gridSpacing: f32,\n  gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, _pad: f32,\n  gridLineColor: vec3f, _pad2: f32,\n};\nstruct LightVP { viewProj: mat4x4f, };\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> light: LightUniforms;\n@group(0) @binding(2) var shadowMap: texture_depth_2d;\n@group(0) @binding(3) var shadowSampler: sampler_comparison;\n@group(0) @binding(4) var<uniform> material: GroundShadowMat;\n@group(0) @binding(5) var<uniform> lightVP: LightVP;\n\nfn hash2(p: vec2f) -> f32 {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);\n  p3 += dot(p3, vec3f(p3.y + 33.33, p3.z + 33.33, p3.x + 33.33));\n  return fract((p3.x + p3.y) * p3.z);\n}\nfn valueNoise(p: vec2f) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hash2(i), hash2(i + vec2f(1.0, 0.0)), u.x),\n             mix(hash2(i + vec2f(0.0, 1.0)), hash2(i + vec2f(1.0, 1.0)), u.x), u.y);\n}\nfn fbmNoise(p: vec2f) -> f32 {\n  var v = 0.0;\n  var a = 0.5;\n  var pp = p;\n  for (var i = 0; i < 4; i++) {\n    v += a * valueNoise(pp);\n    pp *= 2.0;\n    a *= 0.5;\n  }\n  return v;\n}\n\nstruct VO { @builtin(position) position: vec4f, @location(0) worldPos: vec3f, @location(1) normal: vec3f, };\n@vertex fn vs(@location(0) position: vec3f, @location(1) normal: vec3f, @location(2) uv: vec2f) -> VO {\n  var o: VO; o.worldPos = position; o.normal = normal;\n  o.position = camera.projection * camera.view * vec4f(position, 1.0); return o;\n}\nstruct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };\n@fragment fn fs(i: VO) -> FSOut {\n  let n = normalize(i.normal);\n  let centerDist = length(i.worldPos.xz);\n  let edgeFade = 1.0 - smoothstep(0.0, 1.0, clamp((centerDist - material.fadeStart) / max(material.fadeEnd - material.fadeStart, 0.001), 0.0, 1.0));\n\n  let lclip = lightVP.viewProj * vec4f(i.worldPos, 1.0);\n  let ndc = lclip.xyz / max(lclip.w, 1e-6);\n  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);\n  let suv_c = clamp(suv, vec2f(0.02), vec2f(0.98));\n  let st = material.pcfTexel;\n  let compareZ = ndc.z - 0.0035;\n  var vis = 0.0;\n  for (var y = -2; y <= 2; y++) {\n    for (var x = -2; x <= 2; x++) {\n      vis += textureSampleCompare(shadowMap, shadowSampler, suv_c + vec2f(f32(x), f32(y)) * st, compareZ);\n    }\n  }\n  vis *= 0.04;\n\n  // Frosted/matte micro-texture\n  let noiseVal = fbmNoise(i.worldPos.xz * 3.0);\n  let noiseTint = 1.0 + (noiseVal - 0.5) * material.noiseStrength;\n\n  // Grid lines \u2014 anti-aliased via screen-space derivatives\n  let gp = i.worldPos.xz / material.gridSpacing;\n  let gridFrac = abs(fract(gp - 0.5) - 0.5);\n  let gridDeriv = fwidth(gp);\n  let halfLine = material.gridLineWidth * 0.5;\n  let gridLine = 1.0 - min(\n    smoothstep(halfLine - gridDeriv.x, halfLine + gridDeriv.x, gridFrac.x),\n    smoothstep(halfLine - gridDeriv.y, halfLine + gridDeriv.y, gridFrac.y)\n  );\n  let sun = light.ambientColor.xyz + light.lights[0].color.xyz * light.lights[0].color.w * max(dot(n, -light.lights[0].direction.xyz), 0.0);\n  let dark = (1.0 - vis) * material.shadowStrength;\n  var baseColor = material.diffuseColor * sun * (1.0 - dark * 0.65);\n  baseColor *= noiseTint;\n  let finalColor = mix(baseColor, material.gridLineColor, gridLine * material.gridLineOpacity * edgeFade);\n  var out: FSOut;\n  out.color = vec4f(finalColor * edgeFade, edgeFade);\n  // mask.r = 0: ground never contributes to bloom. mask.g = 1.0 with src.a =\n  // edgeFade turns the aux blend into alpha-over, so the drawable alpha fades\n  // from edgeFade at the center to 0 at the radial edge \u2014 letting the page\n  // background show through under the premultiplied canvas alphaMode.\n  out.mask = vec4f(0.0, 1.0, 0.0, edgeFade);\n  return out;\n}\n";
+export declare const GROUND_SHADOW_SHADER_WGSL = "\nstruct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };\nstruct Light { direction: vec4f, color: vec4f, };\nstruct LightUniforms { ambientColor: vec4f, lights: array<Light, 4>, };\nstruct GroundShadowMat {\n  diffuseColor: vec3f, fadeStart: f32,\n  fadeEnd: f32, shadowStrength: f32, pcfTexel: f32, gridSpacing: f32,\n  gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, opacity: f32,\n  gridLineColor: vec3f, _pad2: f32,\n};\nstruct LightVP { viewProj: mat4x4f, };\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> light: LightUniforms;\n@group(0) @binding(2) var shadowMap: texture_depth_2d;\n@group(0) @binding(3) var shadowSampler: sampler_comparison;\n@group(0) @binding(4) var<uniform> material: GroundShadowMat;\n@group(0) @binding(5) var<uniform> lightVP: LightVP;\n\nfn hash2(p: vec2f) -> f32 {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);\n  p3 += dot(p3, vec3f(p3.y + 33.33, p3.z + 33.33, p3.x + 33.33));\n  return fract((p3.x + p3.y) * p3.z);\n}\nfn valueNoise(p: vec2f) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hash2(i), hash2(i + vec2f(1.0, 0.0)), u.x),\n             mix(hash2(i + vec2f(0.0, 1.0)), hash2(i + vec2f(1.0, 1.0)), u.x), u.y);\n}\nfn fbmNoise(p: vec2f) -> f32 {\n  var v = 0.0;\n  var a = 0.5;\n  var pp = p;\n  for (var i = 0; i < 4; i++) {\n    v += a * valueNoise(pp);\n    pp *= 2.0;\n    a *= 0.5;\n  }\n  return v;\n}\n\nstruct VO { @builtin(position) position: vec4f, @location(0) worldPos: vec3f, @location(1) normal: vec3f, };\n@vertex fn vs(@location(0) position: vec3f, @location(1) normal: vec3f, @location(2) uv: vec2f) -> VO {\n  var o: VO; o.worldPos = position; o.normal = normal;\n  o.position = camera.projection * camera.view * vec4f(position, 1.0); return o;\n}\nstruct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };\n@fragment fn fs(i: VO) -> FSOut {\n  let n = normalize(i.normal);\n  let centerDist = length(i.worldPos.xz);\n  let edgeFade = 1.0 - smoothstep(0.0, 1.0, clamp((centerDist - material.fadeStart) / max(material.fadeEnd - material.fadeStart, 0.001), 0.0, 1.0));\n\n  let lclip = lightVP.viewProj * vec4f(i.worldPos, 1.0);\n  let ndc = lclip.xyz / max(lclip.w, 1e-6);\n  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);\n  let suv_c = clamp(suv, vec2f(0.02), vec2f(0.98));\n  let st = material.pcfTexel;\n  let compareZ = ndc.z - 0.0035;\n  var vis = 0.0;\n  for (var y = -2; y <= 2; y++) {\n    for (var x = -2; x <= 2; x++) {\n      vis += textureSampleCompare(shadowMap, shadowSampler, suv_c + vec2f(f32(x), f32(y)) * st, compareZ);\n    }\n  }\n  vis *= 0.04;\n\n  // Frosted/matte micro-texture\n  let noiseVal = fbmNoise(i.worldPos.xz * 3.0);\n  let noiseTint = 1.0 + (noiseVal - 0.5) * material.noiseStrength;\n\n  // Grid lines \u2014 anti-aliased via screen-space derivatives\n  let gp = i.worldPos.xz / material.gridSpacing;\n  let gridFrac = abs(fract(gp - 0.5) - 0.5);\n  let gridDeriv = fwidth(gp);\n  let halfLine = material.gridLineWidth * 0.5;\n  let gridLine = 1.0 - min(\n    smoothstep(halfLine - gridDeriv.x, halfLine + gridDeriv.x, gridFrac.x),\n    smoothstep(halfLine - gridDeriv.y, halfLine + gridDeriv.y, gridFrac.y)\n  );\n  let sun = light.ambientColor.xyz + light.lights[0].color.xyz * light.lights[0].color.w * max(dot(n, -light.lights[0].direction.xyz), 0.0);\n  let dark = (1.0 - vis) * material.shadowStrength;\n  var baseColor = material.diffuseColor * sun * (1.0 - dark * 0.65);\n  baseColor *= noiseTint;\n  let finalColor = mix(baseColor, material.gridLineColor, gridLine * material.gridLineOpacity * edgeFade);\n  // Whole-ground opacity fades the SURFACE (color, grid) but the shadow stays \u2014\n  // as opacity drops, the received shadow becomes a translucent dark layer\n  // (Blender's Shadow Catcher), so models still feel grounded on a photo or\n  // 360 backdrop. At opacity 1 this reduces exactly to the plain surface.\n  let surfA = edgeFade * material.opacity;\n  let catchA = dark * 0.65 * edgeFade * (1.0 - material.opacity);\n  let outA = surfA + catchA;\n  var out: FSOut;\n  out.color = vec4f(finalColor * surfA, outA);\n  // mask.r = 0: ground never contributes to bloom. mask.g = 1.0 with src.a =\n  // outA turns the aux blend into alpha-over, so the drawable alpha goes\n  // from outA at the center to 0 at the radial edge \u2014 letting the page\n  // background show through under the premultiplied canvas alphaMode.\n  out.mask = vec4f(0.0, 1.0, 0.0, outA);\n  return out;\n}\n";
 //# sourceMappingURL=ground.d.ts.map

package/dist/shaders/passes/ground.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB,ijIA8FrC,CAAA"}
+{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB,2+IAqGrC,CAAA"}

package/dist/shaders/passes/ground.js

@@ -7,7 +7,7 @@ struct LightUniforms { ambientColor: vec4f, lights: array<Light, 4>, };
 struct GroundShadowMat {
   diffuseColor: vec3f, fadeStart: f32,
   fadeEnd: f32, shadowStrength: f32, pcfTexel: f32, gridSpacing: f32,
-  gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, _pad: f32,
+  gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, opacity: f32,
   gridLineColor: vec3f, _pad2: f32,
 };
 struct LightVP { viewProj: mat4x4f, };
@@ -85,13 +85,20 @@ struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
   var baseColor = material.diffuseColor * sun * (1.0 - dark * 0.65);
   baseColor *= noiseTint;
   let finalColor = mix(baseColor, material.gridLineColor, gridLine * material.gridLineOpacity * edgeFade);
+  // Whole-ground opacity fades the SURFACE (color, grid) but the shadow stays —
+  // as opacity drops, the received shadow becomes a translucent dark layer
+  // (Blender's Shadow Catcher), so models still feel grounded on a photo or
+  // 360 backdrop. At opacity 1 this reduces exactly to the plain surface.
+  let surfA = edgeFade * material.opacity;
+  let catchA = dark * 0.65 * edgeFade * (1.0 - material.opacity);
+  let outA = surfA + catchA;
   var out: FSOut;
-  out.color = vec4f(finalColor * edgeFade, edgeFade);
+  out.color = vec4f(finalColor * surfA, outA);
   // mask.r = 0: ground never contributes to bloom. mask.g = 1.0 with src.a =
-  // edgeFade turns the aux blend into alpha-over, so the drawable alpha fades
-  // from edgeFade at the center to 0 at the radial edge — letting the page
+  // outA turns the aux blend into alpha-over, so the drawable alpha goes
+  // from outA at the center to 0 at the radial edge — letting the page
   // background show through under the premultiplied canvas alphaMode.
-  out.mask = vec4f(0.0, 1.0, 0.0, edgeFade);
+  out.mask = vec4f(0.0, 1.0, 0.0, outA);
   return out;
 }
 `;