reze-engine 0.69.5 → 0.69.6

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.
@@ -0,0 +1,132 @@
1
+ // Words an effect is handed — `#param text NAME <default words>`.
2
+ //
3
+ // The engine sets every string an effect's text dials can show (each dial's
4
+ // value and every key on its track) into ONE picture per effect, a row a
5
+ // string, and a dial's slot in the params block holds the rect of the string it
6
+ // shows now. Changing the words, by hand or by a key, is a rect write; the
7
+ // picture is redrawn only when a string it has never held arrives.
8
+ //
9
+ // Canvas2D, as the lyric atlas: it sets every script the platform does, CJK
10
+ // included, which a glyph atlas cannot promise. The look — fill, edge, glow —
11
+ // is the author's, in WGSL, from the coverage rzText_NAME answers.
12
+ //
13
+ // FIELD MODULE ONLY, where the picture is bound. Every other module the file is
14
+ // spliced into gets stubs answering zero, so one effect file compiles in every
15
+ // mount it has.
16
+ /** The font size the rows are set at, in texels. A boss's name drawn 60 pixels
17
+ * tall on a 4K frame is still minified from this. */
18
+ export const EFFECT_TEXT_PX = 96;
19
+ const PAD = 8;
20
+ const MAX_W = 4096;
21
+ const MAX_H = 8192;
22
+ /** The CSS font for a size: `#font`'s words with the size put where CSS wants
23
+ * it — after style, variant and weight, before the family. */
24
+ export function effectTextFont(font, px) {
25
+ const css = font?.css ?? "serif";
26
+ const words = css.split(/\s+/);
27
+ let k = 0;
28
+ while (k < words.length - 1 && /^(normal|italic|oblique|small-caps|bold|bolder|lighter|\d{3})$/i.test(words[k]))
29
+ k++;
30
+ return [...words.slice(0, k), `${px}px`, words.slice(k).join(" ")].join(" ").trim();
31
+ }
32
+ function canvas2d(w, h) {
33
+ if (typeof OffscreenCanvas !== "undefined") {
34
+ const canvas = new OffscreenCanvas(w, h);
35
+ const ctx = canvas.getContext("2d");
36
+ if (ctx)
37
+ return { canvas, ctx };
38
+ }
39
+ if (typeof document === "undefined")
40
+ return null;
41
+ const canvas = document.createElement("canvas");
42
+ canvas.width = w;
43
+ canvas.height = h;
44
+ const ctx = canvas.getContext("2d");
45
+ return ctx ? { canvas, ctx } : null;
46
+ }
47
+ /**
48
+ * Set `strings` into one sheet, a row each. Every row is the font's full box
49
+ * (its ascent and descent, not the string's own ink), so two strings in one
50
+ * face have one height and their aspects compare. A string too wide for the
51
+ * sheet is set smaller in its own row rather than cut. Null without a canvas.
52
+ */
53
+ export function rasterEffectText(strings, font) {
54
+ const list = [...new Set(strings.filter((s) => s.length > 0))];
55
+ const probe = canvas2d(1, 1);
56
+ if (!probe)
57
+ return null;
58
+ const css = effectTextFont(font, EFFECT_TEXT_PX);
59
+ const tracking = (font?.tracking ?? 0) * EFFECT_TEXT_PX;
60
+ const setUp = (ctx, px) => {
61
+ ctx.font = px === EFFECT_TEXT_PX ? css : effectTextFont(font, px);
62
+ if ("letterSpacing" in ctx)
63
+ ctx.letterSpacing = `${(tracking * px) / EFFECT_TEXT_PX}px`;
64
+ ctx.textBaseline = "alphabetic";
65
+ ctx.textAlign = "left";
66
+ };
67
+ setUp(probe.ctx, EFFECT_TEXT_PX);
68
+ const box = probe.ctx.measureText("Hg国");
69
+ const ascent = Math.ceil(box.fontBoundingBoxAscent || EFFECT_TEXT_PX * 0.9);
70
+ const descent = Math.ceil(box.fontBoundingBoxDescent || EFFECT_TEXT_PX * 0.25);
71
+ const rowH = ascent + descent + PAD * 2;
72
+ const rows = list.map((s) => {
73
+ // Tracking adds after every glyph, the last one too; trim it off the box.
74
+ const w = probe.ctx.measureText(s).width - tracking;
75
+ const px = w + PAD * 2 > MAX_W ? Math.floor((EFFECT_TEXT_PX * (MAX_W - PAD * 2)) / w) : EFFECT_TEXT_PX;
76
+ return { s, px, w: Math.min(MAX_W, Math.ceil((w * px) / EFFECT_TEXT_PX) + PAD * 2) };
77
+ });
78
+ const width = Math.max(1, ...rows.map((r) => r.w));
79
+ const height = Math.max(1, Math.min(MAX_H, rows.length * rowH));
80
+ const sheet = canvas2d(width, height);
81
+ if (!sheet)
82
+ return null;
83
+ const { ctx } = sheet;
84
+ ctx.clearRect(0, 0, width, height);
85
+ ctx.fillStyle = "#ffffff";
86
+ const rects = new Map();
87
+ rows.forEach((r, i) => {
88
+ const top = i * rowH;
89
+ if (top + rowH > height)
90
+ return;
91
+ setUp(ctx, r.px);
92
+ // A smaller row stays centred on the same baseline band.
93
+ const base = top + rowH / 2 + ((ascent - descent) * r.px) / (2 * EFFECT_TEXT_PX);
94
+ ctx.fillText(r.s, PAD, base);
95
+ rects.set(r.s, [0, top / height, r.w / width, (top + rowH) / height]);
96
+ });
97
+ return { source: sheet.canvas, width, height, rects };
98
+ }
99
+ /**
100
+ * rzText_NAME(uv) and rzTextAspect_NAME() for each text dial. uv runs 0..1
101
+ * across the string's own box, y up, like rzLyricText; the answer is glyph
102
+ * coverage. textureSampleLevel, so it is legal after any branch.
103
+ */
104
+ export function effectTextWgsl(names, real, binding, sampler) {
105
+ if (names.length === 0)
106
+ return "";
107
+ if (!real) {
108
+ return names
109
+ .map((n) => `fn rzText_${n}(uv: vec2f) -> f32 { return 0.0; }\nfn rzTextAspect_${n}() -> f32 { return 1.0; }\n`)
110
+ .join("");
111
+ }
112
+ return (
113
+ /* wgsl */ `
114
+ @group(0) @binding(${binding}) var _rzEffectText: texture_2d<f32>;
115
+
116
+ fn _rzTextAt(r: vec4f, uv: vec2f) -> f32 {
117
+ if (r.z <= r.x || uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) { return 0.0; }
118
+ let at = vec2f(mix(r.x, r.z, uv.x), mix(r.w, r.y, uv.y));
119
+ return textureSampleLevel(_rzEffectText, ${sampler}, at, 0.0).r;
120
+ }
121
+
122
+ fn _rzTextAspect(r: vec4f) -> f32 {
123
+ let h = r.w - r.y;
124
+ if (h <= 0.0) { return 1.0; }
125
+ let dim = vec2f(textureDimensions(_rzEffectText));
126
+ return ((r.z - r.x) * dim.x) / (h * dim.y);
127
+ }
128
+ ` +
129
+ names
130
+ .map((n) => `fn rzText_${n}(uv: vec2f) -> f32 { return _rzTextAt(params.${n}, uv); }\nfn rzTextAspect_${n}() -> f32 { return _rzTextAspect(params.${n}); }\n`)
131
+ .join(""));
132
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "reze-engine",
3
- "version": "0.69.5",
3
+ "version": "0.69.6",
4
4
  "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
package/src/engine.ts CHANGED
@@ -62,6 +62,7 @@ import {
62
62
  import { packHalf, type HdrImage } from "./hdr"
63
63
  import { evalIrradianceSH, projectIrradianceSH, gradientIrradianceSH } from "./ibl"
64
64
  import { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, LYRICS_FLOATS, lyricsApi, packLyrics, type LyricLine, type LyricRect } from "./shaders/lyrics-api"
65
+ import { effectTextFont, effectTextWgsl, rasterEffectText, EFFECT_TEXT_PX, type EffectTextFont } from "./shaders/text-api"
65
66
  import {
66
67
  sceneTargets as sceneTargetsFor,
67
68
  sceneColorFormats,
@@ -608,10 +609,10 @@ type SunOptions = {
608
609
  shadow?: number
609
610
  }
610
611
 
611
- /** An effect param: number → f32, vector-like → vec3f (see setEffect).
612
- * Structural {x,y,z} rather than the Vec3 class so JSON-derived values (a
613
- * shared scene document's params) pass straight in. */
614
- export type EffectParamValue = number | { x: number; y: number; z: number } | EffectPointValue | EffectBoneValue
612
+ /** An effect param: number → f32, vector-like → vec3f, words → a text dial
613
+ * (see setEffect). Structural {x,y,z} rather than the Vec3 class so
614
+ * JSON-derived values (a shared scene document's params) pass straight in. */
615
+ export type EffectParamValue = number | string | { x: number; y: number; z: number } | EffectPointValue | EffectBoneValue
615
616
 
616
617
  /** A `point` dial: a world position, or — with `model` — an offset from where
617
618
  * that character stands, so the point travels with her. */
@@ -1664,6 +1665,10 @@ const TEXTURE_EXTENSION_GUESSES = [".png", ".jpg", ".jpeg", ".bmp", ".tga", ".dd
1664
1665
  */
1665
1666
  function paramValue(p: EffectParamDecl, given: EffectParamValue | undefined): EffectParamValue {
1666
1667
  if (p.kind === "bone") return isBoneValue(given) ? given : { bone: typeof p.value === "string" ? p.value : "", model: null }
1668
+ if (p.kind === "text") return typeof given === "string" ? given : typeof p.value === "string" ? p.value : ""
1669
+ // A lag is filled from the dial it trails, every frame.
1670
+ if (p.kind === "lag") return 0
1671
+ if (typeof given === "string") given = undefined
1667
1672
  if (given !== undefined) return p.kind === "int" && typeof given === "number" ? Math.round(given) : given
1668
1673
  if (p.kind === "color" && typeof p.value === "string") {
1669
1674
  const n = parseInt(p.value.slice(1), 16)
@@ -1697,6 +1702,8 @@ function castSubjectKey(subjects: readonly string[] | null): string {
1697
1702
  }
1698
1703
 
1699
1704
  const EFFECT_PARAMS_BINDING = 7
1705
+ /** The field module's binding for an effect's words — see text-api. */
1706
+ const EFFECT_TEXT_BINDING = 33
1700
1707
  const EFFECT_PARAMS_BINDING_GRID = 9
1701
1708
 
1702
1709
  /** How a mount receives the effect's declared dials: a generator for the struct
@@ -1705,7 +1712,8 @@ const EFFECT_PARAMS_BINDING_GRID = 9
1705
1712
  * emitted — WGSL has no empty struct, and a bound buffer nothing reads is a
1706
1713
  * layout mismatch. */
1707
1714
  type EffectParamsBinding = {
1708
- wgsl: (binding: number) => string
1715
+ /** `text` is true only for the field module, where the words are bound. */
1716
+ wgsl: (binding: number, text?: boolean) => string
1709
1717
  buffer: GPUBuffer | null
1710
1718
  }
1711
1719
 
@@ -1871,6 +1879,17 @@ const FIELD_LAYER_BLEND_ADDITIVE: GPUBlendState = {
1871
1879
  alpha: { srcFactor: "one", dstFactor: "one", operation: "add" },
1872
1880
  }
1873
1881
 
1882
+ /** An effect's text dials: every string they can show (values and keys), the
1883
+ * picture those are set in, and which one each dial shows now. */
1884
+ type EffectText = {
1885
+ font: EffectTextFont
1886
+ strings: Set<string>
1887
+ rects: Map<string, LyricRect>
1888
+ texture: GPUTexture | null
1889
+ view: GPUTextureView | null
1890
+ shown: Map<string, string>
1891
+ }
1892
+
1874
1893
  /**
1875
1894
  * One installed effect, whole.
1876
1895
  *
@@ -1892,15 +1911,18 @@ interface EffectInstance {
1892
1911
  /** One firing's length in seconds, from `#duration`. 0 = ambient. Reported
1893
1912
  * back at install so a host can place the effect at its own length. */
1894
1913
  duration: number
1895
- paramLayout: Map<string, { offset: number; comps: 1 | 3 }>
1914
+ paramLayout: Map<string, { offset: number; comps: 1 | 3 | 4 }>
1896
1915
  paramsBuffer: GPUBuffer | null
1897
1916
  paramsData: Float32Array<ArrayBuffer>
1917
+ /** The words its text dials can show, set into one picture — see text-api.
1918
+ * Null when it declares none. */
1919
+ text: EffectText | null
1898
1920
  /** The dials the engine resolves every frame rather than once: each bone
1899
1921
  * dial's bone and character, and each point dial set to follow one. */
1900
1922
  paramBindings: Map<string, EffectBoneValue | EffectPointValue>
1901
1923
  /** Dials driven by keys, by name — see setEffectParamTrack. Bone keys index
1902
1924
  * `bones`, since the sampler carries numbers. */
1903
- paramTracks: Map<string, { keys: ParamKey[]; bones: EffectBoneValue[]; last: ParamValue | null }>
1925
+ paramTracks: Map<string, { keys: ParamKey[]; bones: EffectBoneValue[]; texts: string[]; last: ParamValue | null }>
1904
1926
  /** This effect IS a mirror — see the `#mirror` directive. Draws no shader;
1905
1927
  * the engine reads its dials and folds the scene through the plane. */
1906
1928
  hasMirror: boolean
@@ -1993,6 +2015,9 @@ interface EffectInstance {
1993
2015
  simStep: number
1994
2016
  /** Empty the particle pool and the grid before this frame's step. */
1995
2017
  simReset: boolean
2018
+ /** The cast its pool and grid were last stepped against — subject mask and
2019
+ * count. A scheduled effect held still re-seeds when this moves. */
2020
+ seededCast: number
1996
2021
  /**
1997
2022
  * The four durations this effect's `#dissolve` takes the cast apart over, as
1998
2023
  * its source wrote them. Null unless it declared one. A dial of the same name
@@ -5210,6 +5235,7 @@ export class Engine {
5210
5235
  { binding: 19, resource: { buffer: this.midiBuffer } },
5211
5236
  { binding: 24, resource: { buffer: this.lyricsBuffer } },
5212
5237
  { binding: 25, resource: this.lyricsTextureView },
5238
+ { binding: EFFECT_TEXT_BINDING, resource: owner.text?.view ?? this.trailFallbackView },
5213
5239
  // The size uniform for the pair THIS effect draws into.
5214
5240
  { binding: 14, resource: { buffer: this.fieldUniformBuffers[owner.fieldLayer] } },
5215
5241
  { binding: 22, resource: { buffer: owner.fieldClock ?? this.fieldUniformBuffers[owner.fieldLayer] } },
@@ -5705,7 +5731,7 @@ export class Engine {
5705
5731
  // over the declared default; a name it passes that the source never declared
5706
5732
  // is ignored, because a field nothing reads is a binding nothing reads.
5707
5733
  const entries: [string, EffectParamValue][] = d.params.map((p) => [p.name, paramValue(p, params?.[p.name])])
5708
- const layout = new Map<string, { offset: number; comps: 1 | 3 }>()
5734
+ const layout = new Map<string, { offset: number; comps: 1 | 3 | 4 }>()
5709
5735
  const fields: string[] = []
5710
5736
  let cursor = 0
5711
5737
  for (const p of d.params) {
@@ -5727,6 +5753,15 @@ export class Engine {
5727
5753
  }
5728
5754
  continue
5729
5755
  }
5756
+ if (p.kind === "text") {
5757
+ // The rect of the string it shows in the effect's picture: u0, vTop,
5758
+ // u1, vBottom — read through rzText_NAME().
5759
+ const offset = Math.ceil(cursor / 16) * 16
5760
+ layout.set(p.name, { offset: offset / 4, comps: 4 })
5761
+ fields.push(` ${p.name}: vec4f,`)
5762
+ cursor = offset + 16
5763
+ continue
5764
+ }
5730
5765
  const isVec = p.kind === "color" || p.kind === "vec3" || p.kind === "point"
5731
5766
  const align = isVec ? 16 : 4
5732
5767
  const offset = Math.ceil(cursor / align) * align
@@ -5744,6 +5779,8 @@ export class Engine {
5744
5779
  paramBindings.set(name, value)
5745
5780
  continue
5746
5781
  }
5782
+ // Words get their rect once the picture is set, after the mounts build.
5783
+ if (typeof value === "string") continue
5747
5784
  if (typeof value === "number") paramsData[slot.offset] = value
5748
5785
  else {
5749
5786
  if ("model" in value && value.model) paramBindings.set(name, value)
@@ -5772,11 +5809,13 @@ export class Engine {
5772
5809
  * one states the number it can spare. Empty when nothing is declared: WGSL
5773
5810
  * has no empty struct, and a binding nothing reads is a layout mismatch.
5774
5811
  */
5775
- const paramsWgsl = (binding: number) =>
5812
+ const textNames = d.params.filter((p) => p.kind === "text").map((p) => p.name)
5813
+ const paramsWgsl = (binding: number, text = false) =>
5776
5814
  entries.length
5777
- ? `struct EffectParams {\n${fields.join("\n")}\n}\n@group(0) @binding(${binding}) var<uniform> params: EffectParams;\n${boneWgsl}`
5815
+ ? `struct EffectParams {\n${fields.join("\n")}\n}\n@group(0) @binding(${binding}) var<uniform> params: EffectParams;\n${boneWgsl}` +
5816
+ effectTextWgsl(textNames, text, EFFECT_TEXT_BINDING, "_rzGridSamp")
5778
5817
  : ""
5779
- const paramsDecl = paramsWgsl(EFFECT_PARAMS_BINDING)
5818
+ const paramsDecl = paramsWgsl(EFFECT_PARAMS_BINDING, true)
5780
5819
 
5781
5820
  // ── Compile with validation captured, not thrown at the console. Line
5782
5821
  // numbers in diagnostics are rebased to the USER's source.
@@ -5980,6 +6019,16 @@ export class Engine {
5980
6019
  paramLayout: layout,
5981
6020
  paramsBuffer,
5982
6021
  paramsData,
6022
+ text: textNames.length
6023
+ ? {
6024
+ font: d.font,
6025
+ strings: new Set(entries.flatMap(([, v]) => (typeof v === "string" && v ? [v] : []))),
6026
+ rects: new Map(),
6027
+ texture: null,
6028
+ view: null,
6029
+ shown: new Map(entries.flatMap(([n, v]) => (typeof v === "string" ? [[n, v] as [string, string]] : []))),
6030
+ }
6031
+ : null,
5983
6032
  paramBindings,
5984
6033
  paramTracks: new Map(),
5985
6034
  hasMirror: d.mirror,
@@ -6022,6 +6071,7 @@ export class Engine {
6022
6071
  sim: { start: null, time: null },
6023
6072
  simStep: 0,
6024
6073
  simReset: false,
6074
+ seededCast: -1,
6025
6075
  dissolve: d.dissolve ? dissolveConstants(authored) : null,
6026
6076
  ground: d.ground ? { color: new Vec3(...d.ground.color), noise: d.ground.noise } : null,
6027
6077
  // Its OWN resolution, no longer the scene's: an effect that never asked
@@ -6055,6 +6105,8 @@ export class Engine {
6055
6105
  trails,
6056
6106
  lights,
6057
6107
  }
6108
+ // Before the swap binds it, so the field's first frame already has words.
6109
+ if (instance.text) this.layoutEffectText(instance)
6058
6110
  return { ok: true, instance, warnings }
6059
6111
  }
6060
6112
 
@@ -6113,6 +6165,7 @@ export class Engine {
6113
6165
  const [identity, gamma] = await this.compositePipelines(false, false)
6114
6166
  for (const e of this.effects) {
6115
6167
  e.paramsBuffer?.destroy()
6168
+ e.text?.texture?.destroy()
6116
6169
  e.lights?.uniform.destroy()
6117
6170
  e.fieldClock?.destroy()
6118
6171
  }
@@ -6192,6 +6245,7 @@ export class Engine {
6192
6245
  // that was running is only torn down now.
6193
6246
  for (const e of this.effects) {
6194
6247
  e.paramsBuffer?.destroy()
6248
+ e.text?.texture?.destroy()
6195
6249
  e.lights?.uniform.destroy()
6196
6250
  e.fieldClock?.destroy()
6197
6251
  }
@@ -6834,12 +6888,20 @@ export class Engine {
6834
6888
  count.dispatchWorkgroups(1)
6835
6889
  count.end()
6836
6890
  }
6837
- const cp = encoder.beginComputePass({ label: "particles" })
6838
- cp.setPipeline(p.compute)
6839
- cp.setBindGroup(0, bind)
6840
- if (p.live) cp.dispatchWorkgroupsIndirect(p.live.indirect, 0)
6841
- else cp.dispatchWorkgroups(Math.ceil(p.count / 64))
6842
- cp.end()
6891
+ // A reset runs the pool TWICE: once to spawn every slot, once to step
6892
+ // what spawned, at dt 0. A dispatch either inits a slot or steps it, and
6893
+ // an effect that poses in its step (Pochita's bones, which its triangles
6894
+ // are drawn from) has no pose after the init alone. Playing, the next
6895
+ // frame's step supplied it; paused at a clip's start no next frame
6896
+ // steps, and the pet stayed collapsed — invisible — until play.
6897
+ for (let pass = e.simReset ? 2 : 1; pass > 0; pass--) {
6898
+ const cp = encoder.beginComputePass({ label: "particles" })
6899
+ cp.setPipeline(p.compute)
6900
+ cp.setBindGroup(0, bind)
6901
+ if (p.live) cp.dispatchWorkgroupsIndirect(p.live.indirect, 0)
6902
+ else cp.dispatchWorkgroups(Math.ceil(p.count / 64))
6903
+ cp.end()
6904
+ }
6843
6905
  }
6844
6906
  }
6845
6907
 
@@ -7625,7 +7687,10 @@ export class Engine {
7625
7687
  if (isBoneValue(value)) fx.paramBindings.set(name, value)
7626
7688
  return false
7627
7689
  }
7628
- if (isBoneValue(value)) return false
7690
+ if (decl.kind === "text") return typeof value === "string" ? this.showEffectText(fx, name, value) : false
7691
+ // A lag is its source's, trailing; nothing writes it by hand.
7692
+ if (decl.kind === "lag") return false
7693
+ if (isBoneValue(value) || typeof value === "string") return false
7629
7694
  if (typeof value === "number") {
7630
7695
  fx.paramsData[slot.offset] = decl.kind === "int" ? Math.round(value) : value
7631
7696
  return true
@@ -7657,8 +7722,10 @@ export class Engine {
7657
7722
  fx.paramTracks.delete(name)
7658
7723
  return true
7659
7724
  }
7660
- const holds = decl.kind === "bool" || decl.kind === "enum" || decl.kind === "bone"
7725
+ if (decl.kind === "lag") return false
7726
+ const holds = decl.kind === "bool" || decl.kind === "enum" || decl.kind === "bone" || decl.kind === "text"
7661
7727
  const bones: EffectBoneValue[] = []
7728
+ const texts: string[] = []
7662
7729
  const sorted = [...keys].sort((a, b) => a.time - b.time)
7663
7730
  const track: ParamKey[] = []
7664
7731
  for (const k of sorted) {
@@ -7666,7 +7733,11 @@ export class Engine {
7666
7733
  if (decl.kind === "bone") {
7667
7734
  if (!isBoneValue(k.value)) continue
7668
7735
  v = bones.push(k.value) - 1
7669
- } else if (typeof k.value === "number") v = k.value
7736
+ } else if (decl.kind === "text") {
7737
+ if (typeof k.value !== "string") continue
7738
+ v = texts.push(k.value) - 1
7739
+ } else if (typeof k.value === "string") continue
7740
+ else if (typeof k.value === "number") v = k.value
7670
7741
  else if (isBoneValue(k.value)) continue
7671
7742
  else v = [k.value.x, k.value.y, k.value.z]
7672
7743
  track.push({
@@ -7676,7 +7747,10 @@ export class Engine {
7676
7747
  ...(!holds && k.curve && k.ease !== "hold" ? { b: k.curve } : {}),
7677
7748
  })
7678
7749
  }
7679
- fx.paramTracks.set(name, { keys: track, bones, last: null })
7750
+ fx.paramTracks.set(name, { keys: track, bones, texts, last: null })
7751
+ // Every word a key can show goes into the picture now, so playing past a
7752
+ // key is a rect write and never a redraw.
7753
+ if (fx.text && texts.some((t) => t && !fx.text!.strings.has(t))) this.layoutEffectText(fx)
7680
7754
  this.evaluateEffectParams()
7681
7755
  return true
7682
7756
  }
@@ -7701,6 +7775,9 @@ export class Engine {
7701
7775
  if (decl?.kind === "bone") {
7702
7776
  const bone = typeof v === "number" ? track.bones[v] : undefined
7703
7777
  if (bone) fx.paramBindings.set(name, bone)
7778
+ } else if (decl?.kind === "text") {
7779
+ const words = typeof v === "number" ? track.texts[v] : undefined
7780
+ if (words !== undefined) dirty = this.showEffectText(fx, name, words) || dirty
7704
7781
  } else if (typeof v === "number") {
7705
7782
  dirty = this.writeEffectParam(fx, name, v) || dirty
7706
7783
  } else {
@@ -7710,11 +7787,140 @@ export class Engine {
7710
7787
  }
7711
7788
  }
7712
7789
  if (fx.paramBindings.size) dirty = this.resolveParamBindings(fx) || dirty
7790
+ for (const p of fx.paramDecls) {
7791
+ if (p.kind !== "lag") continue
7792
+ transport ??= this.transportTime()
7793
+ dirty = this.evaluateLag(fx, p, transport) || dirty
7794
+ }
7713
7795
  if (dirty) this.device.queue.writeBuffer(fx.paramsBuffer, 0, fx.paramsData)
7714
7796
  }
7715
7797
  this.applyXray()
7716
7798
  }
7717
7799
 
7800
+ /**
7801
+ * A `lag` dial at time t: its source, trailing — what a game's health bar
7802
+ * draws as the chunk just lost. After the source falls it HOLDS where it was
7803
+ * for `hold` seconds, then drains at `rate` a second until it meets the
7804
+ * source again; a rise is met at once.
7805
+ *
7806
+ * Sampled from the source's KEYS, never from what the frames before this one
7807
+ * happened to see, so a scrub, a loop and a frame-by-frame export all draw
7808
+ * the same chunk. A source with no keys has no past: the lag is the source.
7809
+ */
7810
+ private evaluateLag(fx: EffectInstance, p: EffectParamDecl, t: number): boolean {
7811
+ const slot = fx.paramLayout.get(p.name)
7812
+ const src = p.source ? fx.paramLayout.get(p.source) : undefined
7813
+ if (!slot || !src) return false
7814
+ const d = fx.paramsData
7815
+ let v = d[src.offset]
7816
+ const track = p.source ? fx.paramTracks.get(p.source) : undefined
7817
+ if (track && track.keys.length > 0) {
7818
+ const hold = p.hold ?? 0
7819
+ const rate = Math.max(p.rate ?? 1, 1e-6)
7820
+ const decl = fx.paramDecls.find((q) => q.name === p.source)
7821
+ const range = decl?.min !== undefined && decl.max !== undefined ? Math.abs(decl.max - decl.min) : 1
7822
+ // Far enough back that anything older has drained past the full range.
7823
+ const span = hold + range / rate
7824
+ const at = (s: number) => {
7825
+ const sv = sampleParamTrack(track.keys, s)
7826
+ if (typeof sv !== "number") return
7827
+ v = Math.max(v, sv - rate * Math.max(0, t - s - hold))
7828
+ }
7829
+ // A fine grid, plus every key in the window exactly — a hit is a key,
7830
+ // and the instant before it is the value the chunk holds.
7831
+ const step = 1 / 120
7832
+ for (let s = t; s >= t - span; s -= step) at(s)
7833
+ for (const k of track.keys) {
7834
+ if (k.t > t || k.t < t - span) continue
7835
+ at(k.t)
7836
+ at(k.t - 1e-4)
7837
+ }
7838
+ }
7839
+ if (d[slot.offset] === v) return false
7840
+ d[slot.offset] = v
7841
+ return true
7842
+ }
7843
+
7844
+ /** Show `words` on a text dial: its rect into the block. A string the
7845
+ * picture has never held is set into it first, which redraws the picture
7846
+ * and writes the block itself. Returns whether the caller still has to. */
7847
+ private showEffectText(fx: EffectInstance, name: string, words: string): boolean {
7848
+ const t = fx.text
7849
+ if (!t) return false
7850
+ t.shown.set(name, words)
7851
+ if (words && !t.strings.has(words)) {
7852
+ this.layoutEffectText(fx)
7853
+ return false
7854
+ }
7855
+ return this.writeTextRect(fx, name, words)
7856
+ }
7857
+
7858
+ private writeTextRect(fx: EffectInstance, name: string, words: string): boolean {
7859
+ const slot = fx.paramLayout.get(name)
7860
+ if (!slot || !fx.text) return false
7861
+ const r = fx.text.rects.get(words) ?? [0, 0, 0, 0]
7862
+ const d = fx.paramsData
7863
+ let moved = false
7864
+ for (let k = 0; k < 4; k++) {
7865
+ if (d[slot.offset + k] === r[k]) continue
7866
+ d[slot.offset + k] = r[k]
7867
+ moved = true
7868
+ }
7869
+ return moved
7870
+ }
7871
+
7872
+ /**
7873
+ * Set every string an effect's text dials can show into its picture, upload
7874
+ * it and point each dial at its row. Re-binds only when the picture changes
7875
+ * SIZE. Once the face has loaded, a second pass sets it again — a web font
7876
+ * the page has not fetched yet draws in the fallback the first time.
7877
+ */
7878
+ private layoutEffectText(fx: EffectInstance, fontLoaded = false): void {
7879
+ const t = fx.text
7880
+ if (!t || !this.device) return
7881
+ // What the dials show now and what their keys can show — rebuilt rather
7882
+ // than added to, so typing a name does not keep every half-typed word.
7883
+ t.strings = new Set([...t.shown.values(), ...[...fx.paramTracks.values()].flatMap((k) => k.texts)].filter((w) => w.length > 0))
7884
+ const sheet = rasterEffectText([...t.strings], t.font)
7885
+ t.rects = sheet?.rects ?? new Map()
7886
+ const w = sheet?.width ?? 1
7887
+ const h = sheet?.height ?? 1
7888
+ if (!t.texture || t.texture.width !== w || t.texture.height !== h) {
7889
+ t.texture?.destroy()
7890
+ t.texture = this.device.createTexture({
7891
+ label: "effect text",
7892
+ size: [w, h],
7893
+ format: "r8unorm",
7894
+ usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
7895
+ })
7896
+ t.view = t.texture.createView()
7897
+ if (this.effects.includes(fx)) this.rebuildFieldBindGroup()
7898
+ }
7899
+ // premultipliedAlpha, as the lyric atlas: white glyphs on a clear canvas
7900
+ // arrive with coverage in red, antialiased edges intact.
7901
+ if (sheet) {
7902
+ this.device.queue.copyExternalImageToTexture(
7903
+ { source: sheet.source },
7904
+ { texture: t.texture, premultipliedAlpha: true },
7905
+ [w, h],
7906
+ )
7907
+ }
7908
+ for (const [name, words] of t.shown) this.writeTextRect(fx, name, words)
7909
+ if (fx.paramsBuffer) this.device.queue.writeBuffer(fx.paramsBuffer, 0, fx.paramsData)
7910
+ const fonts = typeof document !== "undefined" ? document.fonts : undefined
7911
+ if (!fontLoaded && fonts && t.font) {
7912
+ const css = effectTextFont(t.font, EFFECT_TEXT_PX)
7913
+ if (!fonts.check(css, [...t.strings].join(""))) {
7914
+ fonts
7915
+ .load(css, [...t.strings].join(""))
7916
+ .then(() => {
7917
+ if (this.effects.includes(fx)) this.layoutEffectText(fx, true)
7918
+ })
7919
+ .catch(() => {})
7920
+ }
7921
+ }
7922
+ }
7923
+
7718
7924
  /**
7719
7925
  * Each `#xray` effect's window, onto every character it is aimed at: a
7720
7926
  * rectangle on the frame from its X, Y, WIDTH and HEIGHT dials (fractions of
@@ -7984,6 +8190,15 @@ export class Engine {
7984
8190
  fx.sim = sim.clock
7985
8191
  fx.simStep = sim.step
7986
8192
  fx.simReset = sim.reset
8193
+ // A pool held still is seeded ONCE, against whoever was in the cast on
8194
+ // that frame. A scene opened paused at its first frame seeds before her
8195
+ // model has loaded, so an effect that spawns off the cast (chicks round
8196
+ // her feet) is born empty — and a held pool is never stepped again to
8197
+ // ask. So the seed is taken again when the cast it read has changed. The
8198
+ // cast was written earlier this frame (updateCameraUniforms).
8199
+ const cast = fx.subjectMask * 16 + fx.subjectCount
8200
+ if (sim.clock.start !== null && !fx.simReset && fx.simStep === 0 && cast !== fx.seededCast) fx.simReset = true
8201
+ if (fx.simReset || fx.simStep > 0) fx.seededCast = cast
7987
8202
  // Its own clock, expressed the way the mounts read it. Every mount
7988
8203
  // derives time from the epoch against sceneClock, so this one write moves
7989
8204
  // the field, the particles, the ribbons, lightEmit and the grid together
@@ -8603,6 +8818,8 @@ export class Engine {
8603
8818
  { binding: 24, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "read-only-storage" } },
8604
8819
  // The lyric line atlas, for rzLyricText.
8605
8820
  { binding: 25, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
8821
+ // This effect's own words, for rzText_NAME — a 1x1 when it has none.
8822
+ { binding: EFFECT_TEXT_BINDING, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
8606
8823
  { binding: 14, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
8607
8824
  // This effect's own clock — see the field shader's note on why it is
8608
8825
  // not viewU[6].x.