reze-engine 0.43.0 → 0.50.0

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/shadow-cascades.d.ts

@@ -0,0 +1,45 @@
+type ShadowCascade = {
+    /** World units across the ortho box, both axes. */
+    span: number;
+    /** How far behind the target the light's eye sits, along -sunDir. */
+    back: number;
+    /** Ortho near/far, in world units from that eye. */
+    near: number;
+    far: number;
+    /** Texels per side of this cascade's map — sets the snap quantum. */
+    mapSize: number;
+};
+/**
+ * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
+ * each cascade's box must CONTAIN the previous one (same snapped target, wider
+ * span, deeper reach), because
+ *
+ *   - the sampler falls from cascade i to i+1 at the box edge, which is only
+ *     seamless if i+1 covers where i ends, and
+ *   - the cull tests ONE frustum — the outermost — and the rasterizer clips
+ *     each cascade to its own box. That is the same argument that made
+ *     single-volume shadow culling exact: anything rejected was contributing
+ *     nothing anywhere. Concentric containment is what keeps it true for a
+ *     LIST. tests/shadow-cascades.test.mjs pins it.
+ */
+export declare const SHADOW_CASCADES: readonly ShadowCascade[];
+/**
+ * One cascade's view-projection, following the camera target.
+ *
+ * The target is snapped to this cascade's OWN texel quantum in the light's
+ * right/up plane, so a moving volume doesn't shimmer its shadow edges while
+ * running — each cascade snaps to its own grid, coarser maps snapping coarser.
+ *
+ * Writes the 16 floats into `out` at `offset` and returns `out`.
+ */
+export declare function buildShadowVP(target: {
+    x: number;
+    y: number;
+    z: number;
+}, sunDirection: {
+    x: number;
+    y: number;
+    z: number;
+}, cascade: ShadowCascade, out: Float32Array, offset: number): Float32Array;
+export {};
+//# sourceMappingURL=shadow-cascades.d.ts.map

package/dist/shadow-cascades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-cascades.d.ts","sourceRoot":"","sources":["../src/shadow-cascades.ts"],"names":[],"mappings":"AAeA,KAAK,aAAa,GAAG;IACnB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAWnD,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3C,YAAY,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,MAAM,GACb,YAAY,CA4Bd"}

package/dist/shadow-cascades.js

