reze-engine 0.42.3 → 0.50.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. package/README.md +40 -410
  2. package/dist/camera.d.ts +3 -0
  3. package/dist/camera.d.ts.map +1 -1
  4. package/dist/camera.js +33 -8
  5. package/dist/engine.d.ts +924 -29
  6. package/dist/engine.d.ts.map +1 -1
  7. package/dist/engine.js +4043 -278
  8. package/dist/graph/registry.d.ts +2 -2
  9. package/dist/graph/registry.d.ts.map +1 -1
  10. package/dist/graph/registry.js +1 -1
  11. package/dist/graph/slots.d.ts +0 -1
  12. package/dist/graph/slots.d.ts.map +1 -1
  13. package/dist/graph/slots.js +37 -9
  14. package/dist/hdr.d.ts +18 -0
  15. package/dist/hdr.d.ts.map +1 -0
  16. package/dist/hdr.js +162 -0
  17. package/dist/ibl.d.ts +19 -0
  18. package/dist/ibl.d.ts.map +1 -0
  19. package/dist/ibl.js +113 -0
  20. package/dist/ik-solver.d.ts +2 -1
  21. package/dist/ik-solver.d.ts.map +1 -1
  22. package/dist/index.d.ts +5 -1
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +10 -0
  25. package/dist/math.d.ts +20 -1
  26. package/dist/math.d.ts.map +1 -1
  27. package/dist/math.js +23 -16
  28. package/dist/midi-loader.d.ts +10 -0
  29. package/dist/midi-loader.d.ts.map +1 -0
  30. package/dist/midi-loader.js +247 -0
  31. package/dist/model.d.ts +2 -13
  32. package/dist/model.d.ts.map +1 -1
  33. package/dist/model.js +29 -0
  34. package/dist/param-track.d.ts +48 -0
  35. package/dist/param-track.d.ts.map +1 -0
  36. package/dist/param-track.js +80 -0
  37. package/dist/physics/types.d.ts.map +1 -1
  38. package/dist/physics/types.js +3 -0
  39. package/dist/reflection.d.ts +27 -0
  40. package/dist/reflection.d.ts.map +1 -0
  41. package/dist/reflection.js +93 -0
  42. package/dist/shaders/anchor-table.d.ts +56 -0
  43. package/dist/shaders/anchor-table.d.ts.map +1 -0
  44. package/dist/shaders/anchor-table.js +128 -0
  45. package/dist/shaders/audio-api.d.ts +3 -0
  46. package/dist/shaders/audio-api.d.ts.map +1 -0
  47. package/dist/shaders/audio-api.js +81 -0
  48. package/dist/shaders/cast-api.d.ts +2 -0
  49. package/dist/shaders/cast-api.d.ts.map +1 -0
  50. package/dist/shaders/cast-api.js +121 -0
  51. package/dist/shaders/cast-layout.d.ts +21 -0
  52. package/dist/shaders/cast-layout.d.ts.map +1 -0
  53. package/dist/shaders/cast-layout.js +20 -0
  54. package/dist/shaders/lights.d.ts +79 -0
  55. package/dist/shaders/lights.d.ts.map +1 -0
  56. package/dist/shaders/lights.js +269 -0
  57. package/dist/shaders/lyrics-api.d.ts +39 -0
  58. package/dist/shaders/lyrics-api.d.ts.map +1 -0
  59. package/dist/shaders/lyrics-api.js +187 -0
  60. package/dist/shaders/materials/common.d.ts +2 -4
  61. package/dist/shaders/materials/common.d.ts.map +1 -1
  62. package/dist/shaders/materials/common.js +87 -35
  63. package/dist/shaders/midi-api.d.ts +10 -0
  64. package/dist/shaders/midi-api.d.ts.map +1 -0
  65. package/dist/shaders/midi-api.js +114 -0
  66. package/dist/shaders/passes/composite.d.ts +31 -15
  67. package/dist/shaders/passes/composite.d.ts.map +1 -1
  68. package/dist/shaders/passes/composite.js +225 -135
  69. package/dist/shaders/passes/cull.d.ts +2 -0
  70. package/dist/shaders/passes/cull.d.ts.map +1 -0
  71. package/dist/shaders/passes/cull.js +138 -0
  72. package/dist/shaders/passes/field-blit.d.ts +26 -0
  73. package/dist/shaders/passes/field-blit.d.ts.map +1 -0
  74. package/dist/shaders/passes/field-blit.js +65 -0
  75. package/dist/shaders/passes/grid.d.ts +31 -0
  76. package/dist/shaders/passes/grid.d.ts.map +1 -0
  77. package/dist/shaders/passes/grid.js +169 -0
  78. package/dist/shaders/passes/ground.d.ts +13 -1
  79. package/dist/shaders/passes/ground.d.ts.map +1 -1
  80. package/dist/shaders/passes/ground.js +170 -25
  81. package/dist/shaders/passes/hosted-api.d.ts +57 -0
  82. package/dist/shaders/passes/hosted-api.d.ts.map +1 -0
  83. package/dist/shaders/passes/hosted-api.js +166 -0
  84. package/dist/shaders/passes/id-debug.d.ts +28 -0
  85. package/dist/shaders/passes/id-debug.d.ts.map +1 -0
  86. package/dist/shaders/passes/id-debug.js +74 -0
  87. package/dist/shaders/passes/particles.d.ts +66 -0
  88. package/dist/shaders/passes/particles.d.ts.map +1 -0
  89. package/dist/shaders/passes/particles.js +279 -0
  90. package/dist/shaders/passes/scene-contract.d.ts +128 -0
  91. package/dist/shaders/passes/scene-contract.d.ts.map +1 -0
  92. package/dist/shaders/passes/scene-contract.js +207 -0
  93. package/dist/shaders/passes/sim.d.ts +34 -0
  94. package/dist/shaders/passes/sim.d.ts.map +1 -0
  95. package/dist/shaders/passes/sim.js +169 -0
  96. package/dist/shaders/passes/trails.d.ts +59 -0
  97. package/dist/shaders/passes/trails.d.ts.map +1 -0
  98. package/dist/shaders/passes/trails.js +340 -0
  99. package/dist/shaders/score-api.d.ts +10 -0
  100. package/dist/shaders/score-api.d.ts.map +1 -0
  101. package/dist/shaders/score-api.js +114 -0
  102. package/dist/shadow-cascades.d.ts +45 -0
  103. package/dist/shadow-cascades.d.ts.map +1 -0
  104. package/dist/shadow-cascades.js +70 -0
  105. package/dist/vmd-loader.d.ts +3 -2
  106. package/dist/vmd-loader.d.ts.map +1 -1
  107. package/package.json +1 -1
  108. package/src/camera.ts +31 -8
  109. package/src/engine.ts +4535 -296
  110. package/src/graph/registry.ts +2 -2
  111. package/src/graph/slots.ts +37 -9
  112. package/src/hdr.ts +156 -0
  113. package/src/ibl.ts +115 -0
  114. package/src/ik-solver.ts +1 -1
  115. package/src/index.ts +12 -0
  116. package/src/math.ts +23 -17
  117. package/src/midi-loader.ts +246 -0
  118. package/src/model.ts +31 -3
  119. package/src/param-track.ts +83 -0
  120. package/src/physics/types.ts +4 -1
  121. package/src/reflection.ts +94 -0
  122. package/src/shaders/anchor-table.ts +147 -0
  123. package/src/shaders/audio-api.ts +82 -0
  124. package/src/shaders/cast-api.ts +123 -0
  125. package/src/shaders/cast-layout.ts +20 -0
  126. package/src/shaders/lights.ts +280 -0
  127. package/src/shaders/lyrics-api.ts +202 -0
  128. package/src/shaders/materials/common.ts +89 -35
  129. package/src/shaders/midi-api.ts +116 -0
  130. package/src/shaders/passes/composite.ts +244 -136
  131. package/src/shaders/passes/cull.ts +139 -0
  132. package/src/shaders/passes/grid.ts +178 -0
  133. package/src/shaders/passes/ground.ts +172 -25
  134. package/src/shaders/passes/hosted-api.ts +171 -0
  135. package/src/shaders/passes/id-debug.ts +75 -0
  136. package/src/shaders/passes/particles.ts +340 -0
  137. package/src/shaders/passes/scene-contract.ts +266 -0
  138. package/src/shaders/passes/trails.ts +390 -0
  139. package/src/shadow-cascades.ts +97 -0
  140. package/src/vmd-loader.ts +2 -2
