reze-engine 0.42.3 → 0.50.0

package/src/graph/registry.ts

@@ -8,7 +8,7 @@ import type { SocketValue } from "./schema"
 
 export type SockT = "float" | "color" | "vector" | "vec4"
 
-export type InputSpec = {
+type InputSpec = {
   type: SockT
   default?: SocketValue
   /** Socket is meaningless as a literal (e.g. the color being processed) — must be linked. */
@@ -32,7 +32,7 @@ export type NodeSpec = {
 // Deterministic: same graph JSON → byte-identical WGSL. String(x) is JS shortest
 // round-trip, so full-precision Blender constants (0.15000000596046448) survive.
 
-export function fmtFloat(x: number): string {
+function fmtFloat(x: number): string {
   if (!Number.isFinite(x)) throw new Error(`non-finite literal: ${x}`)
   const s = String(x)
   return /[.e]/.test(s) ? s : s + ".0"

package/src/graph/slots.ts

@@ -8,7 +8,8 @@
 // See docs/style-groups-spec.md §5, §7.
 
 import { NODES_WGSL } from "../shaders/materials/nodes"
-import { COMMON_MATERIAL_PRELUDE_WGSL } from "../shaders/materials/common"
+import { COMMON_MATERIAL_PRELUDE_WGSL, commonFsOutWgsl } from "../shaders/materials/common"
+import { sceneIdWriteWgsl } from "../shaders/passes/scene-contract"
 import type { AlphaMode, RenderClass } from "./render-class"
 
 // ── Module-scope declarations ──
@@ -58,7 +59,7 @@ const EYE_REAR_GATE = `
 
 // ── Adjust-tier uniforms — fixed 16-vec4f block (256 B) shared by the single material
 // bind group layout; non-graph draws bind a zero buffer. ──
-export const STYLE_UNIFORMS_WGSL = `struct StyleUniforms { p: array<vec4f, 16> };
+const STYLE_UNIFORMS_WGSL = `struct StyleUniforms { p: array<vec4f, 16> };
 @group(2) @binding(4) var<uniform> style: StyleUniforms;
 
 `
@@ -96,7 +97,9 @@ ${discard}
 ${gate}
   let l = -light.lights[0].direction.xyz;
   let sun = light.lights[0].color.xyz * light.lights[0].color.w;
-  let amb = light.ambientColor.xyz;
+  // The world: flat colour, or the HDRI's irradiance at this normal — which
+  // is what makes a loaded sky actually light her instead of only backing her.
+  let amb = rzWorldAmbient(n);
   let shadow = sampleShadow(input.worldPos, n);
   let tex_color = tex_s.rgb;
 
@@ -108,20 +111,41 @@ ${gate}
 // pass when IS_OVER_EYES is compiled true.
 function epilogue(renderClass: RenderClass, alphaMode: AlphaMode): string {
   const alphaBase = alphaMode === "hashed" ? "1.0" : "alpha"
+  // Empty while ids are off, so the epilogue is exactly what it was. The values
+  // ride in the per-draw material uniform (see MaterialUniforms), which is what
+  // keeps this working through the indirect-draw path.
+  const ID_WRITE = sceneIdWriteWgsl("out", "u32(material.materialId)", "u32(material.objectId)")
+  // The positional lights, ADDED to whatever the graph decided and tinted by
+  // the surface's own texture colour — a red lamp on a blue dress must not wash
+  // it toward white. Deliberately outside the graph: this layer does not
+  // re-ramp, because two ramped terminators crossing a cheek read as plastic.
+  //
+  // With no lights rzLightsDiffuse returns exactly zero and its loop never
+  // runs, so every scene that declares none renders bit-for-bit as it did
+  // before lights existed. That is the property this whole feature is gated on.
+  // Modulated by `albedo`, a named local that TODAY is exactly tex_color — the
+  // raw texture. That is an approximation with a known failure: a graph that
+  // recolours a surface is lit by a colour it no longer shows. The local exists
+  // so the fix has an address — when graphs gain an optional albedo output
+  // (material-track era), it lands here and every light is corrected at once,
+  // instead of a hunt through the epilogue's string templates.
+  const LIT = ` + rzLightsDiffuse(input.worldPos, n) * albedo`
+  const ALBEDO = `  let albedo = tex_color;
+`
   if (renderClass === "hair") {
-    return `  var outAlpha = ${alphaBase};
+    return `${ALBEDO}  var outAlpha = ${alphaBase};
   if (IS_OVER_EYES) { outAlpha = ${alphaBase} * 0.25; }
 
   var out: FSOut;
-  out.color = vec4f(final_color, outAlpha);
+  out.color = vec4f(final_color${LIT}, outAlpha);
   out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
+${ID_WRITE}  return out;
 `
   }
-  return `  var out: FSOut;
-  out.color = vec4f(final_color, ${alphaBase});
+  return `${ALBEDO}  var out: FSOut;
+  out.color = vec4f(final_color${LIT}, ${alphaBase});
   out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
+${ID_WRITE}  return out;
 `
 }
 
@@ -139,6 +163,10 @@ export function assembleModule(
   return (
     NODES_WGSL +
     COMMON_MATERIAL_PRELUDE_WGSL +
+    // Exactly where it sat inside the prelude constant. It moved out because
+    // the id attachment is probed at init and this module is assembled per
+    // compile, which is late enough to know the answer.
+    commonFsOutWgsl() +
     (includeStyleUniforms ? STYLE_UNIFORMS_WGSL : "") +
     decls(renderClass, alphaMode) +
     prelude(renderClass, alphaMode) +

package/src/hdr.ts

@@ -0,0 +1,156 @@
+// Radiance .hdr (RGBE) — the HDRI format Blender worlds ship in.
+//
+// Pure and dependency-free like everything else here: the whole format is a
+// text header, a resolution line, and scanlines of shared-exponent RGBE
+// pixels, so a parser is a hundred lines and a WASM decoder would be absurd.
+// The output is scene-linear RGB — the space the view transform expects —
+// which is the entire point: an 8-bit sky is display-space wallpaper, this is
+// radiance the film can actually roll off.
+
+export type HdrImage = {
+  width: number
+  height: number
+  /** RGBA, scene-linear, alpha 1 — padded for direct rgba16float upload. */
+  data: Float32Array
+}
+
+/**
+ * Parse a Radiance .hdr file. Throws with a reason on anything malformed —
+ * the caller shows it as an upload error, not a blank sky.
+ */
+export function parseHDR(buffer: ArrayBuffer): HdrImage {
+  const bytes = new Uint8Array(buffer)
+  let pos = 0
+  const readLine = (): string => {
+    let end = pos
+    while (end < bytes.length && bytes[end] !== 0x0a) end++
+    const line = String.fromCharCode(...bytes.subarray(pos, end))
+    pos = end + 1
+    return line
+  }
+
+  const magic = readLine()
+  if (!magic.startsWith("#?RADIANCE") && !magic.startsWith("#?RGBE")) {
+    throw new Error("not a Radiance .hdr file (missing #?RADIANCE header)")
+  }
+  let formatOk = false
+  for (;;) {
+    const line = readLine()
+    if (line === "") break
+    if (line.startsWith("FORMAT=")) {
+      if (line !== "FORMAT=32-bit_rle_rgbe") throw new Error(`unsupported .hdr format: ${line.slice(7)}`)
+      formatOk = true
+    }
+    if (pos >= bytes.length) throw new Error("truncated .hdr header")
+  }
+  if (!formatOk) throw new Error(".hdr header has no FORMAT line")
+
+  // Only the universal orientation. Rotated/flipped variants exist in theory;
+  // no tool in this pipeline writes them, and silently mis-orienting a sky is
+  // worse than refusing one.
+  const res = readLine()
+  const m = /^-Y (\d+) \+X (\d+)$/.exec(res)
+  if (!m) throw new Error(`unsupported .hdr orientation: "${res}"`)
+  const height = parseInt(m[1], 10)
+  const width = parseInt(m[2], 10)
+
+  const data = new Float32Array(width * height * 4)
+  const rgbe = new Uint8Array(width * 4)
+
+  for (let y = 0; y < height; y++) {
+    if (pos + 4 > bytes.length) throw new Error(`truncated at scanline ${y}`)
+    const isNewRle = bytes[pos] === 2 && bytes[pos + 1] === 2 && ((bytes[pos + 2] << 8) | bytes[pos + 3]) === width
+    if (isNewRle && width >= 8 && width < 32768) {
+      pos += 4
+      // Four planes, each RLE'd independently: count>128 is a run, else literals.
+      for (let c = 0; c < 4; c++) {
+        let x = 0
+        while (x < width) {
+          if (pos >= bytes.length) throw new Error(`truncated RLE at scanline ${y}`)
+          let count = bytes[pos++]
+          if (count > 128) {
+            count -= 128
+            const v = bytes[pos++]
+            if (x + count > width) throw new Error(`RLE run overflows scanline ${y}`)
+            for (let i = 0; i < count; i++) rgbe[(x + i) * 4 + c] = v
+          } else {
+            if (x + count > width) throw new Error(`RLE literals overflow scanline ${y}`)
+            for (let i = 0; i < count; i++) rgbe[(x + i) * 4 + c] = bytes[pos++]
+          }
+          x += count
+        }
+      }
+    } else {
+      // Flat scanline (small widths, or files that never bothered with RLE).
+      // The old-style (1,1,1,n) repeat marker is part of this path.
+      let x = 0
+      while (x < width) {
+        if (pos + 4 > bytes.length) throw new Error(`truncated at scanline ${y}`)
+        const r = bytes[pos]
+        const g = bytes[pos + 1]
+        const b = bytes[pos + 2]
+        const e = bytes[pos + 3]
+        pos += 4
+        if (r === 1 && g === 1 && b === 1 && x > 0) {
+          // Old-style RLE: repeat the previous pixel e times (shift ignored —
+          // scanlines this parser accepts are under 2^15 wide).
+          const px = (x - 1) * 4
+          for (let i = 0; i < e && x < width; i++, x++) {
+            rgbe[x * 4] = rgbe[px]
+            rgbe[x * 4 + 1] = rgbe[px + 1]
+            rgbe[x * 4 + 2] = rgbe[px + 2]
+            rgbe[x * 4 + 3] = rgbe[px + 3]
+          }
+        } else {
+          rgbe[x * 4] = r
+          rgbe[x * 4 + 1] = g
+          rgbe[x * 4 + 2] = b
+          rgbe[x * 4 + 3] = e
+          x++
+        }
+      }
+    }
+    // RGBE → linear: a shared exponent over three 8-bit mantissas.
+    const row = y * width * 4
+    for (let x = 0; x < width; x++) {
+      const e = rgbe[x * 4 + 3]
+      const scale = e === 0 ? 0 : Math.pow(2, e - 136) // 2^(e-128) / 256
+      data[row + x * 4] = rgbe[x * 4] * scale
+      data[row + x * 4 + 1] = rgbe[x * 4 + 1] * scale
+      data[row + x * 4 + 2] = rgbe[x * 4 + 2] * scale
+      data[row + x * 4 + 3] = 1
+    }
+  }
+  return { width, height, data }
+}
+
+/**
+ * Pack float32 to IEEE half, the format rgba16float uploads want. Clamps to
+ * the half range rather than producing Inf — a 70000-nit sun texel should
+ * read as "the brightest representable", not poison the filter.
+ */
+export function packHalf(src: Float32Array): Uint16Array<ArrayBuffer> {
+  const out = new Uint16Array(new ArrayBuffer(src.length * 2))
+  const f32 = new Float32Array(1)
+  const u32 = new Uint32Array(f32.buffer)
+  for (let i = 0; i < src.length; i++) {
+    f32[0] = src[i]
+    const x = u32[0]
+    const sign = (x >>> 16) & 0x8000
+    let exp = (x >>> 23) & 0xff
+    const frac = x & 0x7fffff
+    let h: number
+    if (exp === 0xff) {
+      h = sign | 0x7bff // NaN/Inf → max finite, by the clamp policy above
+    } else if (exp > 142) {
+      h = sign | 0x7bff // > 65504 → max finite
+    } else if (exp < 113) {
+      // Subnormal or zero in half precision.
+      h = exp < 103 ? sign : sign | ((frac | 0x800000) >> (126 - exp))
+    } else {
+      h = sign | ((exp - 112) << 10) | (frac >> 13)
+    }
+    out[i] = h
+  }
+  return out
+}

package/src/ibl.ts

@@ -0,0 +1,115 @@
+// Diffuse irradiance from an HDRI, as 9 spherical-harmonic coefficients — the
+// Ramamoorthi–Hanrahan formulation every engine uses, because integrating the
+// whole sky per fragment is absurd and an SH2 fit of irradiance is within 1%
+// for natural skies.
+//
+// Pure and headlessly testable (the shadow-cascades precedent). The output is
+// PRE-FOLDED: all basis and convolution constants are baked into the nine RGB
+// vectors here, so the shader is a plain polynomial in the normal — and the
+// whole thing is normalised so a uniform sky of radiance 1 lights every
+// surface with exactly 1, which is what makes an HDRI world a drop-in for the
+// flat world colour it replaces.
+//
+// Direction convention matches the composite's equirect sampling exactly
+// (LH, +Z forward: u = 0.5 + atan2(x, z)/2π, v = 0.5 − asin(y)/π), because a
+// sky that lights the character from anywhere but where it is drawn would be
+// worse than no IBL at all.
+
+import type { HdrImage } from "./hdr"
+
+/**
+ * Project an equirect HDRI to folded irradiance SH.
+ *
+ * Returns 9 RGB triplets (27 floats): [A, By, Bz, Bx, Cxy, Cyz, Cz2, Cxz, Cx2y2]
+ * for  E(n) = A + By·y + Bz·z + Bx·x + Cxy·xy + Cyz·yz + Cz2·(3z²−1) + Cxz·xz + Cx2y2·(x²−y²).
+ *
+ * `stride` subsamples the image — irradiance is the lowest-frequency thing an
+ * HDRI carries, so every 4th texel of a 2K is already overkill.
+ */
+export function projectIrradianceSH(img: HdrImage, stride = 4): Float32Array {
+  const { width: w, height: h, data } = img
+  // Accumulated radiance moments L_lm, RGB each.
+  const L = new Float64Array(9 * 3)
+  const dPhi = (2 * Math.PI) / w
+  const dTheta = Math.PI / h
+  for (let y = 0; y < h; y += stride) {
+    const v = (y + 0.5) / h
+    const ny = Math.cos(Math.PI * v)
+    const r = Math.sin(Math.PI * v)
+    // Solid angle of one texel row-slice, times the stride² it stands in for.
+    const dw = r * dPhi * dTheta * stride * stride
+    if (dw <= 0) continue
+    for (let x = 0; x < w; x += stride) {
+      const u = (x + 0.5) / w
+      const phi = (u - 0.5) * 2 * Math.PI
+      const nx = r * Math.sin(phi)
+      const nz = r * Math.cos(phi)
+      const i = (y * w + x) * 4
+      // Real SH basis, evaluated once and weighted by the solid angle.
+      const b0 = 0.282095 * dw
+      const b1 = 0.488603 * ny * dw
+      const b2 = 0.488603 * nz * dw
+      const b3 = 0.488603 * nx * dw
+      const b4 = 1.092548 * nx * ny * dw
+      const b5 = 1.092548 * ny * nz * dw
+      const b6 = 0.315392 * (3 * nz * nz - 1) * dw
+      const b7 = 1.092548 * nx * nz * dw
+      const b8 = 0.546274 * (nx * nx - ny * ny) * dw
+      for (let c = 0; c < 3; c++) {
+        const rad = data[i + c]
+        L[0 * 3 + c] += rad * b0
+        L[1 * 3 + c] += rad * b1
+        L[2 * 3 + c] += rad * b2
+        L[3 * 3 + c] += rad * b3
+        L[4 * 3 + c] += rad * b4
+        L[5 * 3 + c] += rad * b5
+        L[6 * 3 + c] += rad * b6
+        L[7 * 3 + c] += rad * b7
+        L[8 * 3 + c] += rad * b8
+      }
+    }
+  }
+  // Irradiance convolution (Ramamoorthi's c1..c5), then /π for the Lambert
+  // convention — this is the normalisation that makes uniform-1 → exactly 1.
+  const c1 = 0.429043
+  const c2 = 0.511664
+  const c3 = 0.743125
+  const c4 = 0.886227
+  const c5 = 0.247708
+  const out = new Float32Array(27)
+  for (let c = 0; c < 3; c++) {
+    const l00 = L[0 * 3 + c]
+    const l1m1 = L[1 * 3 + c]
+    const l10 = L[2 * 3 + c]
+    const l11 = L[3 * 3 + c]
+    const l2m2 = L[4 * 3 + c]
+    const l2m1 = L[5 * 3 + c]
+    const l20 = L[6 * 3 + c]
+    const l21 = L[7 * 3 + c]
+    const l22 = L[8 * 3 + c]
+    // c3·L20·z² is refolded onto the (3z²−1) basis: the z²-free remainder
+    // joins the constant term, so the shader's polynomial needs no z² row.
+    out[0 * 3 + c] = (c4 * l00 - c5 * l20 + (c3 / 3) * l20) / Math.PI // A
+    out[1 * 3 + c] = (2 * c2 * l1m1) / Math.PI // By
+    out[2 * 3 + c] = (2 * c2 * l10) / Math.PI // Bz
+    out[3 * 3 + c] = (2 * c2 * l11) / Math.PI // Bx
+    out[4 * 3 + c] = (2 * c1 * l2m2) / Math.PI // Cxy
+    out[5 * 3 + c] = (2 * c1 * l2m1) / Math.PI // Cyz
+    out[6 * 3 + c] = ((c3 / 3) * l20) / Math.PI // Cz2 · (3z²−1)
+    out[7 * 3 + c] = (2 * c1 * l21) / Math.PI // Cxz
+    out[8 * 3 + c] = (2 * c1 * l22) / Math.PI // Cx2y2
+  }
+  return out
+}
+
+/** Evaluate the folded coefficients at a normal — the shader's polynomial, in
+ *  JS, so tests and any future CPU consumer share one definition. */
+export function evalIrradianceSH(sh: Float32Array, n: { x: number; y: number; z: number }): [number, number, number] {
+  const { x, y, z } = n
+  const basis = [1, y, z, x, x * y, y * z, 3 * z * z - 1, x * z, x * x - y * y]
+  const out: [number, number, number] = [0, 0, 0]
+  for (let b = 0; b < 9; b++) {
+    for (let c = 0; c < 3; c++) out[c] += sh[b * 3 + c] * basis[b]
+  }
+  return out
+}

package/src/ik-solver.ts

@@ -4,7 +4,7 @@ import { Mat4, Quat, Vec3, type EulerOrder } from "./math"
 import { Bone, IKLink, IKSolver, IKChainInfo } from "./model"
 
 // Callback type for updating world matrix (provided by model to handle append transformations)
-export type UpdateWorldMatrixFn = (boneIndex: number, applyIK: boolean) => void
+type UpdateWorldMatrixFn = (boneIndex: number, applyIK: boolean) => void
 
 const enum InternalEulerRotationOrder {
   YXZ = 0,

package/src/index.ts

@@ -19,8 +19,20 @@ export {
   type GizmoDragKind,
   type EffectParamValue,
   type EffectResult,
+  type CullDiagnostics,
+  type MidiNote,
 } from "./engine"
 export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload"
+export { parseMidi } from "./midi-loader"
+// Radiance .hdr, for HDRI worlds — the host fetches the file and hands the
+// parsed image to setBackdropEquirect.
+export { parseHDR, type HdrImage } from "./hdr"
+// Lyrics timing (.lrc) — the host parses the file and hands the lines to setLyrics.
+export { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, parseLRC, type LyricLine, type LyricRect } from "./shaders/lyrics-api"
+// A material parameter over time. The sampler is exported too: a host that
+// wants to draw a track, or scrub one, should read the same curve the engine
+// plays rather than reimplementing it a second time.
+export { sampleParamTrack, type ParamKey, type ParamValue } from "./param-track"
 export {
   compileGraph,
   validateGraph,

package/src/math.ts

@@ -684,16 +684,33 @@ export class Mat4 {
     return new Mat4(new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]))
   }
 
-  // Perspective matrix for LEFT-HANDED coordinate system (Z+ forward)
-  // For left-handed: Z goes from 0 (near) to 1 (far), +Z is forward
-  // Zero-alloc perspective into an existing column-major array (same values as perspective).
+  /**
+   * Perspective for a LEFT-HANDED system (+Z forward), mapping z ∈ [near, far]
+   * onto clip z ∈ [0, w] — WebGPU's range, and D3D's.
+   *
+   * It used to write the OpenGL matrix, which maps onto [-w, w]. That is not a
+   * style difference: WebGPU clips everything with z < 0, so half the mapping was
+   * being thrown away and the near plane silently sat at TWICE the requested
+   * near. With the camera's own floor of 0.5 that put the real clip at 1.0 units
+   * — and since most materials draw with no face culling, a close-up did not fade
+   * the front of a head, it cut it open and showed the inside of the skull.
+   * Reported from the wild as 穿模 on imported camera work, which is exactly
+   * where it would show: a wide-angle shot is composed by moving the camera in.
+   *
+   * REVERSED-Z is this same function with near and far passed the other way
+   * round: it maps near → 1 and far → 0, which is worth doing on a float depth
+   * buffer because 1/z crowds precision at the near plane and float crowds it at
+   * zero, and the two cancel. On a UNORM buffer it is pointless — the precision
+   * curve is identical, only mirrored — so the caller decides, and decides on
+   * whether it got a float depth format.
+   */
   static perspectiveInto(out: Float32Array, fov: number, aspect: number, near: number, far: number): void {
     const f = 1.0 / Math.tan(fov / 2)
-    const rangeInv = 1.0 / (far - near) // Positive for left-handed
+    const rangeInv = 1.0 / (far - near)
     out[0] = f / aspect; out[1] = 0; out[2] = 0; out[3] = 0
     out[4] = 0; out[5] = f; out[6] = 0; out[7] = 0
-    out[8] = 0; out[9] = 0; out[10] = (far + near) * rangeInv; out[11] = 1 // Z+ forward (LH)
-    out[12] = 0; out[13] = 0; out[14] = -near * far * rangeInv * 2; out[15] = 0
+    out[8] = 0; out[9] = 0; out[10] = far * rangeInv; out[11] = 1 // Z+ forward (LH)
+    out[12] = 0; out[13] = 0; out[14] = -near * far * rangeInv; out[15] = 0
   }
 
   static perspective(fov: number, aspect: number, near: number, far: number): Mat4 {
@@ -1193,17 +1210,6 @@ export const scratchMat4Values: Float32Array[] = [
   new Float32Array(16),
 ]
 
-export const scratchVec3: Vec3[] = [
-  new Vec3(0, 0, 0),
-  new Vec3(0, 0, 0),
-  new Vec3(0, 0, 0),
-  new Vec3(0, 0, 0),
-  new Vec3(0, 0, 0),
-  new Vec3(0, 0, 0),
-  new Vec3(0, 0, 0),
-  new Vec3(0, 0, 0),
-]
-
 export const scratchQuat: Quat[] = [
   new Quat(0, 0, 0, 1),
   new Quat(0, 0, 0, 1),