@umicat/three-sdk 1.41.0 → 1.43.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.
@@ -15,6 +15,12 @@
15
15
  * Version 2. A version-1 document (the upward-firing disc emitter of 1.35) is
16
16
  * still accepted: `parseVfx` upgrades it to the v2 emitter that plays the same.
17
17
  *
18
+ * Version 8 (1.43) adds PARAMETERS and BINDINGS (`params`, `bindings`, ADR-056
19
+ * step 4): named numbers a game sets, carried into the layers.
20
+ *
21
+ * Version 7 (1.42) adds TRACKS and CLIPS (`tracks`, `clips`, `startClip`,
22
+ * ADR-056 step 2): keyframes on a layer's numbers, and named states.
23
+ *
18
24
  * Version 6 (1.40) adds TRAILS (`emitter.trail`, ADR-055 step 4).
19
25
  *
20
26
  * Version 5 (1.39) adds LIGHTS (`lights`, point lights, ADR-055 step 3).
@@ -30,6 +36,7 @@
30
36
  import { parseMaterial, materialTextures, materialDefaults } from './material.js';
31
37
  import { parseMeshShape } from './mesh.js';
32
38
  import { trailSampling, TRAIL_POINT_BUDGET } from './trail.js';
39
+ import { parseTimeline } from './timeline.js';
33
40
  export const LIMITS = { emitters: 8, layers: 8, meshes: 8, lights: 2, particles: 4000, cells: 4096, bursts: 16, children: 4, curvePoints: 8, gradientStops: 16 };
34
41
  /** Every emitter field's value when a document leaves it out. */
35
42
  export function emitterDefaults() {
@@ -189,8 +196,8 @@ export function parseVfx(value) {
189
196
  const d = structuredClone(value);
190
197
  const number = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
191
198
  const color = (v) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v);
192
- if (![2, 3, 4, 5, 6].includes(d.version))
193
- fail(`version must be 2-6 (or 1, which is upgraded)${typeof d.version === 'number' && d.version > 6 ? ` -- version ${d.version} was written by a newer editor: update @umicat/three-sdk` : ''}`);
199
+ if (![2, 3, 4, 5, 6, 7, 8].includes(d.version))
200
+ fail(`version must be 2-8 (or 1, which is upgraded)${typeof d.version === 'number' && d.version > 8 ? ` -- version ${d.version} was written by a newer editor: update @umicat/three-sdk` : ''}`);
194
201
  if (typeof d.name !== 'string' || !d.name.trim() || d.name.length > 80)
195
202
  fail('name must be 1-80 characters');
196
203
  if (!number(d.seed, 1, 2147483646) || !Number.isInteger(d.seed))
@@ -540,14 +547,22 @@ export function parseVfx(value) {
540
547
  if (f.blend !== 'normal' && f.blend !== 'additive')
541
548
  fail(`${at}.blend must be "normal" or "additive"`);
542
549
  });
550
+ // Last: a track's target is resolved against the completed layers.
551
+ parseTimeline(d, fail, checkCurve);
543
552
  return d;
544
553
  }
545
554
  /**
546
- * The lowest format version that can express this document: 3 when any
547
- * emitter uses the material look, else 2. The editor and the agent write
548
- * this, so an effect that needs nothing new still plays on 1.36.
555
+ * The lowest format version that can express this document: 8 with
556
+ * parameters or bindings, 7 with tracks
557
+ * or clips, 6 with trails, 5 with lights, 4 with meshes, 3 with the material
558
+ * look, else 2. The editor and the agent write this, so an effect that needs
559
+ * nothing new still plays on an older SDK.
549
560
  */
