reze-engine 0.55.0 → 0.55.1

package/dist/engine.js

@@ -1053,6 +1053,8 @@ export class Engine {
             contrast: DEFAULT_COLOR_GRADING.contrast,
             saturation: DEFAULT_COLOR_GRADING.saturation,
         };
+        /** Sensor grain: how much, and whether it moves. */
+        this.grain = { amount: 0, animated: true };
         /** Debug/diagnostic: skip every inverted-hull outline draw. */
         // OFF by default — the product aesthetic. Modern high-detail models read
         // better without hulls (babylon-mmd's own demos disable its outline renderer
@@ -1065,6 +1067,17 @@ export class Engine {
         /** When set, render resolution is pinned to this size instead of tracking the
          *  canvas's CSS size × devicePixelRatio (see setRenderSize). */
         this.fixedRenderSize = null;
+        // ── VMD camera track ──
+        // A dedicated camera VMD (target / rotation / distance / fov animated). Motion VMDs loaded
+        // via model.loadVmd never touch the camera — the camera shot is opt-in through here.
+        /** Whether a loaded camera track is allowed to drive (setCameraVmdEnabled).
+         *  Held separately from `camera.vmdDriven` because that flag now answers to
+         *  two sources, and a track switched off must stay off when the other one
+         *  releases the camera. */
+        this.cameraVmdEnabled = true;
+        /** A pose pushed in from outside — see setCameraPose. Reapplied every frame,
+         *  so it outranks the orbit AND a loaded track for as long as it is set. */
+        this.cameraPoseOverride = null;
         /** Per cascade: does its map currently hold nothing but the cleared far plane?
          *  Set by the cascade loop, which skips a cascade that is unwanted and already
          *  cleared rather than re-clearing it every frame. */
@@ -1400,6 +1413,30 @@ export class Engine {
             saturation: g.saturation,
         };
     }
