reze-engine 0.64.0 → 0.66.0

package/src/shaders/passes/outline.ts

@@ -73,14 +73,39 @@ struct VertexOutput {
   /** The triangle's own threshold, flat — see the material VertexOutput. The
    *  hull traces the body's faces, so it has to lose the same ones. */
   @location(2) @interpolate(flat) faceT: f32,
+  /** How much of a pixel-wide line this one really is (1 = all of it): a line
+   *  held at the minimum width fades by what it was short. */
+  @location(3) coverage: f32,
 };
 
+/**
+ * Half the frame height (engine units, at the subject) below which a line keeps
+ * its constant screen width; wider than that it thins as a world-size line.
+ * 12.5 = a frame 25 units tall — a full figure (an MMD model is ~20) with
+ * room around her.
+ *
+ * Not the game's own break (w = 1 game unit = 8 engine units). The game's
+ * near width is ~3× MMD's 2·edgeSize px; its world-size line comes down to
+ * MMD's width only at a full-figure framing, so that is where the break goes:
+ * close-ups and full figures keep today's width, and past that the game's rule
+ * holds — NDC offset ∝ 1/w, scaled by the zoom as its projection._m11 scales
+ * it. At the game's 8 the demo's own camera (33 units) drew a quarter of
+ * today's width, which put every line on the faded minimum.
+ */
+const RZ_OUTLINE_FULL_FIGURE = 12.5;
+/** The thinnest a line is drawn, in pixels at 1080p (and never under this many
+ *  device pixels). A line due to be thinner is drawn this wide and faded by
+ *  the shortfall, so far lines thin out without aliasing into dashes. */
+const RZ_OUTLINE_MIN_PX = 1.5;
+
 @vertex fn vs(
   @location(0) position: vec3f,
   @location(1) normal: vec3f,
   @location(2) uv: vec2f,
   @location(3) joints0: vec4<u32>,
-  @location(4) weights0: vec4<f32>
+  @location(4) weights0: vec4<f32>,
+  /** xyz: the smoothed rest normal (outline-normals.ts), w: PMX edge scale. */
+  @location(5) outlineNormal: vec4f
 ) -> VertexOutput {
   var output: VertexOutput;
   let pos4 = vec4f(position, 1.0);
@@ -97,30 +122,58 @@ struct VertexOutput {
     let m = skinMats[j];
     skinnedPos += (m * pos4) * w;
     let r3 = mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz);
-    skinnedNrm += (r3 * normal) * w;
+    skinnedNrm += (r3 * outlineNormal.xyz) * w;
   }
   let worldPos = skinnedPos.xyz;
   let worldNormal = normalize(skinnedNrm);
 
   let clipPos = camera.projection * camera.view * vec4f(worldPos, 1.0);
 
-  // babylon-mmd: screenNormal = normalize((view * worldNormal).xy)
+  // The push direction is the view-space normal's XY, NOT renormalized — the
+  // game's: full length at the silhouette, where the normal lies across the
+  // view, and shrinking on surfaces turned toward the camera, so creases
+  // facing her draw finer than the rim. Skinned exactly as the colour pass
+  // skins the normal, from the smoothed rest normal, so every vertex sharing a
+  // position pushes the same way and the hull stays closed over hard edges
+  // and UV seams.
   let viewNormal = (camera.view * vec4f(worldNormal, 0.0)).xyz;
-  let snLen = length(viewNormal.xy);
-  let screenNormal = select(vec2f(0.0, 0.0), viewNormal.xy / snLen, snLen > 1e-5);
 
   // Reference-height normalization (babylon-mmd ships this variant commented
-  // out as \`renderHeight = 1080\`): thickness is a constant FRACTION of the
-  // frame — 2·edgeSize px at 1080p — so retina DPR and 4K export don't thin
-  // the rims to sub-pixel. Width follows the projection aspect.
+  // out as \`renderHeight = 1080\`): the near width is a constant FRACTION of
+  // the frame — 2·edgeSize px at 1080p — so retina DPR and 4K export don't
+  // thin the rims to sub-pixel. Width follows the projection aspect.
   // projection[1][1]/projection[0][0] = width/height for a symmetric frustum.
   let aspect = camera.projection[1][1] / camera.projection[0][0];