550
561
  export function minimumVersion(d) {
562
+ if (d.params !== undefined || d.bindings !== undefined)
563
+ return 8;
564
+ if (d.tracks !== undefined || d.clips !== undefined || d.startClip !== undefined)
565
+ return 7;
551
566
  if (d.emitters.some((e) => e.trail !== undefined))
552
567
  return 6;
553
568
  if (d.lights !== undefined)
@@ -4,6 +4,7 @@ export { VfxInstance } from './VfxInstance.js';
4
4
  export * from './material.js';
5
5
  export * from './mesh.js';
6
6
  export * from './trail.js';
7
+ export * from './timeline.js';
7
8
  export type { VfxInstanceOptions, VfxTextureSource } from './VfxInstance.js';
8
9
  export { loadVfx, VfxEffect, siblingUrl, prepareSheetTexture } from './load.js';
9
10
  export type { LoadVfxOptions } from './load.js';
package/dist/vfx/index.js CHANGED
@@ -9,4 +9,5 @@ export { VfxInstance } from './VfxInstance.js';
9
9
  export * from './material.js';
10
10
  export * from './mesh.js';
11
11
  export * from './trail.js';
12
+ export * from './timeline.js';
12
13
  export { loadVfx, VfxEffect, siblingUrl, prepareSheetTexture } from './load.js';
@@ -206,7 +206,18 @@ export interface CompiledMaterial {
206
206
  displace: boolean;
207
207
  dispose(): void;
208
208
  }
209
- export declare function compileMaterial(m: Material): CompiledMaterial;
209
+ /**
210
+ * `live`: numbers a track drives (ADR-056), kept in the shader even while
211
+ * they are 0 -- `offset<i>` (a mask's offset) and `displace`. Without it a
212
+ * track that starts at 0 would write a uniform nothing reads.
213
+ */
214
+ export declare function compileMaterial(m: Material, live?: ReadonlySet<string>): CompiledMaterial;
215
+ /**
216
+ * Writes a material's NUMBERS into an already-compiled shader's uniforms --
217
+ * what a track changes. Structure (masks, sources, blends, curves, the
218
+ * gradient map) is not touched: that needs `compileMaterial`.
219
+ */
220
+ export declare function updateMaterialUniforms(c: CompiledMaterial, m: Material): void;
210
221
  /**
211
222
  * Starting points, so nobody begins from a blank material. Each is what one
212
223
  * of the reference rebuilds needed (ADR-055), with the numbers rounded.
@@ -403,7 +403,12 @@ float vfxShapeGlow(vec2 p, vec4 k){ float r = length(p); if (r >= 1.0) return 0.
403
403
  float vfxShapeStar(vec2 p, vec4 k){ float r = length(p); if (r >= 1.0) return 0.0; float e = mix(0.12, 1.0, pow(abs(cos(k.y * atan(p.y, p.x) * 0.5)), 1.0 + k.z * 12.0)); return max(1.0 - smoothstep(e * 0.5, e, r), (1.0 - smoothstep(0.0, 0.25, r)) * 0.8); }
404
404
  float vfxShapeRing(vec2 p, vec4 k){ float d = abs(length(p) - k.w); float w = max(k.y, 1e-3); return 1.0 - smoothstep(w * (1.0 - k.x), w, d); }
405
405
  `;
406
- export function compileMaterial(m) {
406
+ /**
407
+ * `live`: numbers a track drives (ADR-056), kept in the shader even while
408
+ * they are 0 -- `offset<i>` (a mask's offset) and `displace`. Without it a
409
+ * track that starts at 0 would write a uniform nothing reads.
410
+ */
411
+ export function compileMaterial(m, live = new Set()) {
407
412
  const curves = curveFields(m), row = new Map(curves.map((c, i) => [c.key, i]));
408
413
  const rows = Math.max(1, curves.length);
409
414
  const value = (key, uniform) => row.has(key) ? `vfxCurve(${glslFloat(row.get(key))}, life.x)` : uniform;
@@ -453,7 +458,7 @@ export function compileMaterial(m) {
453
458
  fns.push(`float vfxMask${i}(vec2 uv0, vec2 life){ vec2 uv = uv0; ${polar}
454
459
  uv = uv * uScale${i} - uScroll${i} * uTime${random};
455
460
  float sa = sin(uSpin${i} * uTime + uTurn${i}), ca = cos(uSpin${i} * uTime + uTurn${i}); uv = mat2(ca, sa, -sa, ca) * (uv - 0.5) + 0.5;
456
- float b = ${sourceCode(s, i, k.polar)};${k.invert ? ' b = 1.0 - b;' : ''}${k.levels ? ` b = smoothstep(uLevels${i}.x, uLevels${i}.y, b);` : ''}${isCurve(k.offset) || k.offset !== 0 ? ` b = clamp(b + ${value(`offset${i}`, `uOffset${i}`)}, 0.0, 1.0);` : ''}
461
+ float b = ${sourceCode(s, i, k.polar)};${k.invert ? ' b = 1.0 - b;' : ''}${k.levels ? ` b = smoothstep(uLevels${i}.x, uLevels${i}.y, b);` : ''}${isCurve(k.offset) || k.offset !== 0 || live.has(`offset${i}`) ? ` b = clamp(b + ${value(`offset${i}`, `uOffset${i}`)}, 0.0, 1.0);` : ''}
457
462
  return b; }`);
458
463
  body.push(i === 0 ? ' m = vfxMask0(uv0, life);' : ` { float a = m, b = vfxMask${i}(uv0, life); m = mix(a, ${BLEND_CODE[k.blend]}, clamp(${value(`strength${i}`, `uStrength${i}`)}, 0.0, 1.0)); }`);
459
464
  });
@@ -481,12 +486,47 @@ ${body.join('\n')}
481
486
  return vec4(rgb * max(0.0, ${value('emission', 'uEmission')}), ramp.a * alpha * clamp(${value('opacity', 'uOpacity')}, 0.0, 1.0));
482
487
  }`;
483
488
  return {
484
- code, uniforms, images, alphaMode: m.alphaMode, displace: m.masks.length > 0 && (isCurve(m.displace.amount) || m.displace.amount !== 0),
489
+ code, uniforms, images, alphaMode: m.alphaMode, displace: m.masks.length > 0 && (isCurve(m.displace.amount) || m.displace.amount !== 0 || live.has('displace')),
485
490
  dispose() { for (const t of owned)
486
491
  t.dispose(); for (const t of noise)
487
492
  releaseNoiseTexture(t); },
488
493
  };
489
494
  }
495
+ /**
496
+ * Writes a material's NUMBERS into an already-compiled shader's uniforms --
497
+ * what a track changes. Structure (masks, sources, blends, curves, the
498
+ * gradient map) is not touched: that needs `compileMaterial`.
499
+ */
500
+ export function updateMaterialUniforms(c, m) {
501
+ const u = c.uniforms;
502
+ if (!isCurve(m.dissolve))
503
+ u.uDissolve.value = m.dissolve;
504
+ if (!isCurve(m.threshold))
505
+ u.uThreshold.value = m.threshold;
506
+ if (!isCurve(m.opacity))
507
+ u.uOpacity.value = m.opacity;
508
+ if (!isCurve(m.emission))
509
+ u.uEmission.value = m.emission;
510
+ u.uSoftness.value = m.softness;
511
+ u.uPower.value = m.power;
512
+ u.uCutoff.value = m.cutoff;
513
+ u.uEdge.value.set(m.edge.width, m.edge.emission, 0);
514
+ u.uEdgeColor.value.set(m.edge.color);
515
+ u.uRim.value.set(m.rim.strength, m.rim.power, m.rim.mode === 'edge' ? 1 : 0);
516
+ u.uDisplace.value.set(isCurve(m.displace.amount) ? 1 : m.displace.amount, m.displace.offset);
517
+ m.masks.forEach((k, i) => {
518
+ u[`uScale${i}`].value.set(k.scale[0], k.scale[1]);
519
+ u[`uScroll${i}`].value.set(k.scroll[0], k.scroll[1]);
520
+ u[`uSpin${i}`].value = k.spin * Math.PI / 180;
521
+ u[`uTurn${i}`].value = k.rotation * Math.PI / 180;
522
+ if (!isCurve(k.offset))
523
+ u[`uOffset${i}`].value = k.offset;
524
+ if (!isCurve(k.strength))
525
+ u[`uStrength${i}`].value = k.strength;
526
+ if (k.levels)
527
+ u[`uLevels${i}`].value.set(k.levels[0], k.levels[1]);
528
+ });
529
+ }
490
530
  // ------------------------------------------------------------------ presets
491
531
  const noise = (p) => ({ ...noiseDefaults(), ...p });
492
532
  const mask = (source, p = {}) => ({ ...maskDefaults(source), ...p });
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Tracks and clips (format v7, umicat-design ADR-056 step 2): Godot's
3
+ * AnimationPlayer for an effect. A TRACK animates one value of one layer
4
+ * over a CLIP's time; clips are the states a persistent effect goes through
5
+ * (open -> idle -> close).
6
+ *
7
+ * This file is the data side: the shapes, what a target path may name, the
8
+ * parser's checks and the sampling. `VfxInstance` turns resolved targets into
9
+ * setters once, at construction.
10
+ */
11
+ import { type VfxDocument, type Curve } from './document.js';
12
+ /** number; [x, y] or [x, y, z]; "#rrggbb"; or a boolean (`enabled` only). */
13
+ export type TrackValue = number | number[] | string | boolean;
14
+ /**
15
+ * `[time, value, ease?]`. `ease` is Godot's transition exponent as-is, applied
16
+ * to the segment the key STARTS: 1 linear (the default), 2 ease in, 0.5 ease
17
+ * out, negative in-out, 0 hold this value until the next key.
18
+ */
19
+ export type TrackKey = [number, TrackValue] | [number, TrackValue, number];
20
+ export interface Track {
21
+ /** `<emitters|meshes|lights|flipbooks>.<layer id>.<field>[.<field>...]`, e.g. `meshes.ring.material.masks.1.strength`. */
22
+ target: string;
23
+ keys: TrackKey[];
24
+ /** linear (default); smooth: Godot's cubic; step: each key holds until the next. Booleans always step. */
25
+ interp?: 'linear' | 'smooth' | 'step';
26
+ }
27
+ export interface Clip {
28
+ name: string;
29
+ /** Seconds. Emitter windows and bursts, mesh-layer and light windows and track times all count from the clip's start. */
30
+ duration: number;
31
+ /** Repeat this clip until told otherwise. */
32
+ loop: boolean;
33
+ /** The clip that follows when this one ends (open -> idle). A clip with neither `loop` nor `next` ends the effect. */
34
+ next?: string;
35
+ tracks: Track[];
36
+ }
37
+ export declare const TIMELINE_LIMITS: {
38
+ readonly clips: 8;
39
+ readonly tracks: 64;
40
+ readonly keys: 16;
41
+ readonly params: 8;
42
+ readonly bindings: 16;
43
+ };
44
+ /**
45
+ * (format v8, ADR-056 step 4) A named number on the effect: a charge level, a
46
+ * health fraction, how open a portal is. Tracks can animate it
47
+ * (`params.<name>`) and a game can set it (`instance.set(name, v)`); it does
48
+ * nothing by itself -- bindings carry it into the layers.
49
+ */
50
+ export interface Param {
51
+ name: string;
52
+ value: number;
53
+ min: number;
54
+ max: number;
55
+ }
56
+ /**
57
+ * Writes a parameter into a layer's number or vector (a vector gets it in
58
+ * every component), every step, after the clip's tracks -- so a field that is
59
+ * both tracked and bound follows the binding. `map` reshapes it: sampled at
60
+ * the parameter's place in its range (0 at min, 1 at max), its value is what
61
+ * is written. Without `map` the parameter goes in as it is.
62
+ */
63
+ export interface ParamBinding {
64
+ param: string;
65
+ target: string;
66
+ map?: Curve;
67
+ }
68
+ export type TrackKind = 'number' | 'vec2' | 'vec3' | 'color' | 'bool';
69
+ export type LayerKind = 'emitters' | 'meshes' | 'lights' | 'flipbooks' | 'params';
70
+ export interface ResolvedTarget {
71
+ kind: LayerKind;
72
+ index: number;
73
+ id: string;
74
+ /** Field path inside the layer; numbers index lists (`masks.1`). */
75
+ path: (string | number)[];
76
+ value: TrackKind;
77
+ /** Per component, for numbers and vectors. */
78
+ bounds: [number, number];
79
+ /** A Range field (`speed`, `size`, ...): a track writes a plain number. */
80
+ range: boolean;
81
+ /** The material this path is inside (its path in the layer), if any -- the instance refreshes its uniforms. */
82
+ material?: (string | number)[];
83
+ }
84
+ /** Resolves `target` against a COMPLETE (parsed) document, or says why not. */
85
+ export declare function resolveTarget(d: VfxDocument, target: unknown): ResolvedTarget | string;
86
+ /**
87
+ * Every target a track (or, for numbers and vectors, a binding) may name in
88
+ * this document, found by walking its layers and asking `resolveTarget` --
89
+ * so the list can never offer what the parser would refuse. For a picker.
90
+ */
91
+ export declare function animatableTargets(d: VfxDocument): {
92
+ target: string;
93
+ value: TrackKind;
94
+ }[];
95
+ /** Things that parse but are probably not what was meant: a field both keyed and bound (the binding wins). */
96
+ export declare function timelineWarnings(d: VfxDocument): string[];
97
+ type Fail = (why: string) => never;
98
+ /** Checks `tracks`, `clips` and `startClip` against a parsed document (layers already complete). */
99
+ export declare function parseTimeline(d: VfxDocument, fail: Fail, checkCurve: (v: unknown, at: string) => void): void;
100
+ /** The clips an instance plays: the document's own, or one named `main` made of `duration`, `loop` and `tracks`. */
101
+ export declare function effectClips(d: VfxDocument): {
102
+ clips: Clip[];
103
+ start: string;
104
+ };
105
+ /** Godot's `ease(x, c)`, exactly (core/math/math_funcs.cpp). */
106
+ export declare function godotEase(x: number, c: number): number;
107
+ export declare const linearToHex: (rgb: number[]) => string;
108
+ /** A track ready to sample: numbers per key (colours in linear space, booleans 0/1). */
109
+ export interface SampledTrack {
110
+ kind: TrackKind;
111
+ times: number[];
112
+ values: number[][];
113
+ eases: number[];
114
+ interp: 'linear' | 'smooth' | 'step';
115
+ }
116
+ export declare function prepareTrack(t: Track, kind: TrackKind): SampledTrack;
117
+ /** The track's value at clip time `t`, into `out` (one number per component). Before the first key it holds the first; after the last, the last. */
118
+ export declare function sampleTrack(s: SampledTrack, t: number, out: number[]): number[];
119
+ export {};