+    /**
+     * Film grain over the rendered scene, 0–1.
+     *
+     * A property of a SENSOR, so it belongs to the camera rather than to any one
+     * subject, and it lands on what the engine drew and on nothing else — never on
+     * a background image or a backdrop video, which arrived with grain of their
+     * own and would be graded rather than matched by a second helping.
+     *
+     * `animated` false freezes it. A still photograph's grain does not move, and
+     * noise crawling over a frozen picture makes the rendering look more alive
+     * than the thing it is standing in.
+     *
+     * Costs one hash per pixel in a pass that already runs, and nothing at all at
+     * zero — the branch is on a uniform.
+     */
+    setFilmGrain(amount, animated = true) {
+        this.grain.amount = Math.min(Math.max(amount, 0), 1);
+        this.grain.animated = animated;
+        if (this.device && this.compositeUniformBuffer)
+            this.writeCompositeViewUniforms();
+    }
+    getFilmGrain() {
+        return this.grain;
+    }
     setViewTransformOptions(patch) {
         const v = this.viewTransform;
         if (patch.exposure !== undefined)
@@ -1442,8 +1479,11 @@ export class Engine {
         // compiler doesn't fold `pow(x, 1/g)` into identity when g=1, so also emit
         // a uniform branch that skips the pow entirely in the common case.
         u[1] = 1.0 / Math.max(v.gamma, 1e-4);
-        u[2] = 0.0;
-        u[3] = 0.0;
+        u[2] = this.grain.amount;
+        // The seed. Zero means STILL: a plate that is one photograph has grain that
+        // does not move, and CG noise crawling over a frozen picture makes the CG
+        // look more alive than the footage — the opposite of the point.
+        u[3] = this.grain.animated ? Math.floor(this.sceneClock * 24) % 1024 : 0;
         u[4] = b.color.x;
         u[5] = b.color.y;
         u[6] = b.color.z;
@@ -6323,21 +6363,60 @@ export class Engine {
         this.cameraFollowSmoothing = Math.max(0, smoothing ?? 0);
         this.cameraFollowSeeded = false;
     }
-    // ── VMD camera track ──
-    // A dedicated camera VMD (target / rotation / distance / fov animated). Motion VMDs loaded
-    // via model.loadVmd never touch the camera — the camera shot is opt-in through here.
+    /** The one place that decides who is holding the camera. An external pose
+     *  wins; a track drives when it is loaded and enabled; otherwise orbit. */
+    refreshCameraDrive() {
+        this.camera.setVmdDriven(this.cameraPoseOverride !== null || (this.cameraVmdEnabled && this.cameraAnimation !== null));
+    }
+    /**
+     * Aim the camera from outside — a solved match-move, a saved shot, a rig
+     * driving the view from the host's own clock.
+     *
+     * The exact partner of `getCameraPose`, and the same five channels: the shot
+     * as MMD states it, roll included. Orbit cannot express roll, so this is the
+     * only way a tilted camera reaches the engine.
+     *
+     * Reapplied every frame while set, which makes it authoritative rather than
+     * advisory — nothing the transport or a loaded track does moves it. Pass null
+     * to release, and whatever was driving before takes the camera back.
+     */
+    setCameraPose(pose) {
+        if (pose) {
+            // Copied, not held: a host reusing one object per frame is the normal
+            // shape of a track, and storing the reference would make the value we
+            // reapply depend on when the caller next touched theirs.
+            this.cameraPoseOverride = {
+                target: new Vec3(pose.target.x, pose.target.y, pose.target.z),
+                rotation: new Vec3(pose.rotation.x, pose.rotation.y, pose.rotation.z),
+                distance: pose.distance,
+                fov: pose.fov,
+            };
+        }
+        else {
+            this.cameraPoseOverride = null;
+        }
+        this.refreshCameraDrive();
+        if (this.cameraPoseOverride)
+            this.camera.setVmdPose(this.cameraPoseOverride);
+    }
+    /** The pose currently forced from outside, or null when nothing is. */
+    getCameraPoseOverride() {
+        return this.cameraPoseOverride;
+    }
     /** Load a camera VMD (dedicated camera file, or any VMD's camera block) and drive the shot
      *  from it. Default-on once a non-empty track loads; toggle with setCameraVmdEnabled. */
     async loadCameraVmd(url) {
         const frames = await VMDLoader.loadCamera(url);
         this.cameraAnimation = frames.length ? new CameraAnimation(frames) : null;
-        this.camera.setVmdDriven(this.cameraAnimation !== null);
+        this.cameraVmdEnabled = true;
+        this.refreshCameraDrive();
     }
     /** Load a camera VMD from an already-fetched buffer (e.g. a File the user dropped). */
     loadCameraVmdFromBuffer(buffer) {
         const frames = VMDLoader.loadCameraFromBuffer(buffer);
         this.cameraAnimation = frames.length ? new CameraAnimation(frames) : null;
-        this.camera.setVmdDriven(this.cameraAnimation !== null);
+        this.cameraVmdEnabled = true;
+        this.refreshCameraDrive();
     }
     /**
      * Drive the shot from camera keyframes built in JS — the camera's answer to
@@ -6354,7 +6433,8 @@ export class Engine {
      */
     loadCameraClip(frames) {
         this.cameraAnimation = frames.length ? new CameraAnimation([...frames]) : null;
-        this.camera.setVmdDriven(this.cameraAnimation !== null);
+        this.cameraVmdEnabled = true;
+        this.refreshCameraDrive();
     }
     /** The loaded camera track as editable keyframes, or [] with none loaded.
      *  Copies — mutating them does not reach the track being sampled. */
@@ -6372,7 +6452,8 @@ export class Engine {
     }
     /** Turn the loaded camera VMD on/off (falls back to orbit when off). No-op if none loaded. */
     setCameraVmdEnabled(enabled) {
-        this.camera.setVmdDriven(enabled && this.cameraAnimation !== null);
+        this.cameraVmdEnabled = enabled;
+        this.refreshCameraDrive();
         if (!enabled && this.cameraTargetModel) {
             // Follow resumes with a clean snap to bone + configured offset — one
             // predictable cut to the scene's framing, no easing from the shot.
@@ -6630,7 +6711,7 @@ export class Engine {
     /** Drop the loaded camera VMD and return to orbit control. */
     clearCameraVmd() {
         this.cameraAnimation = null;
-        this.camera.setVmdDriven(false);
+        this.refreshCameraDrive();
     }
     /**
      * THE TRANSPORT'S CLOCK — where the scene is in its own playback.
@@ -6673,6 +6754,28 @@ export class Engine {
     getCameraPosition() {
         return this.camera.getPosition();
     }
+    /**
+     * The live orbit, read in ONE call.
+     *
+     * A host that stores the shot has to be able to ask where the camera actually
+     * IS, because a drag on the canvas moves this and nothing else — and a
+     * document that never asks will happily write back the angle it last set,
+     * discarding whatever the person just did with the mouse. Reading the four
+     * separately invites a torn set across a frame boundary; this cannot tear.
+     *
+     * `target` is the orbit's own centre. While the engine is following a bone
+     * that point rides the bone, so a caller storing a FOLLOW offset must keep its
+     * own and take only the angles from here.
+     */
+    getCameraOrbit() {
+        const c = this.camera;
+        return {
+            alpha: c.alpha,
+            beta: c.beta,
+            distance: c.radius,
+            target: new Vec3(c.target.x, c.target.y, c.target.z),
+        };
+    }
     getCameraDistance() {
         return this.camera.radius;
     }
@@ -6691,6 +6794,21 @@ export class Engine {
     setCameraBeta(b) {
         this.camera.beta = b;
     }
+    /**
+     * Roll the orbiting shot, radians — the lean alpha and beta cannot state.
+     *
+     * Tips the up vector about the eye→target line, so the camera stays exactly
+     * where it was and keeps looking at exactly what it looked at. Everything the
+     * orbit does still works underneath it: following a bone, dragging, zooming.
+     *
+     * A camera VMD carries its own roll and ignores this while it drives.
+     */
+    setCameraRoll(r) {
+        this.camera.roll = r;
+    }
+    getCameraRoll() {
+        return this.camera.roll;
+    }
     /** Vertical field of view in radians (default π/4). While a camera VMD
      *  drives the view it animates fov itself; the orbit value set here is
      *  restored when the VMD releases the camera. */
@@ -6822,6 +6940,7 @@ export class Engine {
             opacity: 1.0,
             mirror: false,
             mirrorBlur: 0,
+            shadowSoftness: 0,
             ...options,
         };
         this.createGroundGeometry(opts.width, opts.height);
@@ -9015,7 +9134,7 @@ export class Engine {
         this.device.queue.writeBuffer(this.groundIndexBuffer, 0, indices);
     }
     createShadowGroundResources(opts) {
-        const { diffuseColor, fadeStart, fadeEnd, shadowStrength, gridSpacing, gridLineWidth, gridLineOpacity, gridLineColor, noiseStrength, opacity, mirror, mirrorBlur, } = opts;
+        const { diffuseColor, fadeStart, fadeEnd, shadowStrength, gridSpacing, gridLineWidth, gridLineOpacity, gridLineColor, noiseStrength, opacity, mirror, mirrorBlur, shadowSoftness, } = opts;
         // Shadow map is already created in setupPipelines()
         // 20 floats: 16 for the original block, then (mirrorBlur, pad, pad, pad)
         // keeping the uniform vec4-aligned.
@@ -9040,6 +9159,9 @@ export class Engine {
         this.groundMirror = gb[15];
         gb[16] = Math.min(Math.max(mirrorBlur, 0), 1);
         this.groundMirrorBlur = gb[16];
+        // gb[18] — shadow edge softness. Was padding; the shader reads it as the
+        // Vogel disk's radius, and 0 takes the sharp nine-tap path unchanged.
+        gb[18] = Math.min(Math.max(shadowSoftness, 0), 1);
         // gb[17] — does the FAR cascade hold anything?
         //
         // It holds something only when a stage is loaded; that is what it exists for
@@ -10200,15 +10322,65 @@ export class Engine {
         return new Vec3(x / w, y / w, z / w);
     }
     // World-space ray from camera through a canvas pixel. Uses WebGPU's NDC z ∈ [0,1].
+    /**
+     * Where a point on the canvas lands on a horizontal plane.
+     *
+     * `px,py` are canvas-relative pixels, top-left origin — what a pointer event
+     * gives you after subtracting the element's rect. Returns null when the ray
+     * cannot reach the plane: parallel to it, or pointing the other way, which is
+     * what a click on the sky above the horizon is.
+     *
+     * The one primitive a placement UI needs. Dragging a thing across the floor is
+     * otherwise three sliders in world units, which asks someone to guess numbers
+     * that have no visible relation to the picture they are looking at — and it
+     * throws away the property that makes pointing work at all: under perspective,
+     * moving something further away makes it smaller by exactly the right amount,
+     * so position and size stop being two controls to tune against each other.
+     */
+    groundPointAt(px, py, planeY = 0) {
+        const ray = this.buildMouseRay(px, py);
+        if (!ray)
+            return null;
+        // Parallel to the plane: no intersection, and a huge one is not an answer.
+        if (Math.abs(ray.dir.y) < 1e-6)
+            return null;
+        const t = (planeY - ray.origin.y) / ray.dir.y;
+        // Behind the camera — the plane is there, but not in this shot.
+        if (!(t > 0) || !isFinite(t))
+            return null;
+        return new Vec3(ray.origin.x + ray.dir.x * t, planeY, ray.origin.z + ray.dir.z * t);
+    }
+    /** Hand the pointer to something else — a placement drag, a gizmo, a host's own
+     *  overlay — so the orbit does not also act on it. */
+    setCameraInputLocked(locked) {
+        this.camera?.setInputLocked(locked);
+    }
     buildMouseRay(px, py) {
         if (!this.camera)
             return null;
         const width = this.canvas.clientWidth;
         const height = this.canvas.clientHeight;
-        if (width <= 0 || height <= 0)
+        if (width <= 0 || height <= 0 || this.canvas.width <= 0 || this.canvas.height <= 0)
             return null;
-        const ndcX = (px / width) * 2 - 1;
-        const ndcY = -((py / height) * 2 - 1);
+        // THE PICTURE, NOT THE ELEMENT.
+        //
+        // The projection's aspect comes from the DRAWING BUFFER, while a pointer
+        // arrives in the CSS box — and the two do not have to agree. The canvas is
+        // laid out `object-contain`, so whenever they differ the rendered image sits
+        // letterboxed inside the element with bars either side of it, and dividing
+        // by the element's own size lands the ray somewhere the picture is not.
+        // They disagree on every resize until the observer catches up, and
+        // permanently wherever a host frames the canvas to a shape of its own.
+        //
+        // So: work out where the image actually sits, and take the ray from that.
+        const bufAspect = this.canvas.width / this.canvas.height;
+        const boxAspect = width / height;
+        const imgW = bufAspect > boxAspect ? width : height * bufAspect;
+        const imgH = bufAspect > boxAspect ? width / bufAspect : height;
+        const ox = (width - imgW) / 2;
+        const oy = (height - imgH) / 2;
+        const ndcX = ((px - ox) / imgW) * 2 - 1;
+        const ndcY = -(((py - oy) / imgH) * 2 - 1);
         const view = this.camera.getViewMatrix();
         const proj = this.camera.getProjectionMatrix();
         const invVP = proj.multiply(view).inverse();
@@ -10491,8 +10663,14 @@ export class Engine {
                 }
             }
         }
-        // Drive the shot from the camera VMD (synced to the animated model's clock).
-        if (this.camera.vmdDriven && this.cameraAnimation) {
+        // Who holds the shot this frame. An external pose is a statement about
+        // where the camera IS, so it is reapplied rather than sampled — and it
+        // outranks a loaded track, which is scene data.
+        if (this.cameraPoseOverride) {
+            this.camera.setVmdPose(this.cameraPoseOverride);
+        }
+        else if (this.camera.vmdDriven && this.cameraAnimation) {
+            // Drive the shot from the camera VMD (synced to the animated model's clock).
             const pose = this.cameraAnimation.sample(this.transportTime());
             if (pose)
                 this.camera.setVmdPose(pose);
@@ -11724,6 +11902,12 @@ export class Engine {
             // clock is already per effect, which is the one that actually breaks
             // things (rzGridFrame()==0 is a grid's only chance to seed).
             u[24] = this.sceneClock - (this.effects[0]?.epochScene ?? 0);
+            // The grain's seed rides the same per-frame refresh, because it is the
+            // only thing that makes it move — a seed written once by its setter is a
+            // still pattern welded to the picture. On the SCENE clock like everything
+            // else here, so an export reproduces the editor exactly rather than
+            // scattering differently at whatever rate the encoder ran.
+            u[3] = this.grain.animated ? Math.floor((this.sceneClock * 24) % 1024) : 0;
             u[26] = this.canvas.width;
             u[27] = this.canvas.height;
             // Camera world position (viewU[10]) — the other half of bgWorldPos. It

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":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA6LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA4LD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAiFtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA6LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA6MD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAiFtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}

package/dist/shaders/passes/composite.js

@@ -109,7 +109,7 @@ override APPLY_GAMMA: bool = true;
 // monotone-cubic (Fritsch–Carlson) fit through the same 14 anchors — same values, C1
 // 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[0] = (exposure, invGamma, grain amount, grain seed);  viewU[1] = (tint.rgb, intensity)
 // viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
 //            scene post-tonemap. BASE-layer mode: 0 transparent (DOM shows),
 //            1 solid color, 2 = 360 equirect skybox sampled by view ray. A user
@@ -495,6 +495,23 @@ const COMPOSITE_BODY = /* wgsl */ `
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }
+  // ── Film grain, on the SCENE ONLY ─────────────────────────────────────────
+  //
+  // Applied here, before the background is composited under, so it rides on what
+  // the engine drew and nothing else. That placement is the whole point when the
+  // background is footage: the plate came off a real sensor and already carries
+  // its own grain, and a second helping over the top would grade the photograph
+  // rather than match it. A clean CG figure on a grainy plate is one of the
+  // loudest tells there is — the noise gives it away long before the geometry.
+  //
+  // Multiplicative and weighted toward the mid-tones, which is how film behaves:
+  // little grain in the blacks, and the highlights clip it off.
+  if (viewU[0].z > 0.0) {
+    let gp = fragCoord.xy + vec2f(viewU[0].w, viewU[0].w * 1.7);
+    let gn = fract(sin(dot(gp, vec2f(12.9898, 78.233))) * 43758.5453) - 0.5;
+    let glum = dot(disp, vec3f(0.2126, 0.7152, 0.0722));
+    disp = max(disp * (1.0 + gn * viewU[0].z * 4.0 * glum * (1.0 - glum)), vec3f(0.0));
+  }
   // Composite over the background in display space (premultiplied out). The
   // background is TWO layers: a base (transparent / solid color / 360 equirect)
   // and an optional user WGSL effect over-composited onto it.

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":"AAYA,wBAAgB,gBAAgB,IAAI,MAAM,CAkUzC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}
+{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAmEA,wBAAgB,gBAAgB,IAAI,MAAM,CA2TzC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}

package/dist/shaders/passes/ground.js

@@ -8,6 +8,59 @@ import { WORLD_AMBIENT_WGSL } from "../lights";
 // A FUNCTION, not a constant, since the id attachment is a device capability:
 // the struct this returns depends on what the probe at init found, and a string
 // baked at import time cannot know that. Called once, when the module is built.
+// How far the softest setting spreads the taps, in units of the sharp kernel's
+// own step, and how many taps carry that spread. Sixteen is what keeps a wide
+// disk reading as a penumbra instead of sixteen shadows.
+const SOFT_TAPS = 16;
+const SOFT_MAX_SPREAD = 14;
+/**
+ * PCF taps for one cascade, emitted per shadow map.
+ *
+ * At softness 0 this is the 3x3 box the ground has always used — same offsets,
+ * same weights, same result to the bit. Above it the taps spread over a Vogel
+ * disk whose radius IS the penumbra: an overcast sky throws no edge, and a
+ * razor-edged shadow under one is the loudest thing wrong in a composite.
+ *
+ * The branch is on a uniform, so a scene at softness 0 genuinely takes the
+ * nine-tap side rather than masking the wide one — the same reasoning the
+ * shadowStrength branch above it already documents.
+ *
+ * A string rather than a WGSL function because a texture is the one handle type
+ * this shader has never passed as a parameter, and the file is already a
+ * template that interpolates its constants.
+ *
+ * `acc` must already be declared and zeroed; the caller reads it back
+ * normalised, so there is no `/ 9.0` left at the call site.
+ */
+function pcfWgsl(map, uv, texel, z, acc, pad) {
+    const golden = 2.39996323;
+    return [
+        `if (material.shadowSoftness <= 0.0) {`,
+        `  let st = ${texel} * 2.0;`,
+        `  for (var y = -1; y <= 1; y++) {`,
+        `    for (var x = -1; x <= 1; x++) {`,
+        // ...Level, not the implicit-derivative form: identical on a single-mip
+        // shadow map, and legal inside a branch.
+        `      ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(f32(x), f32(y)) * st, ${z});`,
+        `    }`,
+        `  }`,
+        `  ${acc} *= ${1 / 9};`,
+        `} else {`,
+        `  let radius = ${texel} * 2.0 * (1.0 + material.shadowSoftness * ${SOFT_MAX_SPREAD}.0);`,
+        `  for (var s = 0; s < ${SOFT_TAPS}; s++) {`,
+        `    let fs = f32(s);`,
+        // sqrt of the index spaces the ring radii evenly by AREA; the golden angle
+        // keeps successive taps from lining up into spokes.
+        `    let r = sqrt((fs + 0.5) * ${1 / SOFT_TAPS});`,
+        `    let a = fs * ${golden} + rot;`,
+        `    ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(cos(a), sin(a)) * (r * radius), ${z});`,
+        `  }`,
+        `  ${acc} *= ${1 / SOFT_TAPS};`,
+        `}`,
+    ]
+        .map((l) => pad + l)
+        .join("\n");
+}
 export function groundShaderWgsl() {
     return /* wgsl */ `
 struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };
@@ -20,7 +73,7 @@ struct GroundShadowMat {
   gridLineColor: vec3f, mirror: f32,
   // farCascade: 1 while a stage is loaded, 0 otherwise. See the branch below —
   // with no stage the far map is never drawn into, so its taps are known.
-  mirrorBlur: f32, farCascade: f32, _mb1: f32, _mb2: f32,
+  mirrorBlur: f32, farCascade: f32, shadowSoftness: f32, _mb2: f32,
   // Every shadow caster in one sphere, refreshed per frame. w = radius; 0 means
   // nothing casts, negative means "do not use this" (a rigid caster has no
   // sphere, so a scene with a stage keeps the taps). See rzShadowPossible.
@@ -150,6 +203,11 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   // The same reasoning the noise tint below already got, applied to the term
   // that costs a hundred times more.
   if (material.shadowStrength > 0.0 && shadowPossible) {
+  // Per-pixel rotation for the soft disk, so its rings break up into fine noise
+  // rather than banding. Interleaved gradient noise: a function of the pixel
+  // alone, so a still camera gives a still shadow — the sharp path ignores it.
+  let ign = fract(52.9829189 * fract(dot(i.position.xy, vec2f(0.06711056, 0.00583715))));
+  let rot = ign * 6.28318530718;
   // The far cascade's taps, skipped entirely when nothing ever drew into it.
   //
   // This branch is the expensive one on a wide floor: it runs wherever the NEAR
@@ -163,32 +221,20 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   if (material.farCascade > 0.0 && frustum < 1.0 && frustum1 > 0.0) {
     let suv1 = vec2f(ndc1.x * 0.5 + 0.5, 0.5 - ndc1.y * 0.5);
     let suv1_c = clamp(suv1, vec2f(0.02), vec2f(0.98));
-    let st1 = ${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize} * 2.0;
     let compareZ1 = ndc1.z - 0.0035;
     var acc1 = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        acc1 += textureSampleCompareLevel(shadowMapFar, shadowSampler, suv1_c + vec2f(f32(x), f32(y)) * st1, compareZ1);
-      }
-    }
-    vis = mix(1.0, acc1 * (1.0 / 9.0), frustum1);
+${pcfWgsl("shadowMapFar", "suv1_c", `${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize}`, "compareZ1", "acc1", "    ")}
+    vis = mix(1.0, acc1, frustum1);
   }
   if (frustum > 0.0) {
     let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
     let suv_c = clamp(suv, vec2f(0.02), vec2f(0.98));
-    let st = material.pcfTexel * 2.0;
     let compareZ = ndc.z - 0.0035;
     var acc = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        // ...Level, not the implicit-derivative form: identical on a single-mip
-        // shadow map, and legal inside this branch.
-        acc += textureSampleCompareLevel(shadowMap, shadowSampler, suv_c + vec2f(f32(x), f32(y)) * st, compareZ);
-      }
-    }
+${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ")}
     // The base is whatever the far cascade decided, so the near border blends
     // cascade to cascade rather than snapping to lit mid-floor.
-    vis = mix(vis, acc * (1.0 / 9.0), frustum);
+    vis = mix(vis, acc, frustum);
   }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.55.0",
+  "version": "0.55.1",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/camera.ts

@@ -63,6 +63,19 @@ export class Camera {
   maxZ: number = FAR_CAP
   lowerBetaLimit: number = 0.001
   upperBetaLimit: number = Math.PI - 0.001
+  /**
+   * Orbit roll, radians — the lean the orbit itself cannot state.
+   *
+   * alpha and beta are a yaw and a pitch about an upright axis, and lookAt is
+   * handed world up, so an orbiting shot is level by construction. This tips
+   * that up vector about the eye→target line, which leaves WHERE the camera is
+   * and WHAT it looks at exactly as they were.
+   *
+   * That is the whole reason it lives here rather than in a pose pushed from
+   * outside: a rolled shot still follows a bone, still orbits, still zooms. A
+   * pose replaces all of that with one frozen answer.
+   */
+  roll: number = 0
 
   // Reused each frame so getViewMatrix/getProjectionMatrix don't allocate a Mat4 per call.
   private _viewMat = new Mat4(new Float32Array(16))
@@ -140,7 +153,10 @@ export class Camera {
     // NEGATIVE to match: in a VMD the camera sits behind its target.
     return {
       target: new Vec3(this.target.x, this.target.y, this.target.z),
-      rotation: new Vec3(this.beta - Math.PI / 2, -this.alpha, 0),
+      // z carries the roll, so a rolled orbit exports and reads back as the
+      // same shot rather than a level one — the AE rig and the VMD writer both
+      // take this channel.
+      rotation: new Vec3(this.beta - Math.PI / 2, -this.alpha, this.roll),
       distance: -this.radius,
       fov: this.fov,
     }
@@ -208,7 +224,49 @@ export class Camera {
     }
     const eye = this.getPosition()
     const t = this.target
-    Mat4.lookAtInto(this._viewMat.values, eye.x, eye.y, eye.z, t.x, t.y, t.z, 0, 1, 0)
+    if (this.roll === 0) {
+      Mat4.lookAtInto(this._viewMat.values, eye.x, eye.y, eye.z, t.x, t.y, t.z, 0, 1, 0)
+      return this._viewMat
+    }
+    // Roll = the up vector, turned about the view axis. Build the shot's own
+    // basis first (forward, then right, then a true up), because world up is
+    // only the camera's up while the shot is level — which is the thing this is
+    // about to stop being.
+    let fx = t.x - eye.x
+    let fy = t.y - eye.y
+    let fz = t.z - eye.z
+    const fl = Math.hypot(fx, fy, fz) || 1
+    fx /= fl
+    fy /= fl
+    fz /= fl
+    // right = forward × worldUp, with worldUp = (0,1,0), which is (−fz, 0, fx).
+    //
+    // WRITTEN THE OTHER WAY ROUND ONCE, and it did not fail quietly: that is
+    // worldUp × forward, so `right` pointed left, `up` below came out as right ×
+    // forward = DOWN, and the camera turned upside down the moment roll left
+    // zero. Degenerate only when the shot looks straight up or down, where
+    // beta's own limits already keep it from arriving.
+    let rx = -fz
+    let ry = 0
+    let rz = fx
+    const rl = Math.hypot(rx, ry, rz) || 1
+    rx /= rl
+    ry /= rl
+    rz /= rl
+    // up = right × forward
+    const ux = ry * fz - rz * fy
+    const uy = rz * fx - rx * fz
+    const uz = rx * fy - ry * fx
+    const c = Math.cos(this.roll)
+    const sn = Math.sin(this.roll)
+    Mat4.lookAtInto(
+      this._viewMat.values,
+      eye.x, eye.y, eye.z,
+      t.x, t.y, t.z,
+      ux * c + rx * sn,
+      uy * c + ry * sn,
+      uz * c + rz * sn,
+    )
     return this._viewMat
   }