-  let viewport = vec2f(1080.0 * aspect, 1080.0);
+  let refViewport = vec2f(1080.0 * aspect, 1080.0);
+  let deviceViewport = vec2f(camera.viewportHeight * aspect, camera.viewportHeight);
+
+  // The game's width (Character/Debug.shader, pass "Outline"): the clip offset
+  // is the near offset × min(w, break depth). Up close the ×w cancels the
+  // perspective divide — constant screen width; past the break it stops
+  // growing, so the NDC offset falls as 1/w like a line of fixed world width.
+  // The break is the depth at which the frame is a full figure tall, so a
+  // zoomed lens moves it out (see RZ_OUTLINE_FULL_FIGURE). Under an
+  // orthographic camera w is 1 and the same min() makes the line world-size
+  // once the frame is taller than a figure. The PMX per-vertex edge scale
+  // multiplies it all, as vertex colour alpha does in the game.
+  let w = max(clipPos.w, 1e-4);
+  let breakDepth = RZ_OUTLINE_FULL_FIGURE * camera.projection[1][1];
+  let nearNdc = viewNormal.xy * (material.edgeSize * outlineNormal.w * 4.0 / refViewport);
+  var ndc = nearNdc * (min(w, breakDepth) / w);
 
-  // NDC offset = edgeSize · 4/viewport, ×w so the perspective divide cancels:
-  // constant screen thickness at any distance (babylon-mmd parity).
-  let offset = screenNormal * (material.edgeSize * 4.0 / viewport) * clipPos.w;
-  output.position = vec4f(clipPos.xy + offset, clipPos.z, clipPos.w);
+  // Antialiased minimum (the game's _OutlineAntialias): held at the minimum
+  // width and faded by the shortfall, never thinner. The game fades by
+  // sqrt(coverage.x · coverage.y), per axis; for one width that is the ratio
+  // itself.
+  let px = length(ndc * deviceViewport * 0.5);
+  let minPx = RZ_OUTLINE_MIN_PX * max(1.0, camera.viewportHeight / 1080.0);
+  var coverage = 1.0;
+  if (px < minPx) {
+    coverage = px / minPx;
+    ndc = select(vec2f(0.0), ndc * (minPx / px), px > 1e-6);
+  }
+  output.coverage = coverage;
+  output.position = vec4f(clipPos.xy + ndc * w, clipPos.z, clipPos.w);
   output.uv = uv;
   output.restPos = position;
   output.faceT = rz_dissolve_threshold(position);
@@ -155,7 +208,11 @@ ${sceneFsOutWgsl({ name: "FSOut", aux: "mask" })}
     discard;
   }
   var out: FSOut;
-  out.color = vec4f(material.edgeColor.rgb, material.edgeColor.a * texA);
+  // Blended, not alpha-to-coverage: this pass already blends (the texture
+  // alpha above), it is drawn right after the surface it traces so what lies
+  // under a faded line is already there, and 4× MSAA would quantize a fade to
+  // four steps.
+  out.color = vec4f(material.edgeColor.rgb, material.edgeColor.a * texA * input.coverage);
   out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
 ${sceneIdPadWgsl("out")}  return out;
 }

package/src/shaders/passes/particles.ts

@@ -388,9 +388,15 @@ ${src.orient ? `  // the author's own plane (particleOrient): a card on a surfac
   let o = particleOrient(p, ii);
   right = o[0];
   up = o[1];
-` : ""}  let s = sin(p.rot);
+` : ""}${/\bfn\s+particlePivot\s*\(/.test(src.wgsl) ? `  // the card's pivot (particlePivot, in half-size units of the quad): the
+  // corners are offset by it BEFORE the turn, so the card turns about its
+  // pivot rather than its centre — Unity's renderer pivot, a lighthouse beam
+  // whose card starts at the lamp instead of straddling it
+  let cp = c + particlePivot(p, ii);
+` : `  let cp = c;
+`}  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);
+  var r = vec2f(cp.x * k - cp.y * s, cp.x * s + cp.y * k);
   // Stretched along the direction of travel ON SCREEN — which is not the world
   // direction once the camera is off-axis. Rain falling straight down is nearly
   // a point when viewed from above and a long streak from the side, and taking
@@ -402,7 +408,7 @@ ${src.orient ? `  // the author's own plane (particleOrient): a card on a surfac
     let vlen = length(vec2f(vr, vu));
     if (vlen > 1e-5) {
       let d = vec2f(vr, vu) / vlen;
-      r = vec2f(d.y, -d.x) * c.x + d * (c.y * p.stretch);
+      r = vec2f(d.y, -d.x) * cp.x + d * (cp.y * p.stretch);
     }
   }
   let world = p.pos + (right * r.x + up * r.y) * p.size;

package/src/shaders/passes/probe.ts

