@umicat/three-sdk 1.42.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.
package/README.md CHANGED
@@ -157,7 +157,19 @@ as in Godot -- an `idle` with no tracks keeps a portal open.
157
157
  `fx.seek(t, clip?)` replays to that moment at the fixed step (a clip reached
158
158
  by `next` is played through its predecessors).
159
159
 
160
- **Write the lowest version.** `minimumVersion(doc)` is 7 with tracks or clips, 6 with trails, 5 with lights, 4 with meshes, 3 with a
160
+ **Parameters and bindings (version 8, 1.43.0, ADR-056 step 4).** `params:
161
+ [{ name: 'open', value: 1, min: 0, max: 1 }]` are named numbers a game sets
162
+ (`fx.set('open', 0.4)`, `fx.get('open')`, `fx.paramNames`) and tracks can
163
+ animate (`params.open`). `bindings: [{ param: 'open', target:
164
+ 'lights.glow.range', map? }]` write a parameter into a layer's number or
165
+ vector (every component) after the tracks, every step -- so one number can
166
+ open a portal's light, particles and material together, which Godot's packs
167
+ do with a controller script. `map` is a Curve sampled at the parameter's place
168
+ in its range (0 at min, 1 at max). `animatableTargets(doc)` lists every target
169
+ the parser accepts; `timelineWarnings(doc)` names a field that is both keyed
170
+ and bound (the binding wins).
171
+
172
+ **Write the lowest version.** `minimumVersion(doc)` is 8 with parameters or bindings, 7 with tracks or clips, 6 with trails, 5 with lights, 4 with meshes, 3 with a
161
173
  material, else 2; the editor and the agent write that, so an effect that needs nothing
162
174
  new stays version 2 and keeps playing on 1.36.
163
175
 
@@ -43,6 +43,9 @@ export declare class VfxInstance {
43
43
  private clipStart;
44
44
  /** The static value of every field some track writes, for `reset()`. */
45
45
  private restores;
46
+ private wires;
47
+ /** Each parameter's value in the document, for `reset()`. */
48
+ private paramDefaults;
46
49
  /** Particles born so far: hashed into each particle's `seed`. */
47
50
  private serial;
48
51
  private accumulator;
@@ -55,8 +58,21 @@ export declare class VfxInstance {
55
58
  private enter;
56
59
  /** Writes every track of the current clip at the clip's time. Fields no track of it names hold their last value. */
57
60
  private applyTracks;
61
+ /** Parameters into their fields: after the tracks, so a bound field follows its parameter. */
62
+ private applyBindings;
63
+ private writeTracks;
58
64
  /** A clip that ended hands over to its `next`, exactly at its end -- after landing on its own last values, as Godot does. */
59
65
  private advanceClip;
66
+ /**
67
+ * Sets parameter `name` (clamped to its min-max) and carries it into its
68
+ * bindings at once. A track on the parameter in the clip playing writes it
69
+ * again on the next step -- the clip wins while it animates it, as in Godot.
70
+ */
71
+ set(name: string, value: number): void;
72
+ /** A parameter's value now, or undefined when the effect has no such parameter. */
73
+ get(name: string): number | undefined;
74
+ /** Every parameter this effect has. */
75
+ get paramNames(): string[];
60
76
  /** The clip playing now (`main` for an effect without clips). */
61
77
  get clip(): string;
62
78
  /** Every clip this effect has, in document order. */
@@ -179,6 +179,9 @@ export class VfxInstance {
179
179
  this.clipStart = 0;
180
180
  /** The static value of every field some track writes, for `reset()`. */
181
181
  this.restores = [];
182
+ this.wires = [];
183
+ /** Each parameter's value in the document, for `reset()`. */
184
+ this.paramDefaults = [];
182
185
  /** Particles born so far: hashed into each particle's `seed`. */
183
186
  this.serial = 0;
184
187
  this.accumulator = 0;
@@ -236,6 +239,21 @@ export class VfxInstance {
236
239
  });
237
240
  this.clips.set(clip.name, { name: clip.name, duration: clip.duration, loop: clip.loop, next: clip.next, bindings });
238
241
  });
