reze-engine 0.68.8 → 0.68.9

package/dist/shaders/passes/sim.js

@@ -0,0 +1,169 @@
+import { audioApi } from "../audio-api";
+import { scoreApi } from "../score-api";
+import { EFFECT_SCENE_API } from "./composite";
+// A persistent grid an effect can step and read: the one thing an effect could
+// not have before, which is MEMORY.
+//
+// Every other mount is a pure function of position and time. A field shader
+// recomputes its noise from scratch every frame; a trail reads history the
+// engine happens to keep. Neither can build on what it produced last frame, and
+// a whole class of effect is nothing but that:
+//
+//   Fog that a dancer walks through does not "look displaced near her" — it IS
+//   displaced, and stays displaced, and creeps back over seconds. Water does not
+//   look rippled where a foot landed; a ripple leaves and propagates and
+//   reflects off the far edge long after the foot is gone. Both are the same
+//   shape of thing — a grid, stepped by its own previous value.
+//
+// It is also the only way to get the LOOK of a fluid, not merely its motion.
+// Advection compounds: each frame's field is the last one pushed sideways, and a
+// few hundred frames of that stretches and folds a smooth field into filaments
+// and vortex sheets finer than the grid storing them. No noise function
+// produces that, at any octave count, because the structure is not a function of
+// position at all — it is a function of history.
+//
+// The engine owns the ping-pong, the dispatch and the sampling. The author owns
+// the KERNEL, which is the part that differs: advection for smoke, the wave
+// equation for water, a decaying stamp for footprints. That split is the same
+// one the particle mounts make, and for the same reason — the loop is identical
+// in every such effect and the physics never is.
+// A megatexel of rgba16float is 8MB, and two of those is the whole cost. What
+// actually bounds this is the STEP: one invocation per texel per frame, each
+// taking a dozen samples, so doubling the side quadruples the work.
+export const SIM_MAX = 1024;
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export const SIM_FORMAT = "rgba16float";
+/** `// @sim 256` — the grid's resolution, in texels per side. */
+export function parseSimSize(wgsl, max) {
+    const m = /^\s*\/\/\s*@sim\s+(\d+)\s*$/m.exec(wgsl);
+    if (!m)
+        return 0;
+    // Clamped rather than rejected, as the particle count is: an author asking for
+    // 4096 gets the most the engine will give and a scene that still runs.
+    return Math.max(8, Math.min(max, parseInt(m[1], 10)));
+}
+/** Whether this effect drives a grid at all. */
+export function simEntryPoint(wgsl) {
+    return /\bfn\s+simStep\s*\(/.test(wgsl);
+}
+/**
+ * `rzSim(uv)`, for a shader that READS the grid rather than steps it.
+ *
+ * Always compiled in, even for an effect with no grid — it then samples a 1×1
+ * of zeroes. An accessor that exists only sometimes is one an author has to
+ * guard, and a missing function is a compile error rather than a blank result.
+ */
+export function simReadApi(group, tex, samp, size) {
+    return /* wgsl */ `
+const RZ_SIM_SIZE: f32 = ${size > 0 ? size : 1}.0;
+@group(${group}) @binding(${tex}) var _rzSimTex: texture_2d<f32>;
+@group(${group}) @binding(${samp}) var _rzSimSamp: sampler;
+
+/**
+ * The grid, bilinearly sampled. uv is 0..1 across it, and what that MEANS in
+ * the world is the effect's own business — the engine deliberately does not
+ * impose a mapping, because a fog laid over a stage and a ripple field around a
+ * character want different ones and both are two lines of arithmetic.
+ */
+fn rzSim(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+fn rzSimSize() -> f32 { return RZ_SIM_SIZE; }
+fn rzSimTexel() -> f32 { return 1.0 / RZ_SIM_SIZE; }
+
+// ── The step-only half, defined here too and never called here ──
+//
+// One effect file is spliced into EVERY module it has a mount in, so a file
+// with a grid compiles its simStep inside the field and particle shaders as
+// well — where it is dead code that nothing calls, but still code that has to
+// resolve. Leaving these out is a compile error on a function the author was
+// right to write. rzSimPrev reads the current grid rather than a previous one,
+// which is the honest answer outside the step: there is no previous frame here.
+fn rzSimPrev(uv: vec2f) -> vec4f { return rzSim(uv); }
+fn rzSimFrame() -> i32 { return 1; }
+`;
+}
+/** `rzTime`/`rzDt`, for a module that has no clock of its own — the field pass.
+ *  Same reason as above: a spliced simStep refers to them. */
+export function simClockApi(timeExpr) {
+    return /* wgsl */ `
+fn rzTime() -> f32 { return ${timeExpr}; }
+fn rzDt() -> f32 { return 0.0; }
+`;
+}
+const SIM_UNIFORMS = /* wgsl */ `
+struct SimU {
+  time: f32,
+  dt: f32,
+  size: f32,
+  frame: f32,
+}
+`;
+/**
+ * The step shader: one invocation per texel, once per frame.
+ *
+ * The previous grid is bound as a SAMPLED texture and the next as a storage
+ * texture, which is what makes the two different resources and the whole thing
+ * legal — a shader cannot read and write one texture coherently, and the
+ * ping-pong is not an optimisation but the only correct way to do this.
+ *
+ * Sampled rather than only fetched, because advection needs to read BETWEEN
+ * texels: a semi-Lagrangian step asks "what was at the place this parcel came
+ * from", and that place is almost never a texel centre. Point-sampling it is
+ * what turns smoke into a staircase.
+ */
+export function buildSimShader(wgsl, size, _cast) {
+    return (SIM_UNIFORMS +
+        /* wgsl */ `
+@group(0) @binding(0) var<uniform> su: SimU;
+@group(0) @binding(1) var _rzSimPrevTex: texture_2d<f32>;
+@group(0) @binding(2) var _rzSimSamp: sampler;
+@group(0) @binding(3) var _rzSimOut: texture_storage_2d<${SIM_FORMAT}, write>;
+@group(0) @binding(4) var<storage, read> _rzCast: array<vec4f>;
+// The same view uniform the composite reads, so the scene API below is the real
+// thing here rather than a stub — a kernel can ask where a bone is, and a
+// foreground spliced into this module resolves its camera calls.
+@group(0) @binding(6) var<uniform> viewU: array<vec4<f32>, 15>;
+
+fn rzTime() -> f32 { return su.time; }
+fn rzDt() -> f32 { return su.dt; }
+/** Texels per side. */
+fn rzSimSize() -> f32 { return su.size; }
+/** One texel, in uv — the step a neighbour lookup takes. */
+fn rzSimTexel() -> f32 { return 1.0 / su.size; }
+/**
+ * Steps since this effect was installed. Zero on the very first one, which is
+ * the only chance to seed a grid: everything after it builds on what is there.
+ */
+fn rzSimFrame() -> i32 { return i32(su.frame); }
+
+/** The grid as it was LAST frame, bilinear. The only input a kernel really has. */
+fn rzSimPrev(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimPrevTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+` +
+        EFFECT_SCENE_API +
+        audioApi(0, 5) +
+        scoreApi(0, 7) +
+        // rzSim itself, so a kernel may read the grid it is writing — through the
+        // PREVIOUS frame's texture, which is the only version of it that exists
+        // while the current one is still being written.
+        /* wgsl */ `
+fn rzSim(uv: vec2f) -> vec4f { return rzSimPrev(uv); }
+` +
+        "\n// ── user effect (setEffect) ──\n" +
+        wgsl +
+        /* wgsl */ `
+
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let n = u32(${size});
+  if (gid.x >= n || gid.y >= n) { return; }
+  let xy = vec2i(i32(gid.x), i32(gid.y));
+  // The texel CENTRE, so a kernel that reads its own uv back through rzSimPrev
+  // lands on itself rather than a quarter-texel off.
+  let uv = (vec2f(f32(gid.x), f32(gid.y)) + vec2f(0.5)) / su.size;
+  textureStore(_rzSimOut, xy, simStep(uv, textureLoad(_rzSimPrevTex, xy, 0), su.dt));
+}
+`);
+}

package/dist/shaders/score-api.d.ts

@@ -0,0 +1,10 @@
+/** Floats before the key map: count, pitch range, clock, duration, release. */
+export declare const SCORE_HEADER = 8;
+/** One energy slot per MIDI pitch. 128 is the MIDI range, not a cap we chose. */
+export declare const SCORE_KEYS = 128;
+/** Where the note records begin. */
+export declare const SCORE_NOTES: number;
+/** Floats per note: start, duration, pitch, velocity. */
+export declare const SCORE_STRIDE = 4;
+/** The rzNote*/ export declare function scoreApi(group: number, binding: number): string;
+//# sourceMappingURL=score-api.d.ts.map

package/dist/shaders/score-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-api.d.ts","sourceRoot":"","sources":["../../src/shaders/score-api.ts"],"names":[],"mappings":"AA8BA,+EAA+E;AAC/E,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,iFAAiF;AACjF,eAAO,MAAM,UAAU,MAAM,CAAA;AAC7B,oCAAoC;AACpC,eAAO,MAAM,WAAW,QAA4B,CAAA;AACpD,yDAAyD;AACzD,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B,gBAAgB,CAChB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2E/D"}

package/dist/shaders/score-api.js

@@ -0,0 +1,114 @@
+// The score data interface, as WGSL — shared verbatim by every effect module.
+//
+// The sibling of the audio interface, and precomputed for the same reason: an
+// export steps the engine frame by frame rather than playing in real time, so
+// anything read live from a player would render empty into the exported video.
+// A note list is inherently precomputed, so it cannot even be tempted.
+//
+// WHY THIS EXISTS BESIDE rzAudio* RATHER THAN INSTEAD OF IT. The audio interface
+// answers "how loud is the bass right now" — a spectrum, smeared across
+// frequency and time. That is the right shape for a reactive backdrop and the
+// wrong shape for a note: you cannot recover a discrete onset, a pitch and a
+// duration from band energy, and the crispness of a falling note is the whole
+// point of the look. The two are complementary — a scene can pulse its fog on
+// rzAudioOnset while its notes fall on rzNoteAge.
+//
+// LAYOUT. An 8-float header, then a 128-float live key map, then the notes at 4
+// floats each (start, duration, pitch, velocity). `time` and `playing` are
+// rewritten every frame by whoever owns playback, exactly as the audio header
+// is, so "now" is always the clock actually running.
+//
+// THE KEY MAP IS THE POINT OF THE DESIGN. Falling notes index the note list
+// directly — one particle per note, which is what makes the geometry trivial.
+// But a keyboard glow asks the opposite question, per pixel: is anything
+// sounding at THIS pitch? Answering that by scanning the note list would be
+// thousands of iterations per fragment. So the engine keeps a 128-entry
+// per-pitch energy map, updated once per frame on the CPU, and the glow becomes
+// one lookup — the same trade the audio interface makes by precomputing onset
+// so "a beat-triggered effect is one comparison instead of a per-pixel history
+// scan".
+/** Floats before the key map: count, pitch range, clock, duration, release. */
+export const SCORE_HEADER = 8;
+/** One energy slot per MIDI pitch. 128 is the MIDI range, not a cap we chose. */
+export const SCORE_KEYS = 128;
+/** Where the note records begin. */
+export const SCORE_NOTES = SCORE_HEADER + SCORE_KEYS;
+/** Floats per note: start, duration, pitch, velocity. */
+export const SCORE_STRIDE = 4;
+/** The rzNote*/ /* rzKey* accessors, with the buffer declared at the given binding. */
+export function scoreApi(group, binding) {
+    return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzScore: array<f32>;
+
+/** Notes in the score; 0 when none is loaded, which every accessor below
+ *  tolerates by returning zero rather than reading past the end. */
+fn rzNoteCount() -> i32 { return i32(_rzScore[0]); }
+/** Where the score is NOW, in seconds — the clock every age below hangs from. */
+fn rzScoreTime() -> f32 { return _rzScore[3]; }
+/** 1 while the score is advancing, 0 paused or absent. */
+fn rzScorePlaying() -> f32 { return select(0.0, _rzScore[4], i32(_rzScore[0]) > 0); }
+/** Last note-off, in seconds — the length of the piece. */
+fn rzScoreDuration() -> f32 { return _rzScore[5]; }
+/** Lowest and highest pitch the score actually uses. Lay a keyboard out against
+ *  these rather than against 0..127 and a piano piece fills the screen instead
+ *  of occupying its middle third. */
+fn rzPitchLow() -> f32 { return _rzScore[1]; }
+fn rzPitchHigh() -> f32 { return _rzScore[2]; }
+
+fn _rzNoteAt(i: i32, field: i32) -> f32 {
+  if (i < 0 || i >= i32(_rzScore[0])) { return 0.0; }
+  return _rzScore[${SCORE_NOTES} + i * ${SCORE_STRIDE} + field];
+}
+
+/** When note i begins, in seconds. */
+fn rzNoteStart(i: i32) -> f32 { return _rzNoteAt(i, 0); }
+/** How long note i sounds, in seconds. */
+fn rzNoteLength(i: i32) -> f32 { return _rzNoteAt(i, 1); }
+/** MIDI pitch of note i — 60 is middle C. */
+fn rzNotePitch(i: i32) -> f32 { return _rzNoteAt(i, 2); }
+/** How hard note i was struck, 0..1. */
+fn rzNoteVelocity(i: i32) -> f32 { return _rzNoteAt(i, 3); }
+
+/**
+ * Seconds since note i began — NEGATIVE before it does.
+ *
+ * The falling-note function, and the sign is the whole of it: a note's height is
+ * -rzNoteAge(i) * speed, so a note not yet played sits above the keyboard at a
+ * distance proportional to how long is left, crosses zero exactly as it sounds,
+ * and keeps going. One expression, no state, no spawning — which is why one
+ * particle per note is the natural mapping and the pool index IS the note index.
+ */
+fn rzNoteAge(i: i32) -> f32 { return _rzScore[3] - rzNoteStart(i); }
+
+/** 1 while note i is sounding, 0 either side of it. */
+fn rzNoteHeld(i: i32) -> f32 {
+  let age = rzNoteAge(i);
+  return select(0.0, 1.0, age >= 0.0 && age < rzNoteLength(i));
+}
+
+/**
+ * Energy at a MIDI pitch right now: 1 the instant it is struck, holding while
+ * sounding, then falling away over the release set at install time.
+ *
+ * Per PITCH rather than per note, because that is the question a keyboard asks
+ * and a note list cannot answer cheaply — see the header. Fractional pitches
+ * read the nearest key, so a caller can hand this a continuous x across the
+ * keyboard without rounding first.
+ */
+fn rzKeyEnergy(pitch: f32) -> f32 {
+  let k = i32(round(pitch));
+  if (k < 0 || k >= ${SCORE_KEYS}) { return 0.0; }
+  return _rzScore[${SCORE_HEADER} + k];
+}
+
+/**
+ * A pitch's place across the score's own range, 0..1 — the x of a falling note
+ * and of the key it lands on, which have to agree or the effect is nonsense.
+ */
+fn rzPitchX(pitch: f32) -> f32 {
+  let lo = _rzScore[1];
+  let hi = _rzScore[2];
+  return select(0.5, (pitch - lo) / max(hi - lo, 1.0), hi > lo);
+}
+`;
+}

package/dist/shaders/shadow-api.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ *
+ * Shared with the materials, so an effect's shadow and her own shadow soften
+ * alike. The sampler is linear-filtered, which makes each tap a 2×2 bilinear
+ * compare. Unrolled — Safari's Metal backend doesn't unroll nested shadow
+ * loops reliably. The body expects `ndc` in scope and returns.
+ */
+export declare const pcf9: (map: string, ts: string, sampler?: string) => string;
+/** Bindings the real accessor takes, from `binding` upward. */
+export declare const SHADOW_API_BINDINGS = 5;
+/**
+ * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
+ * caster's shadow, soft in between.
+ *
+ * With `on`, declares five bindings from `binding`:
+ *   +0 the light uniform (the sun's direction, and in .w the shadow switch)
+ *   +1 the cascade view-projections, then the caster sphere
+ *   +2 the near cascade's map   +3 the far cascade's map
+ *   +4 the comparison sampler
+ *
+ * It takes a POINT and no normal. The materials' sampleShadow also rejects a
+ * surface facing away from the sun, which is right for skin and wrong for a
+ * blade of grass or a petal: those are thin, lit through, and shaded by their
+ * own N·L. The point is nudged toward the sun instead, which lifts a blade's
+ * root off a stage floor that casts into the same map.
+ */
+export declare function shadowApi(on: boolean, group: number, binding: number): string;
+//# sourceMappingURL=shadow-api.d.ts.map

package/dist/shaders/shadow-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-api.d.ts","sourceRoot":"","sources":["../../src/shaders/shadow-api.ts"],"names":[],"mappings":"AAcA;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,gBAAyB,WActE,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAyD7E"}

package/dist/shaders/shadow-api.js

@@ -0,0 +1,112 @@
+import { SHADOW_CASCADES } from "../shadow-cascades";
+// The sun's shadow, as an effect author sees it.
+//
+// A lawn standing in a character's shadow has to darken where the floor under
+// it does, or the figure floats: the ground catcher draws her shadow, and the
+// blades drawn over it hide it. The map is already there — the materials and
+// the ground read it every frame — so this hands the same lookup to effects.
+//
+// Bound for real in the particle SHADING stage only. That is where geometry an
+// effect draws inside the scene pass is shaded, and the shadow pass has already
+// run by then. Every other module that compiles the author's file gets the
+// stub, which answers 1: lit is what a point with no occlusion information is,
+// the same answer sampleShadow gives outside every cascade.
+/**
+ * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ *
+ * Shared with the materials, so an effect's shadow and her own shadow soften
+ * alike. The sampler is linear-filtered, which makes each tap a 2×2 bilinear
+ * compare. Unrolled — Safari's Metal backend doesn't unroll nested shadow
+ * loops reliably. The body expects `ndc` in scope and returns.
+ */
+export const pcf9 = (map, ts, sampler = "shadowSampler") => /* wgsl */ `
+  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  let cmpZ = ndc.z - 0.001;
+  let ts = ${ts};
+  let s00 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, -ts), cmpZ);
+  let s10 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0, -ts), cmpZ);
+  let s20 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, -ts), cmpZ);
+  let s01 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, 0.0), cmpZ);
+  let s11 = textureSampleCompareLevel(${map}, ${sampler}, suv, cmpZ);
+  let s21 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, 0.0), cmpZ);
+  let s02 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts,  ts), cmpZ);
+  let s12 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0,  ts), cmpZ);
+  let s22 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts,  ts), cmpZ);
+  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+`;
+/** Bindings the real accessor takes, from `binding` upward. */
+export const SHADOW_API_BINDINGS = 5;
+/**
+ * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
+ * caster's shadow, soft in between.
+ *
+ * With `on`, declares five bindings from `binding`:
+ *   +0 the light uniform (the sun's direction, and in .w the shadow switch)
+ *   +1 the cascade view-projections, then the caster sphere
+ *   +2 the near cascade's map   +3 the far cascade's map
+ *   +4 the comparison sampler
+ *
+ * It takes a POINT and no normal. The materials' sampleShadow also rejects a
+ * surface facing away from the sun, which is right for skin and wrong for a
+ * blade of grass or a petal: those are thin, lit through, and shaded by their
+ * own N·L. The point is nudged toward the sun instead, which lifts a blade's
+ * root off a stage floor that casts into the same map.
+ */
+export function shadowApi(on, group, binding) {
+    if (!on) {
+        return /* wgsl */ `
+fn rzShadow(p: vec3f) -> f32 { return 1.0; }
+`;
+    }
+    const n = SHADOW_CASCADES.length;
+    return /* wgsl */ `
+// The first two vec4s of the light uniform: world ambient, then the sun.
+struct _RzShadowSun { ambient: vec4f, direction: vec4f, }
+// The cascades' matrices, inner to outer, then every caster in one sphere
+// (x, y, z, radius): radius 0 = nothing casts, negative = do not test.
+struct _RzShadowBlock { viewProj: array<mat4x4f, ${n}>, casters: vec4f, }
+@group(${group}) @binding(${binding}) var<uniform> _rzShadowSun: _RzShadowSun;
+@group(${group}) @binding(${binding + 1}) var<uniform> _rzShadowVP: _RzShadowBlock;
+@group(${group}) @binding(${binding + 2}) var _rzShadowNear: texture_depth_2d;
+@group(${group}) @binding(${binding + 3}) var _rzShadowFar: texture_depth_2d;
+@group(${group}) @binding(${binding + 4}) var _rzShadowCmp: sampler_comparison;
+
+fn _rzShadowNearTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowNear", `1.0 / ${SHADOW_CASCADES[0].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn _rzShadowFarTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowFar", `1.0 / ${SHADOW_CASCADES[n - 1].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn rzShadow(p: vec3f) -> f32 {
+  // The scene's one shadow switch, on the sun — see sampleShadow.
+  let castAmt = _rzShadowSun.direction.w;
+  if (castAmt <= 0.0) { return 1.0; }
+  let toSun = normalize(-_rzShadowSun.direction.xyz);
+  // Can anything cast onto this point at all? The ground's test, for the same
+  // two reasons: most of a lawn is nowhere near her, and a scene with no
+  // models never renders the map, whose untouched zeroes compare as shadowed.
+  let cs = _rzShadowVP.casters;
+  if (cs.w == 0.0) { return 1.0; }
+  if (cs.w > 0.0) {
+    let toCaster = cs.xyz - p;
+    let along = dot(toCaster, toSun);
+    let perp = length(toCaster - toSun * along);
+    if (along <= -cs.w || perp > cs.w) { return 1.0; }
+  }
+  let q = p + toSun * 0.08;
+  let c0 = _rzShadowVP.viewProj[0] * vec4f(q, 1.0);
+  let n0 = c0.xyz / max(c0.w, 1e-6);
+  if (all(abs(n0.xy) < vec2f(0.98)) && n0.z > 0.0 && n0.z < 1.0) {
+    return mix(1.0, _rzShadowNearTaps(n0), castAmt);
+  }
+  let c1 = _rzShadowVP.viewProj[${n - 1}] * vec4f(q, 1.0);
+  let n1 = c1.xyz / max(c1.w, 1e-6);
+  if (all(abs(n1.xy) < vec2f(0.98)) && n1.z > 0.0 && n1.z < 1.0) {
+    return mix(1.0, _rzShadowFarTaps(n1), castAmt);
+  }
+  return 1.0;
+}
+`;
+}