@@ -0,0 +1,240 @@
+// The reflection probe's GPU passes, and the sky's prefilter.
+//
+// A game does not reflect the sky alone: it bakes a cube of the stage itself
+// from somewhere in the middle of it, prefilters it down its mips with the
+// specular lobe, and every surface reads it box-projected onto the stage's
+// bounds. The engine does the same once a stage has loaded (Engine:
+// captureReflectionProbe): six renders of the stage into a 128² cube, the
+// sky laid in wherever nothing was drawn, a mip chain, then a GGX convolution
+// into the 64² cube the materials sample (rzProbeSpecular in nodes.ts).
+//
+// The world's sky gets the same convolution down its equirect mips, in place
+// of the box average they were built from.
+
+import { NODES_WGSL } from "../materials/nodes"
+import { COMMON_MATERIAL_PRELUDE_WGSL, DISSOLVE_WGSL } from "../materials/common"
+
+/** Face size of the capture, and of the cube the materials read. The game
+ *  bakes 64²; the capture is twice that so the base level is antialiased. */
+export const PROBE_CAPTURE_SIZE = 128
+export const PROBE_SIZE = 64
+/** 64² down to 1²: seven levels, the game's own count. */
+export const PROBE_LEVELS = 7
+export const PROBE_CAPTURE_LEVELS = 8
+
+/**
+ * The perceptual roughness level m of the probe was convolved with, on
+ * Unity's probe curve: m = r·(1.7 − 0.7r)·6 (UNITY_SPECCUBE_LOD_STEPS), the
+ * convention the game's baked probes follow and its lookup (×8, clamped at 6)
+ * reads against. Level 0 is the unblurred capture.
+ */
+export function probeLevelRoughness(level: number): number {
+  if (level <= 0) return 0
+  const m = Math.min(level, 6)
+  return Math.min((10.2 - Math.sqrt(Math.max(104.04 - 16.8 * m, 0))) / 8.4, 1)
+}
+
+/**
+ * The perceptual roughness level m of the sky's equirect chain was convolved
+ * with: the engine's own lookup is lod = sqrt(r)·(levels − 1), so level m is
+ * r = (m / (levels − 1))².
+ */
+export function skyLevelRoughness(level: number, levels: number): number {
+  if (level <= 0 || levels <= 1) return 0
+  const t = level / (levels - 1)
+  return Math.min(t * t, 1)
+}
+
+/** A cube face's direction for a uv on it (uv.y down), in the convention the
+ *  GPU samples a cube with — the same one the capture cameras render. */
+const FACE_DIR_WGSL = /* wgsl */ `
+fn rz_face_dir(face: u32, uv: vec2f) -> vec3f {
+  let s = uv.x * 2.0 - 1.0;
+  let t = uv.y * 2.0 - 1.0;
+  switch face {
+    case 0u: { return normalize(vec3f(1.0, -t, -s)); }
+    case 1u: { return normalize(vec3f(-1.0, -t, s)); }
+    case 2u: { return normalize(vec3f(s, 1.0, t)); }
+    case 3u: { return normalize(vec3f(s, -1.0, -t)); }
+    case 4u: { return normalize(vec3f(s, -t, 1.0)); }
+    default: { return normalize(vec3f(-s, -t, -1.0)); }
+  }
+}
+
+struct RzFullOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f };
+
+@vertex fn vs_full(@builtin(vertex_index) i: u32) -> RzFullOut {
+  var o: RzFullOut;
+  let x = f32(i32(i / 2u) * 4 - 1);
+  let y = f32(i32(i % 2u) * 4 - 1);
+  o.pos = vec4f(x, y, 0.0, 1.0);
+  o.uv = vec2f(x * 0.5 + 0.5, 0.5 - y * 0.5);
+  return o;
+}
+`
+
+/** GGX importance sampling, the filtered kind (Křivánek & Colbert): each
+ *  sample reads the source at the mip whose texel matches its solid angle, so
+ *  a few dozen taps integrate a wide lobe without the fireflies a point sample
+ *  of a bright lamp would leave. */
+const GGX_SAMPLING_WGSL = /* wgsl */ `
+fn rz_hammersley(i: u32, n: u32) -> vec2f {
+  var b = (i << 16u) | (i >> 16u);
+  b = ((b & 0x55555555u) << 1u) | ((b & 0xAAAAAAAAu) >> 1u);
+  b = ((b & 0x33333333u) << 2u) | ((b & 0xCCCCCCCCu) >> 2u);
+  b = ((b & 0x0F0F0F0Fu) << 4u) | ((b & 0xF0F0F0F0u) >> 4u);
+  b = ((b & 0x00FF00FFu) << 8u) | ((b & 0xFF00FF00u) >> 8u);
+  return vec2f(f32(i) / f32(n), f32(b) * 2.3283064365386963e-10);
+}
+
+/** A half vector about N for the lobe at alpha = a (= perceptual r²). */
+fn rz_ggx_half(xi: vec2f, N: vec3f, a: f32) -> vec3f {
+  let phi = 6.283185307 * xi.x;
+  let cosT = sqrt((1.0 - xi.y) / (1.0 + (a * a - 1.0) * xi.y));
+  let sinT = sqrt(max(1.0 - cosT * cosT, 0.0));
+  let h = vec3f(sinT * cos(phi), sinT * sin(phi), cosT);
+  let up = select(vec3f(1.0, 0.0, 0.0), vec3f(0.0, 0.0, 1.0), abs(N.z) < 0.999);
+  let tx = normalize(cross(up, N));
+  let ty = cross(N, tx);
+  return normalize(tx * h.x + ty * h.y + N * h.z);
+}
+
+fn rz_ggx_d(nh: f32, a: f32) -> f32 {
+  let a2 = a * a;
+  let d = nh * nh * (a2 - 1.0) + 1.0;
+  return a2 / (3.141592653589793 * d * d);
+}
+`
+
+/**
+ * The compose step: the stage as captured, with the world's sky laid in
+ * behind it wherever the capture's coverage says nothing was drawn — an open
+ * stage reflects its sky, an interior its walls. Built on the material
+ * prelude for rzWorldSpecularLod, which knows every kind of sky the scene may
+ * have (an HDRI, a gradient, one colour). Only the bindings it reads end up in
+ * its layout ("auto"): the light uniform, the sampler and the sky at group 0,
+ * and its own three past the material set's.
+ */
+export const PROBE_COMPOSE_WGSL =
+  NODES_WGSL +
+  COMMON_MATERIAL_PRELUDE_WGSL +
+  DISSOLVE_WGSL +
+  FACE_DIR_WGSL +
+  /* wgsl */ `
+struct RzProbeStep { face: u32, lod: f32, roughness: f32, srcSize: f32 };
+@group(0) @binding(20) var rzCaptureColor: texture_2d_array<f32>;
+@group(0) @binding(21) var rzCaptureAux: texture_2d_array<f32>;
+@group(0) @binding(22) var<uniform> rzStep: RzProbeStep;
+
+@fragment fn fs_compose(in: RzFullOut) -> @location(0) vec4f {
+  let size = textureDimensions(rzCaptureColor);
+  let px = vec2u(min(in.pos.xy, vec2f(size) - vec2f(1.0)));
+  let c = textureLoad(rzCaptureColor, px, rzStep.face, 0).rgb;
+  let cover = saturate(textureLoad(rzCaptureAux, px, rzStep.face, 0).g);
+  let sky = rzWorldSpecularLod(rz_face_dir(rzStep.face, in.uv), 0.0, 0.0);
+  return vec4f(c + sky * (1.0 - cover), 1.0);
+}
+`
+
+/**
+ * The cube's own passes: a mip from the level above (mode 0 — one bilinear
+ * tap at the child texel's direction is the 2×2 average), and the GGX
+ * convolution into the probe the materials read (mode 1).
+ */
+export const PROBE_FILTER_WGSL =
+  FACE_DIR_WGSL +
+  GGX_SAMPLING_WGSL +
+  /* wgsl */ `
+struct RzProbeStep { face: u32, lod: f32, roughness: f32, srcSize: f32, mode: u32 };
+@group(0) @binding(0) var rzSrc: texture_cube<f32>;
+@group(0) @binding(1) var rzSamp: sampler;
+@group(0) @binding(2) var<uniform> rzStep: RzProbeStep;
+
+const RZ_PROBE_SAMPLES: u32 = 128u;
+
+@fragment fn fs_filter(in: RzFullOut) -> @location(0) vec4f {
+  let N = rz_face_dir(rzStep.face, in.uv);
+  let r = rzStep.roughness;
+  if (rzStep.mode == 0u || r < 0.002) {
+    return vec4f(textureSampleLevel(rzSrc, rzSamp, N, rzStep.lod).rgb, 1.0);
+  }
+  let a = r * r;
+  let texelSolid = 4.0 * 3.141592653589793 / (6.0 * rzStep.srcSize * rzStep.srcSize);
+  let maxLod = f32(textureNumLevels(rzSrc) - 1u);
+  var sum = vec3f(0.0);
+  var weight = 0.0;
+  for (var i = 0u; i < RZ_PROBE_SAMPLES; i++) {
+    let H = rz_ggx_half(rz_hammersley(i, RZ_PROBE_SAMPLES), N, a);
+    let L = 2.0 * dot(N, H) * H - N;
+    let nl = dot(N, L);
+    if (nl <= 0.0) { continue; }
+    // N = V: the pdf over L is D·(N·H)/(4·V·H) = D/4.
+    let pdf = rz_ggx_d(saturate(dot(N, H)), a) * 0.25;
+    let sampleSolid = 1.0 / (f32(RZ_PROBE_SAMPLES) * pdf + 1e-6);
+    let lod = clamp(0.5 * log2(sampleSolid / texelSolid) + 1.0, 0.0, maxLod);
+    sum += textureSampleLevel(rzSrc, rzSamp, L, lod).rgb * nl;
+    weight += nl;
+  }
+  return vec4f(sum / max(weight, 1e-4), 1.0);
+}
+`
+
+/**
+ * The sky's mips, convolved: level m of the equirect the materials read
+ * (rzWorldSpecularLod) becomes the GGX-filtered sky at the roughness that
+ * level stands for, sampled from the box-averaged chain the upload built.
+ * Directions follow the composite's dome: u = 0.5 + atan2(x, z)/2π,
+ * v = 0.5 − asin(y)/π.
+ */
+export const SKY_PREFILTER_WGSL =
+  GGX_SAMPLING_WGSL +
+  /* wgsl */ `
+struct RzFullOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f };
+
+@vertex fn vs_full(@builtin(vertex_index) i: u32) -> RzFullOut {
+  var o: RzFullOut;
+  let x = f32(i32(i / 2u) * 4 - 1);
+  let y = f32(i32(i % 2u) * 4 - 1);
+  o.pos = vec4f(x, y, 0.0, 1.0);
+  o.uv = vec2f(x * 0.5 + 0.5, 0.5 - y * 0.5);
+  return o;
+}
+
+struct RzSkyStep { roughness: f32, srcWidth: f32, srcHeight: f32, spare: f32 };
+@group(0) @binding(0) var rzSky: texture_2d<f32>;
+@group(0) @binding(1) var rzSamp: sampler;
+@group(0) @binding(2) var<uniform> rzStep: RzSkyStep;
+
+const RZ_SKY_SAMPLES: u32 = 64u;
+
+fn rz_sky_dir(uv: vec2f) -> vec3f {
+  let phi = (uv.x - 0.5) * 6.283185307;
+  let lat = (0.5 - uv.y) * 3.141592653589793;
+  return vec3f(cos(lat) * sin(phi), sin(lat), cos(lat) * cos(phi));
+}
+
+fn rz_sky_uv(d: vec3f) -> vec2f {
+  return vec2f(0.5 + atan2(d.x, d.z) * 0.15915494309, 0.5 - asin(clamp(d.y, -1.0, 1.0)) * 0.31830988618);
+}
+
+@fragment fn fs_sky(in: RzFullOut) -> @location(0) vec4f {
+  let N = rz_sky_dir(in.uv);
+  let a = rzStep.roughness * rzStep.roughness;
+  let texelSolid = 4.0 * 3.141592653589793 / (rzStep.srcWidth * rzStep.srcHeight);
+  let maxLod = f32(textureNumLevels(rzSky) - 1u);
+  var sum = vec3f(0.0);
+  var weight = 0.0;
+  for (var i = 0u; i < RZ_SKY_SAMPLES; i++) {
+    let H = rz_ggx_half(rz_hammersley(i, RZ_SKY_SAMPLES), N, a);
+    let L = 2.0 * dot(N, H) * H - N;
+    let nl = dot(N, L);
+    if (nl <= 0.0) { continue; }
+    let pdf = rz_ggx_d(saturate(dot(N, H)), a) * 0.25;
+    let sampleSolid = 1.0 / (f32(RZ_SKY_SAMPLES) * pdf + 1e-6);
+    let lod = clamp(0.5 * log2(sampleSolid / texelSolid) + 1.0, 0.0, maxLod);
+    sum += textureSampleLevel(rzSky, rzSamp, rz_sky_uv(L), lod).rgb * nl;
+    weight += nl;
+  }
+  return vec4f(sum / max(weight, 1e-4), 1.0);
+}
+`

