reze-engine 0.62.1 → 0.64.0

package/src/shaders/materials/nodes.ts

@@ -348,6 +348,215 @@ fn rzWorldSpecularLod(dir: vec3f, roughness: f32, unity: f32) -> vec3f {
   return textureSampleLevel(worldEnvTexture, diffuseSampler, vec2f(u, v), lod).rgb * light.ambientColor.w;
 }
 
+// ── Aether Gazer's character shading, step by step ──
+// From the decompiled ForwardBase pass of SimPipeline/Character/Debug. Its
+// spaces are the game's: a view space looking down -Z (Unity's camera space),
+// which the engine's +Z-forward view is turned into by negating z.
+
+/** CharacterEffect's key light, in sim_TowardMatrix's frame: the camera's
+ *  backward direction flattened to the ground (d), up, and up × d. The
+ *  direction points toward the light. */
+fn ag_key_light(inclination: f32, azimuth: f32) -> vec3f {
+  let f = vec3f(camera.view[0].z, camera.view[1].z, camera.view[2].z);
+  let flat = vec3f(-f.x, 0.0, -f.z);
+  let len = length(flat);
+  let d = select(vec3f(0.0, 0.0, 1.0), flat / max(len, 1e-5), len > 1e-5);
+  let incl = radians(inclination);
+  let az = radians(-azimuth);
+  let c = cos(incl);
+  let k = vec3f(sin(az) * -c, sin(incl), cos(az) * c);
+  return normalize(vec3f(d.z, 0.0, -d.x) * k.x + vec3f(0.0, 1.0, 0.0) * k.y + d * k.z);
+}
+
+/** u on the shadow ramp: N·L, darkened by the mask's occlusion
+ *  (1 - min((1 - ao) * scale, 1)), and min'd with the sun's cast shadow. */
+fn ag_shade_term(n: vec3f, l: vec3f, ao: f32, aoScale: f32, receive: f32, wp: vec3f) -> f32 {
+  let ndl = max(dot(n, l), 0.0);
+  var t = (1.0 - min((1.0 - ao) * aoScale, 1.0)) * ndl;
+  if (receive > 0.5) { t = min(t, rzSunOcclusion(wp, n)); }
+  return t;
+}
+
+/** A ramp image's uv, kept off the image's edge texels so a repeating sampler
+ *  does not blend the far end in. The row is Unity's v, which runs up from the
+ *  image's bottom row; the image is uploaded top row first. */
+fn ag_ramp_uv(value: f32, row: f32) -> vec3f {
+  return vec3f(clamp(value, 0.002, 0.998), clamp(1.0 - row, 0.002, 0.998), 0.0);
+}
+
+/** The view-space reflection, as the game builds it: the view ray mirrored on
+ *  the normal, into camera space, halved and pushed half a unit toward the
+ *  eye, normalised. xy*0.5+0.5 is the sphere image's uv (xyz here, z unused),
+ *  and z how much it faces the eye (w). */
+fn ag_view_reflection(n: vec3f, v: vec3f) -> vec4f {
+  let r = reflect(-v, n);
+  let rv = vec3f(
+    camera.view[0].x * r.x + camera.view[1].x * r.y + camera.view[2].x * r.z,
+    camera.view[0].y * r.x + camera.view[1].y * r.y + camera.view[2].y * r.z,
+    -(camera.view[0].z * r.x + camera.view[1].z * r.y + camera.view[2].z * r.z),
+  );
+  let m = normalize(rv * 0.5 + vec3f(0.0, 0.0, 0.5));
+  // A sphere image is addressed as Unity reads it, v up: flipped for the
+  // top-row-first upload.
+  return vec4f(m.x * 0.5 + 0.5, 0.5 - m.y * 0.5, 0.0, m.z);
+}
+
+/** The matcap's lift: max(mask * (matcap * strength - 1) + 1, 1). */
+fn ag_matcap(color: vec3f, matcap: vec3f, strength: f32, mask: f32) -> vec3f {
+  return color * max(mask * (matcap * strength - vec3f(1.0)) + vec3f(1.0), vec3f(1.0));
+}
+
+/** The rim: smoothstep'd to the silhouette by facing, limited to the two rim
+ *  directions (CharacterEffect: (cos a·s, sin a·s, z), a = azimuth·π,
+ *  s = sqrt(1 - z²)), laid on as a colour dodge: min(max(c, 2), c / (1 - 2·rim)). */
+fn ag_rim(color: vec3f, facing: f32, uvw: vec3f, rimColor: vec3f, threshold: f32, fade: f32, range: f32,
+          inclination: f32, azimuth1: f32, azimuth2: f32, mask: f32) -> vec3f {
+  let m = vec3f(uvw.x * 2.0 - 1.0, 1.0 - uvw.y * 2.0, facing);
+  let t = saturate((facing - (threshold + fade)) / (threshold - (threshold + fade)));
+  let edge = t * t * (3.0 - 2.0 * t);
+  let s = sqrt(max(1.0 - inclination * inclination, 0.0));
+  let a1 = azimuth1 * 3.1415927;
+  let a2 = azimuth2 * 3.1415927;
+  let d1 = vec3f(cos(a1) * s, sin(a1) * s, inclination);
+  let d2 = vec3f(cos(a2) * s, sin(a2) * s, inclination);
+  let along = saturate(max(dot(m, d1), dot(m, d2)) + range);
+  let rim = min(edge, along) * rimColor;
+  let f = min(rim * mask * 2.0, vec3f(0.99));
+  return min(max(color, vec3f(2.0)), color / (vec3f(1.0) - f));
+}
+
+/** The fill: inner to outer by pow(1 - facing², softness + 2), laid over by
+ *  its amount. */
+fn ag_fill(color: vec3f, facing: f32, inner: vec3f, outer: vec3f, amount: f32, softness: f32) -> vec3f {
+  let k = pow(max(1.0 - facing * facing, 0.0), softness + 2.0);
+  return mix(color, mix(inner, outer, k), amount);
+}
+
+// ── Aether Gazer's PBR character shading (SimPipeline/Character/PBR/Uber) ──
+// The ForwardBase pass of the game's current character shader, decompiled and
+// written back out step by step. Its ramp image carries the whole tone of the
+// look in rows: the diffuse ramp in the row the material picks, the specular
+// ramp at 0.95, the environment's floor at 0.85.
+
+/** A ramp image on a group slot, read at a computed coordinate — mip 0 only,
+ *  as the game reads it, and so legal wherever the shading branches. */
+fn _ag_ramp(slot: u32, uv: vec2f) -> vec4f {
+  // Unity's v runs up from the bottom row; the image is uploaded top row first.
+  let c = clamp(vec2f(uv.x, 1.0 - uv.y), vec2f(0.002), vec2f(0.998));
+  switch slot {
+    case 1u: { return textureSampleLevel(groupTexture1, diffuseSampler, c, 0.0); }
+    case 2u: { return textureSampleLevel(groupTexture2, diffuseSampler, c, 0.0); }
+    case 3u: { return textureSampleLevel(groupTexture3, diffuseSampler, c, 0.0); }
+    default: { return textureSampleLevel(groupTexture0, diffuseSampler, c, 0.0); }
+  }
+}
+
+/**
+ * The whole lighting of one Uber material under the character's key light:
+ *   diffuse = base·(1−metal) · ramp(min(shadow, occlusion·N·L), row)
+ *   specular = GGX through the ramp's 0.95 row, × F0, plus the rim, × the
+ *              shade term
+ *   ambient = the object's SH at n × diffuse
+ *   reflection = the scene's environment along the reflected view, at a
+ *              roughness mip, × the mobile environment-BRDF fit
+ *              (F0·A + ramp(N·L·B, 0.85))
+ * Lamps and fog are the engine's, laid on after.
+ */
+fn ag_uber(slot: u32, base: vec3f, metallic: f32, roughness: f32, occlusion: f32, n: vec3f, l: vec3f,
+           row: f32, receive: f32, rimMask: f32, rimMid: f32, rimWidth: f32, rimTint: vec3f,
+           rimIntensity: f32, rimAlbedo: f32, rimInLight: f32, emissive: vec3f, reflection: f32,
+           shade: f32, face: f32, wp: vec3f, v: vec3f) -> vec3f {
+  let diffuse = base * (1.0 - metallic);
+  let f0 = mix(vec3f(0.04), base, metallic);
+  let pr = clamp(roughness, 0.0, 1.0);
+  let r = max(pr * pr, 0.0078125);
+  let a2 = r * r;
+  let h = normalize(v + l);
+  let ndl = saturate(dot(n, l));
+  let ndv = saturate(dot(v, n));
+  let ndh = saturate(dot(n, h));
+  let vdh = saturate(dot(v, h));
+  let ldh = saturate(dot(l, h));
+
+  // where on the ramp: N·L under occlusion, and the sun's cast shadow
+  var shadow = 1.0;
+  if (receive > 0.5) { shadow = rzSunOcclusion(wp, n); }
+  // A face replaces N·L with its SDF shade; anything else reads N·L.
+  let u = min(shadow, occlusion * select(ndl, shade, shade >= 0.0));
+  let ramp = _ag_ramp(slot, vec2f(u, row)).rgb;
+
+  // GGX, as the pass writes it, then through the ramp's specular row
+  let dd = ndh * ndh * (a2 - 1.0) + 1.0;
+  let D = select(a2 / (dd * dd), 1.0, dd * dd == a2);
+  let vis = min(0.5 / (ndl * (ndv * (1.0 - r) + r) + ndv * (ndl * (1.0 - r) + r)), 1.0);
+  let vis2 = min(0.5 / (ldh * (vdh * (1.0 - r) + r) + vdh * (ldh * (1.0 - r) + r)), 1.0);
+  let x = saturate(D * vis * a2 / vis2);
+  let specRamp = _ag_ramp(slot, vec2f(x, 0.95)).rgb;
+  let spec = clamp(vis * specRamp * min(1.0 / a2, 2048.0), vec3f(0.0), vec3f(10.0));
+
+  // the rim: toward the silhouette on the lit side, tinted toward the albedo
+  let lit = select(0.0, 1.0, u > 0.001);
+  let t = saturate(((ndl * 0.25 + 0.75) * (1.0 - ndv) * lit - (rimMid - rimWidth)) / max(2.0 * rimWidth, 1e-4));
+  let edge = t * t * (3.0 - 2.0 * t);
+  let tint = min(rimTint * rimIntensity * mix(vec3f(1.0), base, rimAlbedo) * 2.0 * rimMask, vec3f(0.99));
+  let rim = tint * edge * (1.0 + rimInLight * (u - 1.0));
+
+  // A face (FACE_MODE) takes no GGX: its light is the ramp, the rim and its
+  // optional SDF highlight (off unless _FaceSpecular).
+  let isFace = face > 0.5;
+  let direct = (select(spec * f0, vec3f(0.0), isFace) + rim) * u + diffuse * ramp;
+
+  // the environment, with the game's fit of the split-sum
+  let a004 = min((1.0 - pr) * (1.0 - pr), exp2(-9.28 * ndv)) * (1.0 - pr) + (0.0425 - 0.0275 * pr);
+  let A = -a004 * 1.04 + (1.04 - 0.572 * pr);
+  let ns = saturate(dot(n, mix(reflect(-l, n), h, 0.8)));
+  let B = _ag_ramp(slot, vec2f(ns * (a004 * 1.04 + (0.022 * pr - 0.04)), 0.85)).r;
+  let env = rzWorldSpecularLod(reflect(-v, n), pr, 1.0) * reflection;
+
+  // ... and the environment at a flat 0.0157 rather than through the BRDF fit.
+  let envTerm = select((f0 * A + B) * env, env * 0.0157, isFace);
+  return emissive + rzObjectAmbient(n) * diffuse + envTerm + direct;
+}
+
+
+/**
+ * The face's shade from its SDF image (Uber FACE_MODE, _SDFType 0), in place of
+ * N·L: the key light taken into the face's frame and flattened, the field read
+ * at the uv and at its mirror, the side the light is on choosing which, both
+ * compared against the light's front-to-back angle with _BlendSmoothness, then
+ * softened by how level the light is and a half-Lambert. The face frame is the
+ * head bone's, turned to the game's convention (x to the face's right, z out of
+ * it). An SDF is painted in the face's uvs, so it belongs to models that share
+ * the game's face layout; a white slot reads as a face lit evenly until the
+ * light goes behind it.
+ */
+fn ag_face_sdf(slot: u32, uv: vec2f, l: vec3f, n: vec3f, smoothness: f32, invert: f32) -> f32 {
+  let hb = skinMats[u32(max(material.headBoneIndex, 0.0))];
+  let fx = -normalize(hb[0].xyz);
+  let fy = normalize(hb[1].xyz);
+  let fz = -normalize(hb[2].xyz);
+  let lf = normalize(vec3f(dot(l, fx), dot(l, fy), dot(l, fz)));
+  let fl = lf.xz * inverseSqrt(max(dot(lf.xz, lf.xz), 1.1754944e-38));
+  let u0 = mix(uv.x, 1.0 - uv.x, invert);
+  let s1 = _ag_ramp(slot, vec2f(u0, 1.0 - uv.y));
+  let s2 = _ag_ramp(slot, vec2f(1.0 - u0, 1.0 - uv.y));
+  let left = fl.x < 0.0;
+  let a = select(s2.x, s1.x, left);
+  let b = select(s1.x, s2.x, left);
+  let flag = select(0.0, 1.0, s1.w > 0.5);
+  let k = max(smoothness, 0.001);
+  let th = fl.y * -0.5 + 0.5;
+  let w = 1.0 - th;
+  var m1 = max(saturate((a - th) / k + 0.5), saturate((b - w - 1.0) / k + 0.5));
+  m1 = min(m1, min(saturate((2.0 - a - w) / k + 0.5), saturate((2.0 - b - w) / k + 0.5)));
+  var m2 = max(saturate((b - th - 1.0) / k + 0.5), saturate((a - w) / k + 0.5));
+  m2 = min(m2, min(saturate((a + w) / k + 0.5), saturate((b + w) / k + 0.5)));
+  var r = flag * (m1 - m2) + m2;
+  r *= (1.0 - abs(lf.z)) * 0.5 + 0.5;
+  r *= saturate(dot(n, l)) * 0.5 + 0.5;
+  return r;
+}
+
 fn group_tex0(uv: vec2f) -> vec4f { return textureSample(groupTexture0, diffuseSampler, uv); }
 fn group_tex1(uv: vec2f) -> vec4f { return textureSample(groupTexture1, diffuseSampler, uv); }
 fn group_tex2(uv: vec2f) -> vec4f { return textureSample(groupTexture2, diffuseSampler, uv); }