@@ -0,0 +1,390 @@
1
+ import { RZ_LIGHT_STRUCT_WGSL } from "../lights"
2
+ import { audioApi } from "../audio-api"
3
+ import { lyricsApi } from "../lyrics-api"
4
+ import { anchorAliasWgsl, ribbonSlotWgsl } from "../anchor-table"
5
+ import { midiApi } from "../midi-api"
6
+ import { CAST_API } from "../cast-api"
7
+ import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
8
+ // Ribbons along a bone's recorded path, drawn as geometry.
9
+ //
10
+ // This is the effect the whole geometry path was built for. As a fullscreen
11
+ // field the hand ribbon cost O(pixels × trail samples) — every pixel on screen
12
+ // walking 128 samples to decide it was not on the ribbon — and it was the single
13
+ // most expensive built-in by a wide margin. As a strip of quads it costs the
14
+ // segments: 127 of them, whatever the resolution.
15
+ //
16
+ // It draws from the SAME history the field version read through rzTrail. The
17
+ // engine already records every declared anchor's path at a fixed rate on the
18
+ // scene clock, so nothing new is sampled and an exported ribbon is identical to
19
+ // the one in the editor.
20
+ //
21
+ // The author writes two functions: how wide the ribbon is at a point, and what
22
+ // colour. Everything else — which bones, which characters, where the samples
23
+ // are, how to face the camera — is the engine's.
24
+
25
+ type TrailSource = {
26
+ /** The author's WGSL verbatim. */
27
+ wgsl: string
28
+ /** How many ribbons to draw — one per trailed anchor. */
29
+ slots: number
30
+ /** For each ribbon, the LOCAL anchor slot it belongs to. Identity when every
31
+ * anchor is trailed; otherwise it skips the untrailed ones. */
32
+ ribbonSlots: number[]
33
+ /** Additive, like most glowing ribbons, or straight alpha. */
34
+ blend: "alpha" | "additive"
35
+ bloom: boolean
36
+ }
37
+
38
+ /**
39
+ * Sub-segments drawn between each pair of recorded samples.
40
+ *
41
+ * The path is sampled at a fixed rate on the scene clock, so a fast hand leaves
42
+ * its samples far apart and a strip drawn straight between them is visibly
43
+ * faceted. Four sub-segments on a Catmull-Rom curve through the neighbours costs
44
+ * four times the vertices — which is nothing, they are vertices — and removes
45
+ * both the faceting and most of the jitter, since a spline tangent varies
46
+ * smoothly where a per-segment direction snaps about whenever the hand slows.
47
+ */
48
+ export const TRAIL_SUBDIVISIONS = 6
49
+
50
+ /** Does the source define the trail contract? Both are required together. */
51
+ export function trailEntryPoints(wgsl: string): { width: boolean; shade: boolean } {
52
+ return {
53
+ width: /\bfn\s+trailWidth\s*\(/.test(wgsl),
54
+ shade: /\bfn\s+trailShade\s*\(/.test(wgsl),
55
+ }
56
+ }
57
+
58
+ /**
59
+ * One quad per segment, laid out flat across every anchor and character.
60
+ *
61
+ * The instance index encodes all three — segment, subject, slot — so a scene
62
+ * with three dancers and eight declared bones is still ONE draw call and needs
63
+ * nothing computed on the CPU per frame. Instances past the end of a real trail
64
+ * collapse to a degenerate quad, which costs a vertex shader invocation and no
65
+ * fragments; the alternative is a compacted instance list, which costs a
66
+ * readback every frame to save exactly that.
67
+ *
68
+ * The ribbon faces the camera per SEGMENT rather than as a whole: the side
69
+ * vector is the segment direction crossed with the direction to the eye, so a
70
+ * ribbon that loops back on itself stays visible along its entire length instead
71
+ * of vanishing edge-on where it turns.
72
+ */
73
+ export function buildTrailShader(
74
+ src: TrailSource,
75
+ cast: {
76
+ subjects: number
77
+ samples: number
78
+ base: number
79
+ trailBase: number
80
+ slots: number
81
+ alias: number[]
82
+ /** Depth convention of the scene buffer this layer tests against. The
83
+ * occlusion compare below is MANUAL (the layer has no depth attachment),
84
+ * so it does not flip with the pipelines' depthCompare — it has to be
85
+ * emitted the right way round at build time. On a reversed-Z device,
86
+ * larger z is CLOSER; the unflipped test drew ribbons only when occluded. */
87
+ reversedZ: boolean
88
+ },
89
+ ): string {
90
+ return (
91
+ CAST_API +
92
+ trailSlotsApi(src.slots) +
93
+ EFFECT_MATH_API +
94
+ PARTICLE_STRUCT_WGSL +
95
+ clockApi("tu.time", "0.0") +
96
+ viewportApi("cam.targetHeight") +
97
+ // RZ_SLOTS is this module's alone: how many ribbons to DRAW, which is the
98
+ // instance loop's bound. RZ_MAX_ANCHORS in CAST_API is the address space the
99
+ // accessors are bounded by, and the two being one number was the old trail
100
+ // bug — the comment that said so lived here, so it stays here.
101
+ `const RZ_SLOTS: i32 = ${src.slots};
102
+ ${ribbonSlotWgsl(src.ribbonSlots)}
103
+ ${anchorAliasWgsl(cast.alias)}
104
+ const SUB: i32 = ${TRAIL_SUBDIVISIONS};
105
+
106
+ // World units a sample pair must span to count as a FULL contribution — the
107
+ // original's REF_SEG_PX, converted out of pixels.
108
+ //
109
+ // This is a line integral along a path, so a segment should contribute in
110
+ // proportion to the path it covers. Without it a hand that pauses stacks fifty
111
+ // samples on one point and every one of them contributes fully, which is what
112
+ // turned the ribbon white wherever it slowed. It scales INTENSITY, not width:
113
+ // scaling width pinches the strip shut at exactly the moments a hand decelerates,
114
+ // which is every turn — and a ribbon that closes to nothing at each turn reads as
115
+ // dark breaks in the middle of it.
116
+ const RZ_REF_SPAN: f32 = 0.37;
117
+
118
+ struct CameraU {
119
+ view: mat4x4f,
120
+ proj: mat4x4f,
121
+ camPos: vec3f,
122
+ targetHeight: f32,
123
+ }
124
+ struct TrailU {
125
+ time: f32,
126
+ _pad0: f32,
127
+ _pad1: f32,
128
+ _pad2: f32,
129
+ }
130
+ @group(0) @binding(0) var<storage, read> _rzCast: array<vec4f>;
131
+ @group(0) @binding(1) var<uniform> tu: TrailU;
132
+ @group(0) @binding(2) var<uniform> cam: CameraU;
133
+ // Binding 3 is GONE, and it had to go. Ribbons draw inside the scene pass now,
134
+ // and the depth buffer is that pass's render attachment — binding it for
135
+ // sampling in the same pass is a usage conflict WebGPU rejects outright:
136
+ // "includes writable usage and another usage in the same synchronization
137
+ // scope". The hardware depth test replaced what it was read for.
138
+
139
+ ${RZ_LIGHT_STRUCT_WGSL}
140
+ fn rzCameraPos() -> vec3f { return cam.camPos; }
141
+ fn rzCameraRight() -> vec3f { return vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]); }
142
+ fn rzCameraUp() -> vec3f { return vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]); }
143
+ fn rzCameraForward() -> vec3f { return vec3f(cam.view[0][2], cam.view[1][2], cam.view[2][2]); }
144
+ /** World point → (uv, view distance), same contract as the field mounts' rzProject. */
145
+ fn rzProject(p: vec3f) -> vec3f {
146
+ let clip = cam.proj * cam.view * vec4f(p, 1.0);
147
+ let w = max(clip.w, 1e-4);
148
+ return vec3f(clip.xy / w * 0.5 + 0.5, clip.w);
149
+ }
150
+ fn rzCamPos() -> vec3f { return cam.camPos; }
151
+ fn rzSubjectCount() -> i32 {
152
+ var n = 0;
153
+ for (var i = 0; i < RZ_SUBJECTS; i++) {
154
+ if (_rzCast[i * 3 + 2].w > 0.0) { n = i + 1; }
155
+ }
156
+ return n;
157
+ }
158
+ /** Catmull-Rom through four samples — passes through p1 and p2. */
159
+ fn rzSpline(p0: vec3f, p1: vec3f, p2: vec3f, p3: vec3f, t: f32) -> vec3f {
160
+ let t2 = t * t;
161
+ let t3 = t2 * t;
162
+ return 0.5 * ((2.0 * p1) + (-p0 + p2) * t + (2.0 * p0 - 5.0 * p1 + 4.0 * p2 - p3) * t2 +
163
+ (-p0 + 3.0 * p1 - 3.0 * p2 + p3) * t3);
164
+ }
165
+ /** Its derivative — the ribbon's direction, smooth by construction. */
166
+ fn rzSplineTangent(p0: vec3f, p1: vec3f, p2: vec3f, p3: vec3f, t: f32) -> vec3f {
167
+ let t2 = t * t;
168
+ let d = 0.5 * ((-p0 + p2) + 2.0 * (2.0 * p0 - 5.0 * p1 + 4.0 * p2 - p3) * t +
169
+ 3.0 * (-p0 + 3.0 * p1 - 3.0 * p2 + p3) * t2);
170
+ if (length(d) < 1e-6) { return vec3f(0.0, 1.0, 0.0); }
171
+ return normalize(d);
172
+ }
173
+ fn rzTrailAt(subject: i32, slot: i32, i: i32, n: i32) -> vec4f {
174
+ return rzTrail(subject, slot, clamp(i, 0, n - 1));
175
+ }
176
+
177
+ /**
178
+ * The direction the ribbon runs AT a sample, not along one segment.
179
+ *
180
+ * Averaging the incoming and outgoing directions gives a mitre joint: both quads
181
+ * meeting at a sample compute the same tangent, so they share an edge exactly.
182
+ * Taking each segment's own direction instead leaves a wedge at every bend —
183
+ * which under additive blending is a bright band, and is what put visible
184
+ * stripes across the ribbon wherever the hand turned.
185
+ */
186
+ fn rzTangentAt(subject: i32, slot: i32, i: i32, n: i32) -> vec3f {
187
+ let p = rzTrail(subject, slot, i).xyz;
188
+ var d = vec3f(0.0);
189
+ if (i > 0) {
190
+ let q = rzTrail(subject, slot, i - 1).xyz;
191
+ let e = p - q;
192
+ if (length(e) > 1e-7) { d = d + normalize(e); }
193
+ }
194
+ if (i + 1 < n) {
195
+ let q = rzTrail(subject, slot, i + 1).xyz;
196
+ let e = q - p;
197
+ if (length(e) > 1e-7) { d = d + normalize(e); }
198
+ }
199
+ if (length(d) < 1e-6) { return vec3f(0.0, 1.0, 0.0); }
200
+ return normalize(d);
201
+ }
202
+ /**
203
+ * Circumradius of three consecutive samples — the path's local turn radius.
204
+ *
205
+ * The ribbon's half-width must not exceed this. Where it does, the inner edges
206
+ * of adjacent quads cross the centre of the turn and overlap, and under
207
+ * additive blending every overlap doubles into a bright transverse wedge — the
208
+ * bands that survived every brightness fix, because they were geometry, not
209
+ * shading. Collinear or stationary samples return a huge radius: a straight
210
+ * path clamps nothing.
211
+ */
212
+ fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
213
+ let ab = b - a;
214
+ let bc = c - b;
215
+ let ca = a - c;
216
+ let la = length(ab);
217
+ let lb = length(bc);
218
+ let cr = length(cross(ab, ca));
219
+ if (la < 1e-5 || lb < 1e-5 || cr < 1e-7) { return 1e6; }
220
+ return (la * lb * length(ca)) / (2.0 * cr);
221
+ }
222
+ ` +
223
+ audioApi(0, 4) +
224
+ midiApi(0, 5) +
225
+ lyricsApi(0, 6) +
226
+ "\n// ── user effect ──\n" +
227
+ src.wgsl +
228
+ /* wgsl */ `
229
+ struct VSOut {
230
+ @builtin(position) clip: vec4f,
231
+ @location(0) uv: vec2f,
232
+ @location(1) age: f32,
233
+ @location(2) weight: f32,
234
+ // Which declared anchor this quad belongs to — so one effect can dress its
235
+ // hand and foot ribbons differently instead of sharing a single look.
236
+ @location(3) @interpolate(flat) slot: u32,
237
+ }
238
+
239
+ @vertex
240
+ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut {
241
+ var out: VSOut;
242
+ let subs = u32((RZ_SAMPLES - 1) * SUB);
243
+ let k = i32(ii % subs);
244
+ let rest = ii / subs;
245
+ let seg = k / SUB;
246
+ let sub = k % SUB;
247
+ let subject = i32(rest % u32(RZ_SUBJECTS));
248
+ // Instance index counts RIBBONS; the cast buffer is addressed by anchor slot.
249
+ // One ribbon per trailed anchor, so these are the same number only when every
250
+ // anchor is trailed — _rzRibbonSlot is what bridges them.
251
+ let ribbon = i32(rest / u32(RZ_SUBJECTS));
252
+ let slot = _rzRibbonSlot(ribbon);
253
+
254
+ let n = rzTrailCount(subject, slot);
255
+ if (ribbon >= RZ_SLOTS || seg + 1 >= n) {
256
+ out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
257
+ out.uv = vec2f(0.0);
258
+ out.age = 0.0;
259
+ return out;
260
+ }
261
+
262
+ let quad = array<vec2f, 6>(
263
+ vec2f(0.0, -1.0), vec2f(1.0, -1.0), vec2f(0.0, 1.0),
264
+ vec2f(0.0, 1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0),
265
+ );
266
+ let c = quad[vi];
267
+ let atEnd = c.x > 0.5;
268
+
269
+ // Position ON THE CURVE, not on the chord. Both quads meeting at a sub-sample
270
+ // evaluate the same t, so they share an edge exactly — no wedge to double-blend
271
+ // into a bright band, which is what the per-segment version left at every bend.
272
+ let t0 = f32(sub) / f32(SUB);
273
+ let t1 = (f32(sub) + 1.0) / f32(SUB);
274
+ let t = select(t0, t1, atEnd);
275
+ let p0 = rzTrailAt(subject, slot, seg - 1, n).xyz;
276
+ let p1 = rzTrail(subject, slot, seg).xyz;
277
+ let p2 = rzTrail(subject, slot, seg + 1).xyz;
278
+ let p3 = rzTrailAt(subject, slot, seg + 2, n).xyz;
279
+ let H = cam.targetHeight;
280
+ let toPx = vec2f((cam.proj[1][1] / cam.proj[0][0]) * H, H) * 0.5;
281
+ // The original's MIN_SEG_PX gate, restored as a HARD gate — not a fade.
282
+ //
283
+ // "Below this the hand is not moving", its comment said, and it meant it: a
284
+ // segment under 0.7px contributed NOTHING. Softening that into a weight that
285
+ // approaches zero let a pause stack dozens of near-stationary quads at full
286
+ // glow width, each individually faint, summing into a wide bright bar exactly
287
+ // where the hand slows — aggregation the width taper never clamps, because
288
+ // width follows AGE, not speed. Where the hand is not moving there is no path,
289
+ // and a path effect should draw nothing there at all.
290
+ let c1 = cam.proj * cam.view * vec4f(p1, 1.0);
291
+ let c2 = cam.proj * cam.view * vec4f(p2, 1.0);
292
+ if (c1.w <= 0.01 || c2.w <= 0.01 ||
293
+ distance(c1.xy / c1.w * toPx, c2.xy / c2.w * toPx) < 0.7 * (H / 1080.0)) {
294
+ out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
295
+ out.uv = vec2f(0.0);
296
+ out.age = 0.0;
297
+ out.weight = 0.0;
298
+ return out;
299
+ }
300
+ let pA = rzSpline(p0, p1, p2, p3, t0);
301
+ let pB = rzSpline(p0, p1, p2, p3, t1);
302
+ let p = select(pA, pB, atEnd);
303
+
304
+ // Age and position along the ribbon interpolate across the sub-segment too.
305
+ let ageA = rzTrail(subject, slot, seg).w;
306
+ let ageB = rzTrail(subject, slot, seg + 1).w;
307
+ let age = mix(ageA, ageB, t);
308
+ let u = (f32(seg) + t) / f32(max(1, n - 1));
309
+
310
+ // SCREEN-SPACE extrusion — the fresh take, and the faithful one.
311
+ //
312
+ // Every artefact this ribbon has had came from building it in 3D with a
313
+ // camera-facing side vector: fold-over wedges at tight turns, bowties when the
314
+ // tangent swept past the view axis, and twisted quads whose core line rotated
315
+ // ACROSS the strip and drew as a bright rung. The fullscreen original had none
316
+ // of them, because it never left 2D: it shaded distance to the PROJECTED path,
317
+ // in pixels. So project the spline to pixel space and extrude there — the same
318
+ // geometry the original shaded, at a quad's price. A 2D perpendicular cannot
319
+ // twist, and pixel width is what the original's constants meant all along.
320
+ let clipA = cam.proj * cam.view * vec4f(pA, 1.0);
321
+ let clipB = cam.proj * cam.view * vec4f(pB, 1.0);
322
+ if (clipA.w <= 0.01 || clipB.w <= 0.01) {
323
+ out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
324
+ out.uv = vec2f(0.0);
325
+ out.age = 0.0;
326
+ out.weight = 0.0;
327
+ return out;
328
+ }
329
+ // The projected tangent by the quotient rule — exact at the knot, so the two
330
+ // quads meeting there derive the identical perpendicular and share their edge.
331
+ let dA4 = cam.proj * cam.view * vec4f(rzSplineTangent(p0, p1, p2, p3, t0), 0.0);
332
+ let dB4 = cam.proj * cam.view * vec4f(rzSplineTangent(p0, p1, p2, p3, t1), 0.0);
333
+ var tanA = (dA4.xy * clipA.w - clipA.xy * dA4.w) * toPx;
334
+ var tanB = (dB4.xy * clipB.w - clipB.xy * dB4.w) * toPx;
335
+ if (length(tanA) < 1e-5) { tanA = vec2f(1.0, 0.0); }
336
+ if (length(tanB) < 1e-5) { tanB = vec2f(1.0, 0.0); }
337
+ var perpA = normalize(vec2f(-tanA.y, tanA.x));
338
+ var perpB = normalize(vec2f(-tanB.y, tanB.x));
339
+ // A projected cusp flips the perpendicular. The shade is symmetric in |v|, so
340
+ // forcing the quad's ends to agree is invisible — and without it the quad is a
341
+ // 2D bowtie.
342
+ if (dot(perpA, perpB) < 0.0) { perpB = -perpB; }
343
+ let clipP = select(clipA, clipB, atEnd);
344
+ let perp = select(perpA, perpB, atEnd);
345
+ // trailWidth speaks PIXELS, like the original's constants; rzViewportHeight()
346
+ // lets the effect scale them to the frame.
347
+ let wPx = max(0.0, trailWidth(u, age));
348
+ let ndc = clipP.xy / clipP.w + perp * (c.y * wPx) / toPx;
349
+ out.clip = vec4f(ndc * clipP.w, clipP.z, clipP.w);
350
+ out.slot = u32(slot);
351
+ // The line-integral weight: how far the hand travelled, evaluated AT EACH KNOT
352
+ // by central difference and mixed by t so it is continuous across boundaries —
353
+ // per-pair spans made dashes, per-segment averages made terraces.
354
+ let spanA = distance(p2, p0) * 0.5;
355
+ let spanB = distance(p3, p1) * 0.5;
356
+ out.weight = clamp(mix(spanA, spanB, t) / RZ_REF_SPAN, 0.0, 1.0);
357
+ out.uv = vec2f(u, c.y);
358
+ out.age = age;
359
+ return out;
360
+ }
361
+
362
+ struct TrailFSOut {
363
+ @location(0) color: vec4f,
364
+ // The scene's aux target: (bloom mask, coverage). Writing mask 1 is what
365
+ // makes a ribbon BLOOM — it is light, and the gate is what says so.
366
+ @location(1) aux: vec4f,
367
+ }
368
+
369
+ @fragment
370
+ fn fs(in: VSOut) -> TrailFSOut {
371
+ // No manual depth test any more. This drew into its own attachment-less
372
+ // layer and compared position.z against the scene's depth texture by hand,
373
+ // with the direction baked per depth convention. Inside the scene pass the
374
+ // hardware does it, correctly and for free, and the reversed-Z trap that
375
+ // needed its own regression test goes with it.
376
+ let c = trailShade(in.uv.x, in.uv.y, in.age, in.weight, i32(in.slot));
377
+ if (c.a <= 0.0) { discard; }
378
+ var o: TrailFSOut;
379
+ // STRAIGHT colour into an ADDITIVE target, which reverses the old MAX rule
380
+ // deliberately: max existed so parallel strands could not double into bright
381
+ // dashes on a layer composited after tone mapping. In HDR before bloom,
382
+ // overlapping light SHOULD sum — that is what neon does — and the tone
383
+ // mapper is what keeps the sum from clipping.
384
+ o.color = vec4f(c.rgb, c.a);
385
+ o.aux = vec4f(${src.bloom ? "1.0" : "0.0"}, 1.0, 0.0, c.a);
386
+ return o;
387
+ }
388
+ `
389
+ )
390
+ }
@@ -0,0 +1,97 @@
1
+ // The shadow volumes, as data — a list the engine iterates rather than one
2
+ // hardcoded box, so a second cascade is a list entry and not a rewrite.
3
+ //
4
+ // Pure math, its own module for the same reason param-track.ts is: the engine
5
+ // class needs a GPU to construct, and the one thing that ever goes WRONG with a
6
+ // shadow volume is arithmetic — a snap that stops snapping, an eye that lands
7
+ // inside the near plane. Headless tests can hold this half to golden values.
8
+ //
9
+ // The arithmetic is the shipped single-volume code, operation for operation:
10
+ // float addition is not associative, so "the same formula, reordered" is not
11
+ // the same matrix, and cascade 0 must be BIT-IDENTICAL to the volume every
12
+ // published scene was lit by.
13
+
14
+ import { Mat4, Vec3 } from "./math"
15
+
16
+ type ShadowCascade = {
17
+ /** World units across the ortho box, both axes. */
18
+ span: number
19
+ /** How far behind the target the light's eye sits, along -sunDir. */
20
+ back: number
21
+ /** Ortho near/far, in world units from that eye. */
22
+ near: number
23
+ far: number
24
+ /** Texels per side of this cascade's map — sets the snap quantum. */
25
+ mapSize: number
26
+ }
27
+
28
+ /**
29
+ * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
30
+ * each cascade's box must CONTAIN the previous one (same snapped target, wider
31
+ * span, deeper reach), because
32
+ *
33
+ * - the sampler falls from cascade i to i+1 at the box edge, which is only
34
+ * seamless if i+1 covers where i ends, and
35
+ * - the cull tests ONE frustum — the outermost — and the rasterizer clips
36
+ * each cascade to its own box. That is the same argument that made
37
+ * single-volume shadow culling exact: anything rejected was contributing
38
+ * nothing anywhere. Concentric containment is what keeps it true for a
39
+ * LIST. tests/shadow-cascades.test.mjs pins it.
40
+ */
41
+ export const SHADOW_CASCADES: readonly ShadowCascade[] = [
42
+ // The shipped volume: 64 units at 4096² ≈ 64 texels/unit — crisp contact
43
+ // shadows on the ground catcher (2048 read visibly blurry).
44
+ { span: 64, back: 72, near: 1, far: 140, mapSize: 4096 },
45
+ // The stage volume: 4× the span on each side, so a set piece 100 units out
46
+ // still throws and receives shade instead of popping lit at the near box's
47
+ // edge. 2048² over 256 units ≈ 8 texels/unit — soft, and read at distances
48
+ // where soft is what a shadow looks like anyway. 16 MB where the near map
49
+ // is 64. Depth reach scales with the span (same eye direction, deeper box),
50
+ // keeping the containment invariant checkable from the specs alone.
51
+ { span: 256, back: 288, near: 1, far: 560, mapSize: 2048 },
52
+ ]
53
+
54
+ /**
55
+ * One cascade's view-projection, following the camera target.
56
+ *
57
+ * The target is snapped to this cascade's OWN texel quantum in the light's
58
+ * right/up plane, so a moving volume doesn't shimmer its shadow edges while
59
+ * running — each cascade snaps to its own grid, coarser maps snapping coarser.
60
+ *
61
+ * Writes the 16 floats into `out` at `offset` and returns `out`.
62
+ */
63
+ export function buildShadowVP(
64
+ target: { x: number; y: number; z: number },
65
+ sunDirection: { x: number; y: number; z: number },
66
+ cascade: ShadowCascade,
67
+ out: Float32Array,
68
+ offset: number,
69
+ ): Float32Array {
70
+ const dir = new Vec3(sunDirection.x, sunDirection.y, sunDirection.z)
71
+ dir.normalize()
72
+ const up = Math.abs(dir.y) > 0.99 ? new Vec3(0, 0, -1) : new Vec3(0, 1, 0)
73
+
74
+ const t = new Vec3(target.x, target.y, target.z)
75
+ const right = Vec3.crossInto(up, dir, new Vec3(0, 0, 0)).normalize()
76
+ const upv = Vec3.crossInto(dir, right, new Vec3(0, 0, 0))
77
+ const texel = cascade.span / cascade.mapSize
78
+ const tr = Math.round(t.dot(right) / texel) * texel
79
+ const tu = Math.round(t.dot(upv) / texel) * texel
80
+ const td = t.dot(dir)
81
+ const snapped = new Vec3(
82
+ right.x * tr + upv.x * tu + dir.x * td,
83
+ right.y * tr + upv.y * tu + dir.y * td,
84
+ right.z * tr + upv.z * tu + dir.z * td,
85
+ )
86
+
87
+ const eye = new Vec3(snapped.x - dir.x * cascade.back, snapped.y - dir.y * cascade.back, snapped.z - dir.z * cascade.back)
88
+ const view = Mat4.lookAt(eye, snapped, up)
89
+ const half = cascade.span / 2
90
+ // The shadow map keeps the NON-reversed convention (orthographicLh maps z to
91
+ // [0,1] front-to-back) — reversing it buys nothing for an ortho box and the
92
+ // +2 pipeline depth bias is signed against this direction.
93
+ const proj = Mat4.orthographicLh(-half, half, -half, half, cascade.near, cascade.far)
94
+ const vp = proj.multiply(view)
95
+ out.set(vp.values, offset)
96
+ return out
97
+ }
package/src/vmd-loader.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { Quat, Vec3 } from "./math"
2
2
 
3
- export interface BoneFrame {
3
+ interface BoneFrame {
4
4
  boneName: string
5
5
  frame: number
6
6
  rotation: Quat
@@ -8,7 +8,7 @@ export interface BoneFrame {
8
8
  interpolation: Uint8Array // 64 bytes of interpolation parameters
9
9
  }
10
10
 
11
- export interface MorphFrame {
11
+ interface MorphFrame {
12
12
  morphName: string
13
13
  frame: number
14
14
  weight: number // 0.0 to 1.0