package/package.json

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

package/src/engine.ts

@@ -354,11 +354,6 @@ type GroupInstall = {
   pipelineNoDepthWrite: GPURenderPipeline
   /** hair render-class only: the stencil-matched IS_OVER_EYES=true variant. */
   overEyesPipeline?: GPURenderPipeline
-  /** eye render-class only: the same pipeline with its cull flipped, for the
-   *  mirror pass. The eye is the ONE material class that culls a face, and a
-   *  reflection flips winding, so in the mirror the ordinary pipeline keeps
-   *  exactly the faces it exists to discard. */
-  mirrorPipeline?: GPURenderPipeline
   uniformBuffer: GPUBuffer
   /** The group's own image maps, uploaded once per apply and owned here — the
    *  install destroys them when it is replaced, so a re-apply cannot leak. */
@@ -8512,6 +8507,8 @@ export class Engine {
         { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
         { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
         { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+        // The model's ObjectLight, for its jelly eyes.
+        { binding: 3, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
       ],
     })
     const shadowShader = this.device.createShaderModule({
@@ -15180,6 +15177,20 @@ export class Engine {
       physics.setFloor(this.physicsFloor)
     }
 
+    // Its ObjectLight: the world's ambient, and the layers its kind draws on —
+    // the cast on the character layer as well as the default one. Words:
+    // layers [0..3], ambient flag [4..7], SH [8..43], fill [44..47], jelly
+    // eyes [48..71] — see materials/common.ts.
+    const objectLight = new Float32Array(96)
+    new Uint32Array(objectLight.buffer)[0] =
+      isStage || isPlane || isProp ? RENDERING_LAYER_DEFAULT : (RENDERING_LAYER_DEFAULT | RENDERING_LAYER_CHARACTER) >>> 0
+    const lightBuffer = this.device.createBuffer({
+      label: `${name}: object light`,
+      size: objectLight.byteLength,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    })
+    this.device.queue.writeBuffer(lightBuffer, 0, objectLight)
+
     // One per cascade: the shadow VERTEX shader reads a single matrix, and
     // which one is the only thing that differs between the cascade passes.
     const shadowBindGroups = SHADOW_CASCADES.map((_, ci) =>
@@ -15190,6 +15201,7 @@ export class Engine {
           { binding: 0, resource: { buffer: this.shadowCascadeVPBuffers[ci] } },
           { binding: 1, resource: { buffer: skinMatrixBuffer } },
           { binding: 2, resource: this.materialSampler },
+          { binding: 3, resource: { buffer: lightBuffer } },
         ],
       }),
     )
@@ -15202,23 +15214,10 @@ export class Engine {
           { binding: 0, resource: { buffer: this.castShadowVPBuffer } },
           { binding: 1, resource: { buffer: skinMatrixBuffer } },
           { binding: 2, resource: this.materialSampler },
+          { binding: 3, resource: { buffer: lightBuffer } },
         ],
       }),
     )