@@ -1056,6 +1265,7 @@ struct _RzLampPair { d: vec3f, s: vec3f };
 
 fn _rzLampOne(i: u32, p: vec3f, n: vec3f, v: vec3f, ndv: f32, roughness: f32, unity: f32) -> _RzLampPair {
   var out = _RzLampPair(vec3f(0.0), vec3f(0.0));
+  if (!_rzLightReaches(i)) { return out; }
   let pr = _rzLightVec(i, 0u);
   let d = pr.xyz - p;
   let dist = length(d);

package/src/shaders/passes/composite.ts

@@ -302,11 +302,23 @@ fn agxTransform(c: vec3f) -> vec3f {
   return vec3f(srgb_encode(linear.r), srgb_encode(linear.g), srgb_encode(linear.b));
 }
 
-/** Which display transform, chosen per frame at viewU[6].y (0 filmic, 1 standard, 2 agx).
+/**
+ * Aether Gazer's own curve, from its final pass (Hidden/SimPipeline/Final,
+ * decompiled): (1 - e^(-exposure x))^contrast, at the 2.5 and 1.4 its scenes
+ * set, into a linear target the swapchain then encodes. The game's ACES branch
+ * is off in every scene measured.
+ */
+fn agTransform(c: vec3f) -> vec3f {
+  let t = pow(max(vec3f(1.0) - exp(-2.5 * max(c, vec3f(0.0))), vec3f(0.0)), vec3f(1.4));
+  return vec3f(srgb_encode(t.r), srgb_encode(t.g), srgb_encode(t.b));
+}
+
+/** Which display transform, chosen per frame at viewU[6].y (0 filmic, 1 standard, 2 agx, 3 aether-gazer).
  *  A uniform branch rather than a pipeline variant: switching is rare, and both
  *  arms are cheap enough that specialising the pipeline would buy nothing. */
 fn viewTransform(c: vec3f) -> vec3f {
   let mode = viewU[6].y;
+  if (mode > 2.5) { return agTransform(c); }
   if (mode > 1.5) { return agxTransform(c); }
   if (mode > 0.5) { return vec3f(srgb_encode(c.r), srgb_encode(c.g), srgb_encode(c.b)); }
   return vec3f(filmic(c.r), filmic(c.g), filmic(c.b));

package/src/shaders/passes/cull.ts

@@ -130,10 +130,14 @@ fn cs(@builtin(global_invocation_id) gid: vec3<u32>) {
   // a hidden material is not culled, it is switched off, and answering "is this
   // gone because of culling?" requires the two to stay separable.
   let off = frusta.counts.y == 0u;
-  let shown = hidden[i] == 0u;
+  // hidden: bit 0 switched off; bit 1 drawn by the native-material host
+  // (unity/host.ts) rather than by its graph — no camera or mirror draw here,
+  // and still its shadow, which the engine's pass casts for every material.
+  let shown = (hidden[i] & 1u) == 0u;
+  let graph = (hidden[i] & 2u) == 0u;
   let castsShadow = (dm.flags & DRAW_CASTS_SHADOW) != 0u;
-  cameraArgs[i * 5u + 1u] = select(0u, 1u, (inCamera || off) && shown);
+  cameraArgs[i * 5u + 1u] = select(0u, 1u, (inCamera || off) && shown && graph);
   shadowArgs[i * 5u + 1u] = select(0u, 1u, ((inLight && castsShadow) || off) && shown);
-  mirrorArgs[i * 5u + 1u] = select(0u, 1u, (inMirror || off) && shown);
+  mirrorArgs[i * 5u + 1u] = select(0u, 1u, (inMirror || off) && shown && graph);
 }
 `

package/src/shaders/passes/ground.ts

@@ -1,6 +1,7 @@
 import { sceneFsOutWgsl, sceneIdWriteWgsl } from "./scene-contract"
 import { lightsApi } from "../lights"
-import { SHADOW_CASCADES } from "../../shadow-cascades"
+import { SHADOW_ATLAS_SIZE, SHADOW_CASCADES } from "../../shadow-cascades"
+import { SHADOW_MARGIN } from "../scene-light-api"
 import { WORLD_AMBIENT_WGSL } from "../lights"
 
 // Ground shadow-catcher: receives directional shadow, grid lines, frosted noise,
@@ -36,6 +37,9 @@ const SOFT_MAX_SPREAD = 14
  * normalised, so there is no `/ 9.0` left at the call site.
  */
 function pcfWgsl(map: string, uv: string, texel: string, z: string, acc: string, pad: string, soft: boolean): string {
+  // Every tap stays inside the cascade's own tile (tileLo..tileHi, in scope at
+  // the call): the soft disk reaches further than the selection margin, and a
+  // tap in the neighbouring tile compares against another cascade's depths.
   const golden = 2.39996323
   // ONE BRANCH IS COMPILED, NOT BOTH.
   //
@@ -58,7 +62,7 @@ function pcfWgsl(map: string, uv: string, texel: string, z: string, acc: string,
     `  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} += textureSampleCompareLevel(${map}, shadowSampler, clamp(${uv} + vec2f(f32(x), f32(y)) * st, tileLo, tileHi), ${z});`,
     `  }`,
     `}`,
     `${acc} *= ${1 / 9};`,
@@ -71,7 +75,7 @@ function pcfWgsl(map: string, uv: string, texel: string, z: string, acc: string,
     // 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} += textureSampleCompareLevel(${map}, shadowSampler, clamp(${uv} + vec2f(cos(a), sin(a)) * (r * radius), tileLo, tileHi), ${z});`,
     `}`,
     `${acc} *= ${1 / SOFT_TAPS};`,
   ]