242
+ const params = this.document.params ?? [];
243
+ this.paramDefaults = params.map((p) => p.value);
244
+ for (const b of this.document.bindings ?? []) {
245
+ const r = resolveTarget(this.document, b.target);
246
+ let parent = this.document[r.kind][r.index];
247
+ for (const seg of r.path.slice(0, -1))
248
+ parent = parent[seg];
249
+ const key = r.path[r.path.length - 1], sync = this.syncer(r.kind, r.index);
250
+ const where = `${r.kind}.${r.index}.${r.path.join('.')}`;
251
+ if (!restored.has(where)) {
252
+ restored.add(where);
253
+ this.restores.push({ parent, key, base: structuredClone(parent[key]), sync });
254
+ }
255
+ this.wires.push({ param: params.find((p) => p.name === b.param), map: b.map, parent, key, kind: r.value, sync });
256
+ }
239
257
  this.startClip = this.clips.get(timeline.start);
240
258
  this.enter(this.startClip, 0);
241
259
  this.applyTracks();
@@ -243,6 +261,9 @@ export class VfxInstance {
243
261
  }
244
262
  /** Refreshes what was derived from a layer's config when a track wrote into it. */
245
263
  syncer(kind, index) {
264
+ // A parameter derives nothing itself; the bindings read it after every write.
265
+ if (kind === 'params')
266
+ return () => { };
246
267
  if (kind === 'emitters')
247
268
  return () => {
248
269
  const l = this.particleLayers[index], c = l.config, u = l.material.uniforms;
@@ -298,8 +319,28 @@ export class VfxInstance {
298
319
  }
299
320
  /** Writes every track of the current clip at the clip's time. Fields no track of it names hold their last value. */
300
321
  applyTracks(c = this.cur, at) {
301
- if (!c.bindings.length)
322
+ if (c.bindings.length)
323
+ this.writeTracks(c, at);
324
+ this.applyBindings();
325
+ }
326
+ /** Parameters into their fields: after the tracks, so a bound field follows its parameter. */
327
+ applyBindings() {
328
+ if (!this.wires.length)
302
329
  return;
330
+ const dirty = new Set();
331
+ for (const w of this.wires) {
332
+ const p = w.param;
333
+ const v = w.map ? sampleCurve(w.map, (p.value - p.min) / (p.max - p.min)) : p.value;
334
+ if (w.kind === 'number')
335
+ w.parent[w.key] = v;
336
+ else
337
+ w.parent[w.key].fill(v);
338
+ dirty.add(w.sync);
339
+ }
340
+ for (const f of dirty)
341
+ f();
342
+ }
343
+ writeTracks(c, at) {
303
344
  const ct = at ?? this.clipTime, t = at !== undefined ? at : c.loop ? ct % c.duration : ct;
304
345
  const dirty = new Set();
305
346
  for (const b of c.bindings) {
@@ -327,6 +368,25 @@ export class VfxInstance {
327
368
  this.enter(this.clips.get(this.cur.next), this.clipStart + this.cur.duration);
328
369
  }
329
370
  }
371
+ /**
372
+ * Sets parameter `name` (clamped to its min-max) and carries it into its
373
+ * bindings at once. A track on the parameter in the clip playing writes it
374
+ * again on the next step -- the clip wins while it animates it, as in Godot.
375
+ */
376
+ set(name, value) {
377
+ const p = this.document.params?.find((x) => x.name === name);
378
+ if (!p)
379
+ throw new Error(`VfxInstance.set: no parameter "${name}" (this effect has ${this.paramNames.join(', ') || 'none'})`);
380
+ if (!Number.isFinite(value))
381
+ return;
382
+ p.value = Math.max(p.min, Math.min(p.max, value));
383
+ this.applyBindings();
384
+ this.draw();
385
+ }
386
+ /** A parameter's value now, or undefined when the effect has no such parameter. */
387
+ get(name) { return this.document.params?.find((x) => x.name === name)?.value; }
388
+ /** Every parameter this effect has. */
389
+ get paramNames() { return (this.document.params ?? []).map((p) => p.name); }
330
390
  /** The clip playing now (`main` for an effect without clips). */
331
391
  get clip() { return this.cur.name; }
332
392
  /** Every clip this effect has, in document order. */
@@ -578,6 +638,7 @@ export class VfxInstance {
578
638
  r.parent[r.key] = structuredClone(r.base);
579
639
  dirty.add(r.sync);
580
640
  }
641
+ (this.document.params ?? []).forEach((p, i) => { p.value = this.paramDefaults[i]; });
581
642
  for (const f of dirty)
582
643
  f();
583
644
  this.enter(this.startClip, 0);
@@ -15,6 +15,9 @@
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
+ *
18
21
  * Version 7 (1.42) adds TRACKS and CLIPS (`tracks`, `clips`, `startClip`,
19
22
  * ADR-056 step 2): keyframes on a layer's numbers, and named states.
20
23
  *
@@ -33,7 +36,7 @@
33
36
  import { type Material } from './material.js';
34
37
  import { type MeshShape, type MeshLayer } from './mesh.js';
35
38
  import { type Trail } from './trail.js';
36
- import { type Track, type Clip } from './timeline.js';
39
+ import { type Track, type Clip, type Param, type ParamBinding } from './timeline.js';
37
40
  /** A number, or `[min, max]`: picked uniformly per particle. */
38
41
  export type Range = number | [number, number];
39
42
  export type Vec3 = [number, number, number];
@@ -240,7 +243,7 @@ export interface Flipbook {
240
243
  blend: 'normal' | 'additive';
241
244
  }
242
245
  export interface VfxDocument {
243
- version: 2 | 3 | 4 | 5 | 6 | 7;
246
+ version: 2 | 3 | 4 | 5 | 6 | 7 | 8;
244
247
  name: string;
245
248
  seed: number;
246
249
  /** Seconds in one cycle. A looping effect repeats it; a one-shot stops emitting after it. */
@@ -263,6 +266,10 @@ export interface VfxDocument {
263
266
  clips?: Clip[];
264
267
  /** (version 7) The clip that plays first, and after `reset()`. Default: the first. */
265
268
  startClip?: string;
269
+ /** (version 8) Named numbers a game can set and tracks can animate. */
270
+ params?: Param[];
271
+ /** (version 8) A parameter written into a layer's number or vector, optionally through a curve. */
272
+ bindings?: ParamBinding[];
266
273
  }
267
274
  /**
268
275
  * A point light, created once with the effect and dimmed to 0 when it is off
@@ -391,12 +398,13 @@ export declare function sampleGradient(g: Gradient, t: number, out?: number[]):
391
398
  */
392
399
  export declare function parseVfx(value: unknown): VfxDocument;
393
400
  /**
394
- * The lowest format version that can express this document: 7 with tracks
401
+ * The lowest format version that can express this document: 8 with
402
+ * parameters or bindings, 7 with tracks
395
403
  * or clips, 6 with trails, 5 with lights, 4 with meshes, 3 with the material
396
404
  * look, else 2. The editor and the agent write this, so an effect that needs
397
405
  * nothing new still plays on an older SDK.
398
406
  */
399
- export declare function minimumVersion(d: Pick<VfxDocument, 'emitters' | 'meshes' | 'lights'> & Partial<Pick<VfxDocument, 'tracks' | 'clips' | 'startClip'>>): 2 | 3 | 4 | 5 | 6 | 7;
407
+ export declare function minimumVersion(d: Pick<VfxDocument, 'emitters' | 'meshes' | 'lights'> & Partial<Pick<VfxDocument, 'tracks' | 'clips' | 'startClip' | 'params' | 'bindings'>>): 2 | 3 | 4 | 5 | 6 | 7 | 8;
400
408
  /** A new mesh layer: a soft additive ring on the ground, for the editor's "Add" and the agent. */
401
409
  export declare function meshLayerDefaults(): Omit<MeshLayer, 'id'>;
402
410
  /** A new light: a warm glow just above the origin, lit for the whole cycle. */
@@ -15,6 +15,9 @@
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
+ *
18
21
  * Version 7 (1.42) adds TRACKS and CLIPS (`tracks`, `clips`, `startClip`,
19
22
  * ADR-056 step 2): keyframes on a layer's numbers, and named states.
20
23
  *
@@ -193,8 +196,8 @@ export function parseVfx(value) {
193
196
  const d = structuredClone(value);
194
197
  const number = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
195
198
  const color = (v) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v);
196
- if (![2, 3, 4, 5, 6, 7].includes(d.version))
197
- fail(`version must be 2-7 (or 1, which is upgraded)${typeof d.version === 'number' && d.version > 7 ? ` -- 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` : ''}`);
198
201
  if (typeof d.name !== 'string' || !d.name.trim() || d.name.length > 80)
199
202
  fail('name must be 1-80 characters');
200
203
  if (!number(d.seed, 1, 2147483646) || !Number.isInteger(d.seed))
@@ -545,16 +548,19 @@ export function parseVfx(value) {
545
548
  fail(`${at}.blend must be "normal" or "additive"`);
546
549
  });
547
550
  // Last: a track's target is resolved against the completed layers.
548
- parseTimeline(d, fail);
551
+ parseTimeline(d, fail, checkCurve);
549
552
  return d;
550
553
  }
551
554
  /**
552
- * The lowest format version that can express this document: 7 with tracks
555
+ * The lowest format version that can express this document: 8 with
556
+ * parameters or bindings, 7 with tracks
553
557
  * or clips, 6 with trails, 5 with lights, 4 with meshes, 3 with the material
554
558
  * look, else 2. The editor and the agent write this, so an effect that needs
555
559
  * nothing new still plays on an older SDK.
556
560
  */
557
561
  export function minimumVersion(d) {
562
+ if (d.params !== undefined || d.bindings !== undefined)
563
+ return 8;
558
564
  if (d.tracks !== undefined || d.clips !== undefined || d.startClip !== undefined)
559
565
  return 7;
560
566
  if (d.emitters.some((e) => e.trail !== undefined))
@@ -8,7 +8,7 @@
8
8
  * parser's checks and the sampling. `VfxInstance` turns resolved targets into
9
9
  * setters once, at construction.
10
10
  */
11
- import { type VfxDocument } from './document.js';
11
+ import { type VfxDocument, type Curve } from './document.js';
12
12
  /** number; [x, y] or [x, y, z]; "#rrggbb"; or a boolean (`enabled` only). */
13
13
  export type TrackValue = number | number[] | string | boolean;
14
14
  /**
@@ -38,9 +38,35 @@ export declare const TIMELINE_LIMITS: {
38
38
  readonly clips: 8;
39
39
  readonly tracks: 64;
40
40
  readonly keys: 16;
41
+ readonly params: 8;
42
+ readonly bindings: 16;
41
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
+ }
42
68
  export type TrackKind = 'number' | 'vec2' | 'vec3' | 'color' | 'bool';
43
- export type LayerKind = 'emitters' | 'meshes' | 'lights' | 'flipbooks';
69
+ export type LayerKind = 'emitters' | 'meshes' | 'lights' | 'flipbooks' | 'params';
44
70
  export interface ResolvedTarget {
45
71
  kind: LayerKind;
46
72
  index: number;
@@ -57,9 +83,20 @@ export interface ResolvedTarget {
57
83
  }
58
84
  /** Resolves `target` against a COMPLETE (parsed) document, or says why not. */
59
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[];
60
97
  type Fail = (why: string) => never;
61
98
  /** Checks `tracks`, `clips` and `startClip` against a parsed document (layers already complete). */
62
- export declare function parseTimeline(d: VfxDocument, fail: Fail): void;
99
+ export declare function parseTimeline(d: VfxDocument, fail: Fail, checkCurve: (v: unknown, at: string) => void): void;
63
100
  /** The clips an instance plays: the document's own, or one named `main` made of `duration`, `loop` and `tracks`. */
64
101
  export declare function effectClips(d: VfxDocument): {
65
102
  clips: Clip[];
@@ -9,7 +9,7 @@
9
9
  * setters once, at construction.
10
10
  */
11
11
  import { EMITTER_NUMBERS, EMITTER_RANGES, EMITTER_VECTORS, FLIPBOOK_RANGES } from './document.js';
12
- export const TIMELINE_LIMITS = { clips: 8, tracks: 64, keys: 16 };
12
+ export const TIMELINE_LIMITS = { clips: 8, tracks: 64, keys: 16, params: 8, bindings: 16 };
13
13
  const MATERIAL_FIELDS = {
14
14
  dissolve: [-1, 2], threshold: [-1, 2], opacity: [0, 1], emission: [0, 32], softness: [0, 1], power: [.1, 8], cutoff: [0, 1],
15
15
  'edge.width': [0, 1], 'edge.emission': [0, 16], 'edge.color': 'color', 'rim.strength': [0, 1], 'rim.power': [.25, 8],
@@ -71,8 +71,14 @@ export function resolveTarget(d, target) {
71
71
  if (typeof target !== 'string' || !target)
72
72
  return 'target must be a path like "emitters.sparks.rate"';
73
73
  const [kind, id, ...rest] = target.split('.');
74
- if (kind === 'params')
75
- return 'parameters (params.*) are not supported yet';
74
+ if (kind === 'params') {
75
+ const ps = d.params ?? [], i = ps.findIndex((p) => p.name === id);
76
+ if (i < 0)
77
+ return `there is no parameter "${id}" in this effect${ps.length ? ` (it has ${ps.map((p) => p.name).join(', ')})` : ''}`;
78
+ if (rest.length)
79
+ return `${target}: a parameter is one number; name it as params.${id}`;
80
+ return { kind: 'params', index: i, id, path: ['value'], value: 'number', bounds: [ps[i].min, ps[i].max], range: false };
81
+ }
76
82
  if (!LAYER_KINDS.includes(kind))
77
83
  return `"${kind}" is not a layer kind (expected emitters, meshes, lights or flipbooks)`;
78
84
  const k = kind;
@@ -116,6 +122,47 @@ export function resolveTarget(d, target) {
116
122
  const m = path.indexOf('material');
117
123
  return { kind: k, index, id, path, value, bounds: Array.isArray(bound) ? [bound[0], bound[1]] : [0, 1], range, material: m >= 0 ? path.slice(0, m + 1) : undefined };
118
124
  }
125
+ /**
126
+ * Every target a track (or, for numbers and vectors, a binding) may name in
127
+ * this document, found by walking its layers and asking `resolveTarget` --
128
+ * so the list can never offer what the parser would refuse. For a picker.
129
+ */
130
+ export function animatableTargets(d) {
131
+ const out = [];
132
+ const test = (p) => { const r = resolveTarget(d, p); if (typeof r !== 'string')
133
+ out.push({ target: p, value: r.value }); };
134
+ const walk = (o, prefix, depth) => {
135
+ if (depth > 6)
136
+ return;
137
+ for (const [k, v] of Object.entries(o)) {
138
+ if (k === 'id')
139
+ continue;
140
+ const p = `${prefix}.${k}`;
141
+ if (Array.isArray(v)) {
142
+ if (v.length && typeof v[0] === 'object')
143
+ v.forEach((x, i) => x && typeof x === 'object' && !Array.isArray(x) && walk(x, `${p}.${i}`, depth + 1));
144
+ else
145
+ test(p);
146
+ }
147
+ else if (v && typeof v === 'object')
148
+ walk(v, p, depth + 1);
149
+ else
150
+ test(p);
151
+ }
152
+ };
153
+ for (const k of LAYER_KINDS)
154
+ for (const layer of (d[k] ?? []))
155
+ walk(layer, `${k}.${layer.id}`, 0);
156
+ for (const p of d.params ?? [])
157
+ out.push({ target: `params.${p.name}`, value: 'number' });
158
+ return out;
159
+ }
160
+ /** Things that parse but are probably not what was meant: a field both keyed and bound (the binding wins). */
161
+ export function timelineWarnings(d) {
162
+ const bound = new Map((d.bindings ?? []).map((b) => [b.target, b.param]));
163
+ const tracked = new Set([...(d.tracks ?? []), ...(d.clips ?? []).flatMap((c) => c.tracks)].map((t) => t.target));
164
+ return [...bound].filter(([t]) => tracked.has(t)).map(([t, p]) => `${t} has keys, but parameter "${p}" is bound to it, so the keys never show`);
165
+ }
119
166
  const num = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
120
167
  function checkTracks(d, tracks, at, fail) {
121
168
  if (!Array.isArray(tracks) || tracks.length > TIMELINE_LIMITS.tracks)
@@ -161,8 +208,64 @@ function checkTracks(d, tracks, at, fail) {
161
208
  return t;
162
209
  });
163
210
  }
211
+ /** Checks `params` and `bindings` (format v8): before tracks, which may animate a parameter. */
212
+ function parseParams(d, fail, checkCurve) {
213
+ if (d.params === undefined && d.bindings === undefined)
214
+ return;
215
+ if (d.version < 8)
216
+ fail('params and bindings are version 8: set "version": 8 (needs @umicat/three-sdk 1.43 or later)');
217
+ if (d.params !== undefined && (!Array.isArray(d.params) || d.params.length > TIMELINE_LIMITS.params))
218
+ fail(`params must be a list of 0-${TIMELINE_LIMITS.params}`);
219
+ const names = new Set();
220
+ (d.params ?? []).forEach((p, i) => {
221
+ const at = `params[${i}]`;
222
+ if (!p || typeof p !== 'object' || Array.isArray(p))
223
+ fail(`${at} must be { name, value, min, max }`);
224
+ for (const k of Object.keys(p))
225
+ if (!['name', 'value', 'min', 'max'].includes(k))
226
+ fail(`${at}.${k} is not a parameter field (expected name, value, min, max)`);
227
+ if (typeof p.name !== 'string' || !/^[a-z0-9_-]{1,40}$/i.test(p.name))
228
+ fail(`${at}.name must be 1-40 of a-z 0-9 _ -`);
229
+ if (names.has(p.name))
230
+ fail(`${at}.name "${p.name}" is used twice`);
231
+ names.add(p.name);
232
+ if (!num(p.min, -1000, 1000) || !num(p.max, -1000, 1000) || !(p.max > p.min))
233
+ fail(`${at} needs min < max, each -1000-1000`);
234
+ if (!num(p.value, p.min, p.max))
235
+ fail(`${at}.value must be ${p.min}-${p.max} (its min-max)`);
236
+ });
237
+ if (d.bindings === undefined)
238
+ return;
239
+ if (!Array.isArray(d.bindings) || d.bindings.length > TIMELINE_LIMITS.bindings)
240
+ fail(`bindings must be a list of 0-${TIMELINE_LIMITS.bindings}`);
241
+ const seen = new Set();
242
+ d.bindings.forEach((b, i) => {
243
+ const at = `bindings[${i}]`;
244
+ if (!b || typeof b !== 'object' || Array.isArray(b))
245
+ fail(`${at} must be { param, target, map? }`);
246
+ for (const k of Object.keys(b))
247
+ if (!['param', 'target', 'map'].includes(k))
248
+ fail(`${at}.${k} is not a binding field (expected param, target, map)`);
249
+ if (!names.has(b.param))
250
+ fail(`${at}.param "${b.param}" is not a parameter in this effect`);
251
+ const r = resolveTarget(d, b.target);
252
+ if (typeof r === 'string')
253
+ fail(`${at}.target ${r}`);
254
+ const res = r;
255
+ if (res.kind === 'params')
256
+ fail(`${at}.target is a parameter; a binding drives a layer's field`);
257
+ if (res.value === 'bool' || res.value === 'color')
258
+ fail(`${at}.target ${b.target} is ${res.value === 'bool' ? 'on/off' : 'a colour'}; a binding drives a number or a vector`);
259
+ if (seen.has(b.target))
260
+ fail(`${at}.target "${b.target}" is bound twice`);
261
+ seen.add(b.target);
262
+ if (b.map !== undefined)
263
+ checkCurve(b.map, `${at}.map`);
264
+ });
265
+ }
164
266
  /** Checks `tracks`, `clips` and `startClip` against a parsed document (layers already complete). */
165
- export function parseTimeline(d, fail) {
267
+ export function parseTimeline(d, fail, checkCurve) {
268
+ parseParams(d, fail, checkCurve);
166
269
  const used = d.tracks !== undefined || d.clips !== undefined || d.startClip !== undefined;
167
270
  if (!used)
168
271
  return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.42.0",
3
+ "version": "1.43.0",
4
4
  "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",