@@ -0,0 +1,70 @@
+// The shadow volumes, as data — a list the engine iterates rather than one
+// hardcoded box, so a second cascade is a list entry and not a rewrite.
+//
+// Pure math, its own module for the same reason param-track.ts is: the engine
+// class needs a GPU to construct, and the one thing that ever goes WRONG with a
+// shadow volume is arithmetic — a snap that stops snapping, an eye that lands
+// inside the near plane. Headless tests can hold this half to golden values.
+//
+// The arithmetic is the shipped single-volume code, operation for operation:
+// float addition is not associative, so "the same formula, reordered" is not
+// the same matrix, and cascade 0 must be BIT-IDENTICAL to the volume every
+// published scene was lit by.
+import { Mat4, Vec3 } from "./math";
+/**
+ * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
+ * each cascade's box must CONTAIN the previous one (same snapped target, wider
+ * span, deeper reach), because
+ *
+ *   - the sampler falls from cascade i to i+1 at the box edge, which is only
+ *     seamless if i+1 covers where i ends, and
+ *   - the cull tests ONE frustum — the outermost — and the rasterizer clips
+ *     each cascade to its own box. That is the same argument that made
+ *     single-volume shadow culling exact: anything rejected was contributing
+ *     nothing anywhere. Concentric containment is what keeps it true for a
+ *     LIST. tests/shadow-cascades.test.mjs pins it.
+ */
+export const SHADOW_CASCADES = [
+    // The shipped volume: 64 units at 4096² ≈ 64 texels/unit — crisp contact
+    // shadows on the ground catcher (2048 read visibly blurry).
+    { span: 64, back: 72, near: 1, far: 140, mapSize: 4096 },
+    // The stage volume: 4× the span on each side, so a set piece 100 units out
+    // still throws and receives shade instead of popping lit at the near box's
+    // edge. 2048² over 256 units ≈ 8 texels/unit — soft, and read at distances
+    // where soft is what a shadow looks like anyway. 16 MB where the near map
+    // is 64. Depth reach scales with the span (same eye direction, deeper box),
+    // keeping the containment invariant checkable from the specs alone.
+    { span: 256, back: 288, near: 1, far: 560, mapSize: 2048 },
+];
+/**
+ * One cascade's view-projection, following the camera target.
+ *
+ * The target is snapped to this cascade's OWN texel quantum in the light's
+ * right/up plane, so a moving volume doesn't shimmer its shadow edges while
+ * running — each cascade snaps to its own grid, coarser maps snapping coarser.
+ *
+ * Writes the 16 floats into `out` at `offset` and returns `out`.
+ */
+export function buildShadowVP(target, sunDirection, cascade, out, offset) {
+    const dir = new Vec3(sunDirection.x, sunDirection.y, sunDirection.z);
+    dir.normalize();
+    const up = Math.abs(dir.y) > 0.99 ? new Vec3(0, 0, -1) : new Vec3(0, 1, 0);
+    const t = new Vec3(target.x, target.y, target.z);
+    const right = Vec3.crossInto(up, dir, new Vec3(0, 0, 0)).normalize();
+    const upv = Vec3.crossInto(dir, right, new Vec3(0, 0, 0));
+    const texel = cascade.span / cascade.mapSize;
+    const tr = Math.round(t.dot(right) / texel) * texel;
+    const tu = Math.round(t.dot(upv) / texel) * texel;
+    const td = t.dot(dir);
+    const snapped = new Vec3(right.x * tr + upv.x * tu + dir.x * td, right.y * tr + upv.y * tu + dir.y * td, right.z * tr + upv.z * tu + dir.z * td);
+    const eye = new Vec3(snapped.x - dir.x * cascade.back, snapped.y - dir.y * cascade.back, snapped.z - dir.z * cascade.back);
+    const view = Mat4.lookAt(eye, snapped, up);
+    const half = cascade.span / 2;
+    // The shadow map keeps the NON-reversed convention (orthographicLh maps z to
+    // [0,1] front-to-back) — reversing it buys nothing for an ortho box and the
+    // +2 pipeline depth bias is signed against this direction.
+    const proj = Mat4.orthographicLh(-half, half, -half, half, cascade.near, cascade.far);
+    const vp = proj.multiply(view);
+    out.set(vp.values, offset);
+    return out;
+}

package/dist/vmd-loader.d.ts

@@ -1,12 +1,12 @@
 import { Quat, Vec3 } from "./math";