@@ -89,12 +93,10 @@ struct Light { direction: vec4f, color: vec4f, };
 struct LightUniforms { ambientColor: vec4f, lights: array<Light, 4>, sh: array<vec4f, 9>, };
 struct GroundShadowMat {
   diffuseColor: vec3f, fadeStart: f32,
-  fadeEnd: f32, shadowStrength: f32, pcfTexel: f32, gridSpacing: f32,
+  fadeEnd: f32, shadowStrength: f32, _pad6: f32, gridSpacing: f32,
   gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, opacity: f32,
   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, shadowSoftness: f32, groundY: f32,
+  mirrorBlur: f32, _pad17: f32, shadowSoftness: f32, groundY: 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.
@@ -105,12 +107,11 @@ struct GroundShadowMat {
 struct LightVP { viewProj: array<mat4x4f, ${SHADOW_CASCADES.length}>, };
 @group(0) @binding(0) var<uniform> camera: CameraUniforms;
 @group(0) @binding(1) var<uniform> light: LightUniforms;
-@group(0) @binding(2) var shadowMap: texture_depth_2d;
+// The sun's shadow atlas — see shadow-cascades.ts.
+@group(0) @binding(2) var shadowAtlas: texture_depth_2d;
 @group(0) @binding(3) var shadowSampler: sampler_comparison;
 @group(0) @binding(4) var<uniform> material: GroundShadowMat;
 @group(0) @binding(5) var<uniform> lightVP: LightVP;
-// The far cascade's map, binding 7 as in the materials' layout.
-@group(0) @binding(7) var shadowMapFar: texture_depth_2d;
 // The floor mirror (step 7D): the reflection target, the camera that rendered
 // it, and an ordinary sampler — the two shadow bindings above are comparison.
 // params = (projA, projB, _, _) — the depth-linearisation pair of the SHARED
@@ -144,7 +145,7 @@ struct MirrorVP { viewProj: mat4x4f, params: vec4f, };
 struct MirrorClip { plane: vec4f, on: f32, _p0: f32, _p1: f32, _p2: f32, };
 @group(0) @binding(14) var<uniform> clip: MirrorClip;
 ${WORLD_AMBIENT_WGSL}
-${lightsApi(0, 6)}
+${lightsApi(0, 6, "1u")}
 
 struct VO { @builtin(position) position: vec4f, @location(0) worldPos: vec3f, @location(1) normal: vec3f, };
 @vertex fn vs(@location(0) position: vec3f, @location(1) normal: vec3f, @location(2) uv: vec2f) -> VO {
@@ -178,21 +179,6 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
     return out;
   }
 
-  // Outside a cascade's frustum there IS no shadow information — the clamped
-  // border samples compare against unrelated depths and read "shadowed",
-  // darkening the whole far plane with a visible band at the frustum edge
-  // (masked by the opaque surface normally, glaring in green-screen mode where
-  // only the shadow-catcher term renders). So each cascade fades out near its
-  // border — the near one INTO the far one's answer, the far one into lit.
-  let l0 = lightVP.viewProj[0] * vec4f(i.worldPos, 1.0);
-  let ndc = l0.xyz / max(l0.w, 1e-6);
-  let inZ = select(0.0, 1.0, ndc.z > 0.0 && ndc.z < 1.0);
-  let frustum = (1.0 - smoothstep(0.88, 0.96, abs(ndc.x))) * (1.0 - smoothstep(0.88, 0.96, abs(ndc.y))) * inZ;
-  let l1 = lightVP.viewProj[1] * vec4f(i.worldPos, 1.0);
-  let ndc1 = l1.xyz / max(l1.w, 1e-6);
-  let inZ1 = select(0.0, 1.0, ndc1.z > 0.0 && ndc1.z < 1.0);
-  let frustum1 = (1.0 - smoothstep(0.88, 0.96, abs(ndc1.x))) * (1.0 - smoothstep(0.88, 0.96, abs(ndc1.y))) * inZ1;
-
   // THE cost of this shader, measured: a full-screen ground ran 25 shadow
   // comparisons per pixel, and each one is hardware-bilinear, so ~100 depth
   // samples per pixel. Gutting the rest of the shader changed nothing; cutting
@@ -201,11 +187,9 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   // 3x3 at two-texel spacing covers the same +/-2 texel penumbra the 5x5 at
   // one-texel spacing did — that kernel was oversampled, its taps overlapping
   // almost entirely once the comparison sampler's own 2x2 filter is counted.
-  // Nine taps instead of twenty-five for the same blur radius.
+  // Nine taps instead of twenty-five for the same blur radius, and one
+  // cascade's worth per pixel: the first that holds it.
   //
-  // The far cascade's taps run ONLY where the near one is fading or absent
-  // (frustum < 1), so a pixel in the near core costs exactly what it did with
-  // one cascade — and that core is where the camera usually looks.
   // Can anything cast a shadow ONTO this point at all?
   //
   // The ground is vastly larger than what stands on it, and the answer for most
@@ -261,33 +245,26 @@ ${
   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
-  // cascade does not reach, and the near cascade is a 64-unit box around the
-  // camera target, so a floor receding to the horizon takes it almost
-  // everywhere. Nine comparison taps, per pixel, on the largest draw in the
-  // frame — against a map that is cleared unless a stage is in the scene.
-  //
-  // Cleared depth compares as "no occluder", so the skipped path leaves vis at
-  // 1.0, which is exactly what the taps returned. Free, not cheaper.
-  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 compareZ1 = ndc1.z - 0.0035;
-    var acc1 = 0.0;
-${pcfWgsl("shadowMapFar", "suv1_c", `${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize}`, "compareZ1", "acc1", "    ", soft)}
-    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));
+  // The first cascade whose box holds the point, as the materials pick it.
+  // Outside a cascade's box there IS no shadow information — the clamped
+  // border samples compare against unrelated depths and read "shadowed",
+  // darkening the far floor with a band at the edge — so the outermost one
+  // fades into lit near its border. Inner cascades hand over to the next.
+  let n = ${SHADOW_CASCADES.length}u;
+  for (var ci = 0u; ci < n; ci++) {
+    let lc = lightVP.viewProj[ci] * vec4f(i.worldPos, 1.0);
+    let ndc = lc.xyz / max(lc.w, 1e-6);
+    if (!(all(abs(ndc.xy) < vec2f(${SHADOW_MARGIN})) && ndc.z > 0.0 && ndc.z < 1.0)) { continue; }
+    let frustum = select(1.0, (1.0 - smoothstep(0.88, 0.96, abs(ndc.x))) * (1.0 - smoothstep(0.88, 0.96, abs(ndc.y))), ci == n - 1u);
+    let tile = vec2f(f32(ci % 2u), f32(ci / 2u)) * ${SHADOW_CASCADES[0].mapSize / SHADOW_ATLAS_SIZE};
+    let tileLo = tile + vec2f(${0.5 / SHADOW_ATLAS_SIZE});
+    let tileHi = tile + vec2f(${(SHADOW_CASCADES[0].mapSize - 0.5) / SHADOW_ATLAS_SIZE});
+    let suv = tile + vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5) * ${SHADOW_CASCADES[0].mapSize / SHADOW_ATLAS_SIZE};
     let compareZ = ndc.z - 0.0035;
     var acc = 0.0;
-${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ", soft)}
-    // 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, frustum);
+${pcfWgsl("shadowAtlas", "suv", `${1 / SHADOW_ATLAS_SIZE}`, "compareZ", "acc", "    ", soft)}
+    vis = mix(1.0, acc, frustum);
+    break;
   }
   }
 

