@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 +13 -1
- package/dist/vfx/VfxInstance.d.ts +16 -0
- package/dist/vfx/VfxInstance.js +62 -1
- package/dist/vfx/document.d.ts +12 -4
- package/dist/vfx/document.js +10 -4
- package/dist/vfx/timeline.d.ts +40 -3
- package/dist/vfx/timeline.js +107 -4
- package/package.json +1 -1
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
|
-
**
|
|
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. */
|
package/dist/vfx/VfxInstance.js
CHANGED
|
@@ -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 (
|
|
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);
|
package/dist/vfx/document.d.ts
CHANGED
|
@@ -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:
|
|
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. */
|
package/dist/vfx/document.js
CHANGED
|
@@ -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-
|
|
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:
|
|
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))
|
package/dist/vfx/timeline.d.ts
CHANGED
|
@@ -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[];
|
package/dist/vfx/timeline.js
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
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",
|