-export interface BoneFrame {
+interface BoneFrame {
     boneName: string;
     frame: number;
     rotation: Quat;
     translation: Vec3;
     interpolation: Uint8Array;
 }
-export interface MorphFrame {
+interface MorphFrame {
     morphName: string;
     frame: number;
     weight: number;
@@ -70,4 +70,5 @@ export declare class VMDLoader {
     private getString;
     private skip;
 }
+export {};
 //# sourceMappingURL=vmd-loader.d.ts.map

package/dist/vmd-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vmd-loader.d.ts","sourceRoot":"","sources":["../src/vmd-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEnC,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,IAAI,CAAA;IACd,WAAW,EAAE,IAAI,CAAA;IACjB,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;qFAEqF;AACrF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,IAAI,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CACjD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAa;IAE5B,OAAO;WAWM,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE;IAKzD;mGAC+F;WAClF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK/D,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,EAAE;IAOlE,OAAO,CAAC,WAAW;IA4BnB,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,EAAE;IAIvD;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IA8Bf,OAAO,CAAC,KAAK;IAgGb,OAAO,CAAC,aAAa;IAuDrB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IASlB,gFAAgF;IAChF,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,IAAI;CAMb"}
+{"version":3,"file":"vmd-loader.d.ts","sourceRoot":"","sources":["../src/vmd-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEnC,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,IAAI,CAAA;IACd,WAAW,EAAE,IAAI,CAAA;IACjB,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,UAAU,UAAU;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;qFAEqF;AACrF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,IAAI,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CACjD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAa;IAE5B,OAAO;WAWM,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE;IAKzD;mGAC+F;WAClF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK/D,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,EAAE;IAOlE,OAAO,CAAC,WAAW;IA4BnB,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,EAAE;IAIvD;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IA8Bf,OAAO,CAAC,KAAK;IAgGb,OAAO,CAAC,aAAa;IAuDrB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IASlB,gFAAgF;IAChF,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,IAAI;CAMb"}

package/package.json

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

package/src/camera.ts

@@ -4,11 +4,25 @@ import type { CameraPose } from "./camera-animation"
 /** Far cap / zoom limit; large enough for wide shots without clipping distant ground */
 const FAR_CAP = 8000
 const FAR_MIN = 200
-/** The character-framing value the cloth z-fighting fix settled on — never go below it. */
-const NEAR_MIN = 0.5
-/** ~40cm in MMD units. Past this the near plane would start clipping geometry a
- *  user has deliberately pushed the camera up against. */
-const NEAR_MAX = 5
+/**
+ * Near-plane floor and cap, in two sets, because what a near plane costs depends
+ * entirely on the depth buffer underneath it.
+ *
+ * The single set that used to live here was written against a projection that
+ * silently doubled it (see Mat4.perspectiveInto), so the real clip was at 1.0 and
+ * 10 rather than the 0.5 and 5 stated. UNORM keeps exactly that behaviour, now
+ * said out loud: identical precision, identical z-fighting margin on coplanar
+ * cloth, no change to any scene that renders correctly today.
+ *
+ * REVERSED gets the floor the content actually wants. Float depth read backwards
+ * holds roughly constant RELATIVE precision across the range, so pulling the near
+ * plane in by twenty times costs almost nothing — and a 4 mm near plane is closer
+ * than any camera VMD will ever push.
+ */
+const NEAR_MIN_UNORM = 1.0
+const NEAR_MAX_UNORM = 10
+const NEAR_MIN_REVERSED = 0.05
+const NEAR_MAX_REVERSED = 5
 
 export class Camera {
   alpha: number
@@ -21,8 +35,11 @@ export class Camera {
    *  nearly all of it within a hand's reach and coplanar cloth/body layers z-fought
    *  (white crack flashes, worse the further the camera). 0.5 MMD units ≈ 4 cm —
    *  closer than any real framing — and buys 10× precision at character range. */
-  near: number = 0.5
+  near: number = NEAR_MIN_UNORM
   far: number = FAR_CAP
+  /** Set once by the engine, from whether it got a float depth format. Decides
+   *  both the near-plane floor and which way round the projection maps z. */
+  reversedZ = false
 
   // Input state
   private canvas: HTMLCanvasElement | null = null
@@ -248,13 +265,19 @@ export class Camera {
    * user is deliberately close to.
    */
   private updateNearFromRadius(): void {
-    this.near = Math.min(NEAR_MAX, Math.max(NEAR_MIN, this.radius / 50))
+    const lo = this.reversedZ ? NEAR_MIN_REVERSED : NEAR_MIN_UNORM
+    const hi = this.reversedZ ? NEAR_MAX_REVERSED : NEAR_MAX_UNORM
+    this.near = Math.min(hi, Math.max(lo, this.radius / 50))
   }
 
   getProjectionMatrix(): Mat4 {
     this.updateFarFromRadius()
     this.updateNearFromRadius()
-    Mat4.perspectiveInto(this._projMat.values, this.fov, this.aspect, this.near, this.far)
+    // Reversed-Z is the same matrix with near and far handed over the other way
+    // round — near → 1, far → 0. One projection function, and the reversal is a
+    // property of the depth buffer rather than a second matrix to keep in step.
+    if (this.reversedZ) Mat4.perspectiveInto(this._projMat.values, this.fov, this.aspect, this.far, this.near)
+    else Mat4.perspectiveInto(this._projMat.values, this.fov, this.aspect, this.near, this.far)
     return this._projMat
   }