package/src/shaders/passes/particles.ts

@@ -102,6 +102,15 @@ type ParticleSource = {
    *  where every stacked fragment is otherwise shaded in full; the prepass is
    *  the shape of that rejection, done by hand and cheaply. */
   cover: boolean
+  /** The effect defines `particleOrient(p: Particle, id: u32) -> mat3x3f`: the
+   *  quad lies along its first two columns (right, up) instead of facing the
+   *  camera. A card that belongs to a surface — a raindrop's glow on a window,
+   *  a sheet of water standing in its fall — is flat on that surface and turns
+   *  with it, not with the eye: Unity's Local and World render alignments. The
+   *  particle's rotation still turns the corners within that plane, and a
+   *  stretched particle stretches along its velocity projected into it. `id`
+   *  is the particle's slot, so the axes can come from its emitter. */
+  orient?: boolean
   /** The effect defines `particleCount() -> u32`: how many of the pool are
    *  live this frame, as a function of its dials. The step is dispatched and
    *  the quads drawn for that many slots and no more, through indirect
@@ -121,7 +130,7 @@ type ParticleSource = {
   textures?: number
 }
 
-/** Where the shading stage's five scene-light bindings start — see scene-light-api.ts. */
+/** Where the shading stage's four scene-light bindings start — see scene-light-api.ts. */
 export const PARTICLE_LIGHT_BINDING = 10
 /** The effect's named points (`#points`), in both stages — see points-api.ts. */
 export const PARTICLE_POINTS_BINDING = 15
@@ -196,8 +205,9 @@ fn rzCamPos() -> vec3f { return cam.camPos; }
 /** Does the source define the particle contract? All three are required
  *  together; `cover` is optional and only means anything to a cutout, and
  *  `count` is optional and bounds the frame's work — see particleCount. */
-export function particleEntryPoints(wgsl: string): { init: boolean; step: boolean; shade: boolean; cover: boolean; count: boolean } {
+export function particleEntryPoints(wgsl: string): { init: boolean; step: boolean; shade: boolean; cover: boolean; count: boolean; orient: boolean } {
   return {
+    orient: /\bfn\s+particleOrient\s*\(/.test(wgsl),
     init: /\bfn\s+particleInit\s*\(/.test(wgsl),
     step: /\bfn\s+particleStep\s*\(/.test(wgsl),
     shade: /\bfn\s+particleShade\s*\(/.test(wgsl),
@@ -372,9 +382,13 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
     out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
     return out;
   }
-  let right = vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]);
-  let up = vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]);
-  let s = sin(p.rot);
+  var right = vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]);
+  var up = vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]);
+${src.orient ? `  // the author's own plane (particleOrient): a card on a surface, not facing the eye
+  let o = particleOrient(p, ii);
+  right = o[0];
+  up = o[1];
+` : ""}  let s = sin(p.rot);
   let k = cos(p.rot);
   var r = vec2f(c.x * k - c.y * s, c.x * s + c.y * k);
   // Stretched along the direction of travel ON SCREEN — which is not the world