package/src/shaders/passes/scene-contract.ts

@@ -98,6 +98,12 @@ type SceneRenderClass =
    *  X309's night sky was. Out of WRITES_ID for the mirror's reason — a sheet of
    *  light is not an object anything should be able to pick or outline. */
   | "material-additive"
+  /** A material whose colour arrives ALREADY weighted by its coverage — a
+   *  game's glass (Blend One OneMinusSrcAlpha): the pane's diffuse fades with
+   *  its alpha while its reflection does not, which a src-alpha blend cannot
+   *  express. Out of WRITES_ID for the mirror's reason: a window is not what a
+   *  click on the figure behind it means. */
+  | "material-premultiplied"
   /** Particles and ribbons in their default, non-additive mode. */
   | "particle"
   /** Particles declaring `#blend additive` — LIGHT rather than matter, so
@@ -110,6 +116,13 @@ type SceneRenderClass =
    *  whole, and an ordinary alpha-over aux so a ribbon's mask does not
    *  saturate along every overlap. */
   | "trail"
+  /** Ribbons declaring `#blend over` — MATTER rather than light: laid over
+   *  what is behind them by their own alpha, the way a game's trail material
+   *  with Blend One OneMinusSrcAlpha draws. A dark band then darkens, which an
+   *  additive ribbon can never do; it is how a deep-blue smoke tail reads as a
+   *  tail at all. The fragment writes straight colour, so the colour blend is
+   *  src-alpha like any other alpha-over class. */
+  | "trail-over"
   /** The transparent depth prepass: it exists to write DEPTH after the fabric's
    *  colour blended, so an outline drawn later is occluded behind it. It must
    *  therefore write no colour at all — the targets exist only to make the
@@ -183,6 +196,9 @@ const BLENDS: Record<Exclude<SceneRenderClass, "depth-prepass">, [GPUBlendState,
   // The same pair the additive particles use: light into the colour target, and
   // coverage that still accumulates so bloom and the composite can see it.
   "material-additive": [ADD_KEEP_ALPHA, ADD_BOTH],
+  // The colour premultiplied by the graph (game_pbr's glass); the aux is
+  // written straight, as every material's is.
+  "material-premultiplied": [PREMULTIPLIED_OVER, ALPHA_OVER],
   // PREMULTIPLIED, like the ground and for the same reason: what a mirror
   // writes is a sample of the HDR target, and that target already holds colour
   // premultiplied by its own alpha. Handed to the src-alpha blend it would be
@@ -201,6 +217,7 @@ const BLENDS: Record<Exclude<SceneRenderClass, "depth-prepass">, [GPUBlendState,
   particle: [PREMULTIPLIED_OVER, ALPHA_OVER],
   "particle-additive": [ADD_KEEP_ALPHA, ADD_BOTH],
   trail: [ADD_PREMULTIPLIED, ALPHA_OVER],
+  "trail-over": [ALPHA_OVER, ALPHA_OVER],
 }
 
 /**

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

@@ -131,6 +131,7 @@ export function sceneLightApi(on: boolean, group: number, binding: number): stri
     return /* wgsl */ `
 fn rzShadow(p: vec3f) -> f32 { return 1.0; }
 fn rzWorldAmbient(n: vec3f) -> vec3f { return vec3f(0.0); }
+fn rzWorldAmbientAvg() -> vec3f { return vec3f(0.0); }
 `
   }
   const n = SHADOW_CASCADES.length