-
-    // Its ObjectLight: the world's ambient, and the layers its kind draws on —
-    // the cast on the character layer as well as the default one. Words:
-    // layers [0..3], ambient flag [4..7], SH [8..43], fill [44..47], jelly
-    // eyes [48..71] — see materials/common.ts.
-    const objectLight = new Float32Array(96)
-    new Uint32Array(objectLight.buffer)[0] =
-      isStage || isPlane || isProp ? RENDERING_LAYER_DEFAULT : (RENDERING_LAYER_DEFAULT | RENDERING_LAYER_CHARACTER) >>> 0
-    const lightBuffer = this.device.createBuffer({
-      label: `${name}: object light`,
-      size: objectLight.byteLength,
-      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-    })
-    this.device.queue.writeBuffer(lightBuffer, 0, objectLight)
     const mainPerInstanceBindGroup = this.perInstanceBindGroup(name, skinMatrixBuffer, lightBuffer)
 
     const pickPerInstanceBindGroup = this.device.createBindGroup({
@@ -16189,6 +16188,10 @@ export class Engine {
       // Alpha is the switch; clamp the rest so a stacked multiply cannot send a
       // colour negative and light the material from the inside.
       for (let k = 0; k < 11; k++) if (d[k] < 0) d[k] = 0
+      // Alpha also stops at 1, as in MMD. Models ship additive +1 alpha morphs
+      // (照れ on 拾星梦语) that MMD's clamp makes a no-op; let through, alpha 2
+      // blends as src*2 - dst and burns every material white.
+      if (d[3] > 1) d[3] = 1
       if (d[3] < 0.0001) inst.morphHiddenMaterials.add(target.materialName)
       let changed = false
       for (let k = 0; k < 11; k++) {
@@ -18021,10 +18024,9 @@ export class Engine {
         if (!result.ok) return
         const module = this.cachedShaderModule(result.wgsl, `style group: ${g.id} (${renderClass})`)
         await Promise.all([
-          this.createRenderClassPipeline(renderClass, module, false, true, false, blend),
-          this.createRenderClassPipeline(renderClass, module, false, false, false, blend),
-          renderClass === "hair" ? this.createRenderClassPipeline(renderClass, module, true, true, false, blend) : null,
-          renderClass === "eye" ? this.createRenderClassPipeline(renderClass, module, false, true, true, blend) : null,
+          this.createRenderClassPipeline(renderClass, module, false, true, blend),
+          this.createRenderClassPipeline(renderClass, module, false, false, blend),
+          renderClass === "hair" ? this.createRenderClassPipeline(renderClass, module, true, true, blend) : null,
         ]).catch(() => {})
       }),
     )
@@ -18401,20 +18403,17 @@ export class Engine {
     // The single-sided twins a draw of this group will ask for (sidedPipeline),
     // built with their pipelines rather than synchronously at the first draw.
     const singleSided = inst.drawCalls.some((dc) => !dc.doubleSided && group.materials.includes(dc.materialName))
-    const variant = (overEyes: boolean, depthWrite: boolean, mirrored: boolean) =>
-      this.createRenderClassPipeline(renderClass, module, overEyes, depthWrite, mirrored, blend).then(async (p) => {
-        if (singleSided && !mirrored) await this.buildSidedTwin(p, false)
+    const variant = (overEyes: boolean, depthWrite: boolean) =>
+      this.createRenderClassPipeline(renderClass, module, overEyes, depthWrite, blend).then(async (p) => {
+        if (singleSided) await this.buildSidedTwin(p, false)
         return p
       })
     const variants = Promise.all([
-      variant(false, true, false),
+      variant(false, true),
       // The depth-write-off twin: stage transparency draws with it (see
       // pipelineForDrawCall), and a future OIT path would too.
-      variant(false, false, false),
-      renderClass === "hair" ? variant(true, true, false) : undefined,
-      // Only the eye needs one: every other class culls "none", which a flipped
-      // winding leaves alone.
-      renderClass === "eye" ? variant(false, true, true) : undefined,
+      variant(false, false),
+      renderClass === "hair" ? variant(true, true) : undefined,
     ])
     // Handled below either way; this keeps a rejection off the console while
     // the diagnostics are read.
@@ -18435,9 +18434,8 @@ export class Engine {
     let pipeline: GPURenderPipeline
     let pipelineNoDepthWrite: GPURenderPipeline
     let overEyesPipeline: GPURenderPipeline | undefined
-    let mirrorPipeline: GPURenderPipeline | undefined
     try {
-      ;[pipeline, pipelineNoDepthWrite, overEyesPipeline, mirrorPipeline] = await variants
+      ;[pipeline, pipelineNoDepthWrite, overEyesPipeline] = await variants
     } catch (e) {
       diagnostics.push({ severity: "error", message: `pipeline creation failed: ${(e as Error).message}` })
       return { ok: false, diagnostics, slotMap: result.slotMap }
@@ -18467,7 +18465,6 @@ export class Engine {
       pipeline,
       pipelineNoDepthWrite,
       overEyesPipeline,
-      mirrorPipeline,
       uniformBuffer,
       images: this.uploadGroupImages(group),
       imagesByMaterial: group.imagesByMaterial
@@ -18643,29 +18640,25 @@ export class Engine {
   /**
    * Render-class pipeline state. A group's compiled graph swaps the fragment shading; the
    * render-class owns pass integration (stencil interplay, depth bias, cull). auto = plain;
-   * eye = stamp + front cull + bias; hair = stencil-test (+ the over-eyes variant).
+   * eye = stencil stamp; hair = stencil-test (+ the over-eyes variant). Cull comes from
+   * the material's double-sided flag (sidedPipeline).
    */
   private createRenderClassPipeline(
     renderClass: RenderClass,
     module: GPUShaderModule,
     overEyes: boolean,
     depthWrite = true,
-    mirrored = false,
     blend: StyleBlend = "over",
   ): Promise<GPURenderPipeline> {
     const base = {
       label: `style ${renderClass}${overEyes ? " (over eyes)" : ""}`,
       layout: this.mainPipelineLayout,
       vertex: { module, buffers: this.materialVertexBufferLayouts },
-      // The eye front-culls — the see-through-hair look is draw order plus that
-      // cull plus the stencil stamp, and it is the deployed appearance of every
-      // published scene. In the MIRROR the winding is flipped (determinant -1,
-      // reflection.ts), so the same cull keeps the back of the eyeball and
-      // discards its front. `mirrored` flips it back rather than changing what
-      // the camera sees.
-      primitive: {
-        cullMode: (renderClass === "eye" ? (mirrored ? "back" : "front") : "none") as GPUCullMode,
-      },
+      // Every class draws both sides here and takes the PMX double-sided flag
+      // from sidedPipeline, whose single-sided twin culls front (back in the
+      // mirror's flipped winding) — the eye's old fixed cull. A double-sided
+      // iris sheet keeps the faces a turn of the eye swings away.
+      primitive: { cullMode: "none" as GPUCullMode },
       multisample: { count: Engine.MULTISAMPLE_COUNT },
     }
     const plainDepth: GPUDepthStencilState = {
@@ -18956,7 +18949,6 @@ export class Engine {
     if (dc.groupId) {
       const install = inst.styleGroups.get(dc.groupId)
       if (install) {
-        if (mirrored && install.mirrorPipeline) return install.mirrorPipeline
         return stageGlass ? install.pipelineNoDepthWrite : install.pipeline
       }
     }