package/src/shaders/scene-light-api.ts

@@ -1,4 +1,4 @@
-import { SHADOW_CASCADES } from "../shadow-cascades"
+import { SHADOW_ATLAS_SIZE, SHADOW_CASCADES } from "../shadow-cascades"
 // The scene's own light, as an effect author sees it: the sun's shadow and the
 // world's ambient.
 //
@@ -51,31 +51,61 @@ fn rzWorldAmbientAvg() -> vec3f {
 `
 
 /**
- * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ * The sun's shadow atlas, as every reader looks it up: `<p>Locate(q)` finds
+ * world point q in the first cascade whose box holds it and answers
+ * (atlas uv, depth, cascade) — cascade -1 outside them all — and `<p>Taps(a)`
+ * is the 3×3 PCF at that place.
  *
- * 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.
+ * ONE implementation for the materials, the ground and effects, so a blade of
+ * grass and her own skin go dark at the same edge. `vp` names the cascades'
+ * view-projection array in the module that includes it.
+ *
+ * The box test keeps a margin (SHADOW_MARGIN of the tile's half-width) so the
+ * whole filter stays inside the tile: a tap that crossed into the neighbouring
+ * tile would compare against another cascade's depths. The sampler is linear,
+ * so each tap is itself a 2×2 compare. Unrolled — Safari's Metal backend
+ * doesn't unroll nested shadow loops reliably.
  */
-export const pcf9 = (map: string, ts: string, 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);
+export const SHADOW_MARGIN = 0.98
+
+export const sunShadowWgsl = (p: string, map: string, sampler: string, vp: string) => {
+  const n = SHADOW_CASCADES.length
+  const tiles = SHADOW_CASCADES.map((c) => `vec2f(${c.origin[0] / SHADOW_ATLAS_SIZE}, ${c.origin[1] / SHADOW_ATLAS_SIZE})`).join(", ")
+  const scale = SHADOW_CASCADES[0].mapSize / SHADOW_ATLAS_SIZE
+  return /* wgsl */ `
+const ${p}Tiles = array<vec2f, ${n}>(${tiles});
+
+fn ${p}Locate(q: vec3f) -> vec4f {
+  for (var i = 0u; i < ${n}u; i++) {
+    let c = ${vp}[i] * vec4f(q, 1.0);
+    let ndc = c.xyz / max(c.w, 1e-6);
+    if (all(abs(ndc.xy) < vec2f(${SHADOW_MARGIN})) && ndc.z > 0.0 && ndc.z < 1.0) {
+      let uv = ${p}Tiles[i] + vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5) * ${scale};
+      return vec4f(uv, ndc.z, f32(i));
+    }
+  }
+  return vec4f(0.0, 0.0, 0.0, -1.0);
+}
+
+fn ${p}Taps(a: vec4f) -> f32 {
+  let cmpZ = a.z - 0.001;
+  let ts = ${1 / SHADOW_ATLAS_SIZE};
+  let s00 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f(-ts, -ts), cmpZ);
+  let s10 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f(0.0, -ts), cmpZ);
+  let s20 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f( ts, -ts), cmpZ);
+  let s01 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f(-ts, 0.0), cmpZ);
+  let s11 = textureSampleCompareLevel(${map}, ${sampler}, a.xy, cmpZ);
+  let s21 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f( ts, 0.0), cmpZ);
+  let s02 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f(-ts,  ts), cmpZ);
+  let s12 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f(0.0,  ts), cmpZ);
+  let s22 = textureSampleCompareLevel(${map}, ${sampler}, a.xy + vec2f( ts,  ts), cmpZ);
   return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+}
 `
+}
 
 /** Bindings the real accessors take, from `binding` upward. */
-export const SCENE_LIGHT_API_BINDINGS = 5
+export const SCENE_LIGHT_API_BINDINGS = 4
 
 /**
  * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
@@ -84,12 +114,11 @@ export const SCENE_LIGHT_API_BINDINGS = 5
  * `rzWorldAmbient(n)`: the world's light arriving at a surface facing `n` —
  * the materials' own ambient, so an effect's shade can match hers.
  *
- * With `on`, declares five bindings from `binding`:
+ * With `on`, declares four bindings from `binding`:
  *   +0 the light uniform (ambient, the sun — direction, and in .w the shadow
  *      switch — and the HDRI's irradiance)
  *   +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
+ *   +2 the sun's shadow atlas   +3 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
@@ -114,17 +143,9 @@ struct _RzSceneLightU { ambientColor: vec4f, lights: array<_RzSceneLight, 4>, sh
 struct _RzShadowBlock { viewProj: array<mat4x4f, ${n}>, casters: vec4f, }
 @group(${group}) @binding(${binding}) var<uniform> _rzLight: _RzSceneLightU;
 @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")}
-}
+@group(${group}) @binding(${binding + 2}) var _rzShadowAtlas: texture_depth_2d;
+@group(${group}) @binding(${binding + 3}) var _rzShadowCmp: sampler_comparison;
+${sunShadowWgsl("_rzSun", "_rzShadowAtlas", "_rzShadowCmp", "_rzShadowVP.viewProj")}
 
 fn rzShadow(p: vec3f) -> f32 {
   // The scene's one shadow switch, on the sun — see sampleShadow.
@@ -142,18 +163,10 @@ fn rzShadow(p: vec3f) -> f32 {
     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;
+  let a = _rzSunLocate(p + toSun * 0.08);
+  // Outside every cascade there is no occlusion information: lit.
+  if (a.w < 0.0) { return 1.0; }
+  return mix(1.0, _rzSunTaps(a), castAmt);
 }
 ${worldAmbientWgsl("_rzLight")}`
 }