package/src/unity/globals.ts

@@ -71,6 +71,9 @@ export type UnityFrameInput = {
   /** The direction the main light travels, unit; null for none. */
   sunDirection: [number, number, number] | null
   sunColor: [number, number, number]
+  /** A game stage's own main light as its pipeline packed it (recorded), which
+   *  its shaders get in place of sunColor; null for the scene sun's. */
+  sunUnity?: { color: number[]; simColor: number[]; simColorNoInt: number[] } | null
   sunShadow: number
   lights: UnityLight[]
   /** Ambient as the engine's folded SH9 (27 floats, ibl.ts), or null for flat. */
@@ -257,12 +260,13 @@ export function unityFrameGlobals(f: UnityFrameInput): Record<string, NativeValu
   if (f.sunDirection) {
     const d = gameDir(f.sunDirection)
     g.SimMainLightDir = [-d[0], -d[1], -d[2], 0]
-    g.SimMainLightColor = [...f.sunColor, 1]
-    g.SimMainLightColorNoInt = [...f.sunColor, 1]
+    const u = f.sunUnity
+    g.SimMainLightColor = u ? u.simColor.slice(0, 4) : [...f.sunColor, 1]
+    g.SimMainLightColorNoInt = u ? u.simColorNoInt.slice(0, 4) : [...f.sunColor, 1]
     // As the game's pipeline leaves it (recorded): the way the light travels.
     g._MainLightPosition = [d[0], d[1], d[2], 0]
     g.sim_ShadowLightDirection = [-d[0], -d[1], -d[2], 0]
-    g._MainLightColor = [...f.sunColor, 1]
+    g._MainLightColor = u ? u.color.slice(0, 4) : [...f.sunColor, 1]
   } else {
     g.SimMainLightDir = [0, 0, 0, 0]
     g.SimMainLightColor = [0, 0, 0, 0]

package/src/unity/host.ts

@@ -54,6 +54,21 @@ export type NativeValue = number | ArrayLike<number> | ArrayLike<ArrayLike<numbe
 /** Name -> value; the first source that has a name wins. */
 export type ValueSource = Record<string, NativeValue | undefined>
 
+/** Whether two values carry the same numbers (and the same integer-ness). */
+export function sameValue(a: NativeValue, b: NativeValue): boolean {
+  if (typeof a === "number" || typeof b === "number") return a === b
+  if (a.length !== b.length) return false
+  if (a instanceof Uint32Array !== b instanceof Uint32Array) return false
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i] as number | ArrayLike<number>
+    const y = b[i] as number | ArrayLike<number>
+    if (typeof x === "number" || typeof y === "number") {
+      if (x !== y) return false
+    } else if (!sameValue(x, y)) return false
+  }
+  return true
+}
+
 /** One vertex stream a draw binds, by the semantic a shader input names. */
 export type NativeStream = {
   buffer: GPUBuffer
@@ -87,14 +102,25 @@ export function wrapFragment(frag: string, ids: boolean): string {
   const at = frag.lastIndexOf("@fragment")
   if (at < 0) throw new Error("native shader: no fragment entry point")
   const head = frag.slice(at)
-  const sig = /->\s*@location\(0\)\s*vec4<f32>\s*\{/
-  if (!sig.test(head)) throw new Error("native shader: the fragment entry does not return one vec4 target")
+  // A target narrower than four channels (a float3 SV_Target) leaves the rest
+  // unwritten: widened here with zeros and an alpha of one.
+  const sig = /->\s*@location\(0\)\s*(vec4<f32>|vec3<f32>|vec2<f32>|f32)\s*\{/
+  const kind = sig.exec(head)?.[1]
+  if (!kind) throw new Error("native shader: the fragment entry does not return one float target")
   let body = head.replace(sig, "-> RzNativeOut {")
   const ret = /return\s+(_e\d+)\s*;\s*\}\s*$/
   const m = ret.exec(body)
   if (!m) throw new Error("native shader: the fragment entry's return is not the translator's")
-  const v = m[1]
-  body = body.replace(ret, `return RzNativeOut(${v}, vec4f(1.0, 1.0, 0.0, ${v}.a)${ids ? ", vec2u(0u)" : ""});\n}\n`)
+  const e = m[1]
+  const v =
+    kind === "vec4<f32>"
+      ? e
+      : kind === "vec3<f32>"
+        ? `vec4f(${e}, 1.0)`
+        : kind === "vec2<f32>"
+          ? `vec4f(${e}, 0.0, 1.0)`
+          : `vec4f(${e}, 0.0, 0.0, 1.0)`
+  body = body.replace(ret, `let rzColor = ${v};\n  return RzNativeOut(rzColor, vec4f(1.0, 1.0, 0.0, rzColor.a)${ids ? ", vec2u(0u)" : ""});\n}\n`)
   const struct = `struct RzNativeOut {\n  @location(0) color: vec4f,\n  @location(1) mask: vec4f,\n${ids ? "  @location(2) id: vec2u,\n" : ""}};\n`
   // After the module's directives (diagnostic, enable): WGSL wants them first.
   const pre = frag.slice(0, at)
@@ -173,6 +199,8 @@ export type NativeDraw = {
 export class NativeHost {
   private prepared = new Map<string, Prepared>()
   private pipelines = new Map<string, { pipeline: GPURenderPipeline; stencilRef: number } | null>()
+  /** Pipelines being compiled (see warm). */
+  private pending = new Map<string, Promise<void>>()
   private draws = new Map<string, DrawCache>()
   private shared = new Map<string, Block>()
   private frame = 0
@@ -188,6 +216,7 @@ export class NativeHost {
       white: GPUTextureView
       black: GPUTextureView
       blackCube: GPUTextureView
+      emptyVolume: GPUTextureView
       depth: GPUTextureView
       comparison: GPUSampler
     },
@@ -281,9 +310,58 @@ export class NativeHost {
       : []
   }
 
+  private pipelineKey(p: Prepared, state: PassState, streams: NativeStream[]): string {
+    return `${p.shader.name}|${JSON.stringify(state)}|${streams.map((s) => `${s.format}/${s.stride}`).join(",")}`
+  }
+
+  /**
+   * Compile a draw's pipeline ahead of the draw — what a stage or a look calls
+   * for every pass it will draw, the moment it knows the shader, the state and
+   * the streams. Async: a synchronous build holds the GPU process for the
+   * whole compile, which was a one-to-two-second frozen frame at the first
+   * draw of each new shader. Resolves when the pipeline is ready or has
+   * failed (into `errors`); never rejects.
+   */
+  warm(shader: string, state: PassState, streams: NativeStream[]): Promise<void> {
+    const p = this.prepared.get(shader)
+    if (!p) return Promise.resolve()
+    const key = this.pipelineKey(p, state, streams)
+    if (this.pipelines.has(key)) return Promise.resolve()
+    let job = this.pending.get(key)
+    if (job) return job
+    let built: { desc: GPURenderPipelineDescriptor; stencilRef: number }
+    try {
+      built = this.describe(p, state, streams)
+    } catch (e) {
+      this.errors.push(`pipeline ${p.shader.name}: ${(e as Error).message}`)
+      this.pipelines.set(key, null)
+      return Promise.resolve()
+    }
+    job = this.device.createRenderPipelineAsync(built.desc).then(
+      (pipeline) => {
+        this.pipelines.set(key, { pipeline, stencilRef: built.stencilRef })
+        this.pending.delete(key)
+      },
+      (e) => {
+        this.errors.push(`pipeline ${p.shader.name}: ${(e as Error).message}`)
+        this.pipelines.set(key, null)
+        this.pending.delete(key)
+      },
+    )
+    this.pending.set(key, job)
+    return job
+  }
+
+  /** The draw's pipeline if it is ready. Never built here: one that is not
+   *  ready is started and the draw sits this frame out. */
   private pipeline(p: Prepared, state: PassState, streams: NativeStream[]) {
-    const key = `${p.shader.name}|${JSON.stringify(state)}|${streams.map((s) => s.format).join(",")}`
-    if (this.pipelines.has(key)) return this.pipelines.get(key)!
+    const ready = this.pipelines.get(this.pipelineKey(p, state, streams))
+    if (ready !== undefined) return ready
+    void this.warm(p.shader.name, state, streams)
+    return null
+  }
+
+  private describe(p: Prepared, state: PassState, streams: NativeStream[]): { desc: GPURenderPipelineDescriptor; stencilRef: number } {
     const t = this.targets
     const stencil = stencilState(state)
     const blend = blendState(state)
@@ -317,10 +395,8 @@ export class NativeHost {
         ]
     if (t.colorFormats[2]) targets.push({ format: t.colorFormats[2], writeMask: 0 })
     const offset = state.Offset
-    let result: { pipeline: GPURenderPipeline; stencilRef: number } | null
-    try {
-      result = {
-        pipeline: this.device.createRenderPipeline({
+    return {
+      desc: {
           label: `${p.shader.name} pipeline`,
           layout: p.layout,
           vertex: {
@@ -367,15 +443,9 @@ export class NativeHost {
               : {}),
           },
           multisample: { count: t.sampleCount },
-        }),
-        stencilRef: stencil?.ref ?? 0,
-      }
-    } catch (e) {
-      this.errors.push(`pipeline ${p.shader.name}: ${(e as Error).message}`)
-      result = null
+      },
+      stencilRef: stencil?.ref ?? 0,
     }
-    this.pipelines.set(key, result)
-    return result
   }
 
   private lookup(name: string, sources: ValueSource[]): NativeValue | undefined {
@@ -555,14 +625,17 @@ export class NativeHost {
     if (!samplers) return this.sampler
     const bare = name.replace(/^sampler_?/, "")
     const tex = info.bindings[bare] ? bare : info.bindings[`_${bare}`] ? `_${bare}` : bare
-    return samplers[tex] ?? this.sampler
+    return samplers[tex] ?? samplers[tex.replace(/_+$/, "")] ?? this.sampler
   }
 
   private textureView(name: string, type: string, textures: Record<string, GPUTextureView | undefined>): GPUTextureView {
-    const v = textures[name]
+    // naga renames a binding that ends in a digit with a trailing "_", as it
+    // does a member (lookupFrom): _AlbedoTex_1 is declared _AlbedoTex_1_
+    const v = textures[name] ?? (name.endsWith("_") ? textures[name.replace(/_+$/, "")] : undefined)
     if (v) return v
     if (/texture_depth/.test(type)) return this.fallback.depth
     if (/texture_cube/.test(type)) return this.fallback.blackCube
+    if (/texture_3d/.test(type)) return this.fallback.emptyVolume
     return this.fallback.white
   }