@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.
- package/README.md +38 -2
- package/dist/vfx/VfxInstance.d.ts +56 -2
- package/dist/vfx/VfxInstance.js +290 -29
- package/dist/vfx/document.d.ts +28 -5
- package/dist/vfx/document.js +20 -5
- package/dist/vfx/index.d.ts +1 -0
- package/dist/vfx/index.js +1 -0
- package/dist/vfx/material.d.ts +12 -1
- package/dist/vfx/material.js +43 -3
- package/dist/vfx/timeline.d.ts +119 -0
- package/dist/vfx/timeline.js +394 -0
- package/package.json +1 -1
|
@@ -0,0 +1,394 @@
|
|
|
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 { EMITTER_NUMBERS, EMITTER_RANGES, EMITTER_VECTORS, FLIPBOOK_RANGES } from './document.js';
|
|
12
|
+
export const TIMELINE_LIMITS = { clips: 8, tracks: 64, keys: 16, params: 8, bindings: 16 };
|
|
13
|
+
const MATERIAL_FIELDS = {
|
|
14
|
+
dissolve: [-1, 2], threshold: [-1, 2], opacity: [0, 1], emission: [0, 32], softness: [0, 1], power: [.1, 8], cutoff: [0, 1],
|
|
15
|
+
'edge.width': [0, 1], 'edge.emission': [0, 16], 'edge.color': 'color', 'rim.strength': [0, 1], 'rim.power': [.25, 8],
|
|
16
|
+
'displace.amount': [-5, 5], 'displace.offset': [0, 1],
|
|
17
|
+
'masks.*.scale': [-100, 100], 'masks.*.scroll': [-100, 100], 'masks.*.spin': [-3600, 3600], 'masks.*.rotation': [-360, 360],
|
|
18
|
+
'masks.*.offset': [-2, 2], 'masks.*.strength': [0, 1], 'masks.*.levels': [-2, 3],
|
|
19
|
+
};
|
|
20
|
+
const withMaterial = (prefix) => Object.fromEntries(Object.entries(MATERIAL_FIELDS).map(([k, v]) => [`${prefix}.${k}`, v]));
|
|
21
|
+
// Built on first use: document.ts imports this file, so its constants are not ready at load time.
|
|
22
|
+
let fieldTable;
|
|
23
|
+
const fields = () => fieldTable ?? (fieldTable = {
|
|
24
|
+
emitters: {
|
|
25
|
+
enabled: 'bool', ...EMITTER_RANGES, ...EMITTER_NUMBERS, ...EMITTER_VECTORS, stop: [0, 60],
|
|
26
|
+
'shape.radius': [0, 100], 'shape.inner': [0, 100], 'shape.height': [0, 100], 'shape.extents': [0, 100], 'shape.axis': [-1, 1],
|
|
27
|
+
'look.softness': [0, 1], 'look.points': [3, 12], 'look.sharpness': [0, 1], 'trail.width': [0, 50],
|
|
28
|
+
...withMaterial('look.material'), ...withMaterial('trail.material'),
|
|
29
|
+
},
|
|
30
|
+
meshes: {
|
|
31
|
+
enabled: 'bool', position: [-100, 100], rotation: [-360, 360], scale: [-100, 100], start: [0, 60], life: [.01, 60], color: 'color', intensity: [0, 16],
|
|
32
|
+
...withMaterial('material'),
|
|
33
|
+
},
|
|
34
|
+
lights: { enabled: 'bool', position: [-100, 100], color: 'color', intensity: [0, 1000], range: [.1, 100], start: [0, 60], life: [.01, 60], flicker: [0, 1] },
|
|
35
|
+
flipbooks: {
|
|
36
|
+
enabled: 'bool', color: 'color',
|
|
37
|
+
...Object.fromEntries(FLIPBOOK_RANGES.filter(([k]) => k !== 'cols' && k !== 'rows' && k !== 'frames').map(([k, a, b]) => [k, [a, b]])),
|
|
38
|
+
},
|
|
39
|
+
});
|
|
40
|
+
const LAYER_KINDS = ['emitters', 'meshes', 'lights', 'flipbooks'];
|
|
41
|
+
const HEX = /^#[0-9a-f]{6}$/i;
|
|
42
|
+
/** Why a path names something no track may drive -- said by name, so the agent can fix it. */
|
|
43
|
+
function refusal(kind, path, value) {
|
|
44
|
+
const p = path.join('.');
|
|
45
|
+
if (kind === 'meshes' && path[0] === 'shape')
|
|
46
|
+
return `the shape of a mesh cannot be animated (it would rebuild the geometry): animate "scale" instead`;
|
|
47
|
+
if (kind === 'emitters' && path[0] === 'mesh')
|
|
48
|
+
return `a particle's mesh shape cannot be animated: animate "size" instead`;
|
|
49
|
+
if (kind === 'emitters' && path[0] === 'trail' && path[1] === 'length')
|
|
50
|
+
return `a trail's length cannot be animated (it sets how many points each trail keeps)`;
|
|
51
|
+
if (kind === 'flipbooks' && ['cols', 'rows', 'frames'].includes(path[0]))
|
|
52
|
+
return `a flipbook's grid (${path[0]}) cannot be animated`;
|
|
53
|
+
const m = path.indexOf('material');
|
|
54
|
+
if (m >= 0 && path[m + 1] === 'masks' && path[m + 3] !== undefined && !['scale', 'scroll', 'spin', 'rotation', 'offset', 'strength', 'levels'].includes(path[m + 3]))
|
|
55
|
+
return `a mask's ${path[m + 3]} is the material's structure (it would recompile the shader): animate its scale, scroll, spin, rotation, offset, strength or levels`;
|
|
56
|
+
if (m >= 0 && ['color', 'ramp', 'alphaMode'].includes(path[m + 1]))
|
|
57
|
+
return `the material's ${path[m + 1]} is its structure and cannot be animated`;
|
|
58
|
+
if (value === null)
|
|
59
|
+
return `${p} is null here; give it a number first to animate it`;
|
|
60
|
+
if (value && typeof value === 'object' && !Array.isArray(value)) {
|
|
61
|
+
if ('overLife' in value)
|
|
62
|
+
return `${p} is a curve over each particle's life; a track cannot drive it as well (make it a number first)`;
|
|
63
|
+
if ('points' in value || 'stops' in value)
|
|
64
|
+
return `${p} is a curve or gradient, which cannot be animated -- animate a number instead`;
|
|
65
|
+
return `${p} is a group; name one of its numbers`;
|
|
66
|
+
}
|
|
67
|
+
return `${p} cannot be animated`;
|
|
68
|
+
}
|
|
69
|
+
/** Resolves `target` against a COMPLETE (parsed) document, or says why not. */
|
|
70
|
+
export function resolveTarget(d, target) {
|
|
71
|
+
if (typeof target !== 'string' || !target)
|
|
72
|
+
return 'target must be a path like "emitters.sparks.rate"';
|
|
73
|
+
const [kind, id, ...rest] = target.split('.');
|
|
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
|
+
}
|
|
82
|
+
if (!LAYER_KINDS.includes(kind))
|
|
83
|
+
return `"${kind}" is not a layer kind (expected emitters, meshes, lights or flipbooks)`;
|
|
84
|
+
const k = kind;
|
|
85
|
+
const layers = (d[k] ?? []);
|
|
86
|
+
const index = layers.findIndex((l) => l.id === id);
|
|
87
|
+
if (index < 0)
|
|
88
|
+
return `there is no ${k.slice(0, -1)} "${id}" in this effect`;
|
|
89
|
+
if (!rest.length)
|
|
90
|
+
return `name a field of ${k}.${id}, e.g. ${k}.${id}.${k === 'emitters' ? 'rate' : 'enabled'}`;
|
|
91
|
+
let at = layers[index];
|
|
92
|
+
const path = [];
|
|
93
|
+
for (const seg of rest) {
|
|
94
|
+
if (Array.isArray(at) && /^\d+$/.test(seg)) {
|
|
95
|
+
if (+seg >= at.length)
|
|
96
|
+
return `${target}: there is no item ${seg}`;
|
|
97
|
+
path.push(+seg);
|
|
98
|
+
at = at[+seg];
|
|
99
|
+
continue;
|
|
100
|
+
}
|
|
101
|
+
if (!at || typeof at !== 'object' || Array.isArray(at) || !Object.prototype.hasOwnProperty.call(at, seg))
|
|
102
|
+
return `${target}: "${seg}" is not a field there`;
|
|
103
|
+
path.push(seg);
|
|
104
|
+
at = at[seg];
|
|
105
|
+
}
|
|
106
|
+
const pattern = path.map((s) => typeof s === 'number' ? '*' : s).join('.');
|
|
107
|
+
const bound = fields()[k][pattern];
|
|
108
|
+
if (!bound || at === null || (typeof at === 'object' && !Array.isArray(at)))
|
|
109
|
+
return `${target}: ${refusal(k, rest, at)}`;
|
|
110
|
+
const range = k === 'emitters' && path.length === 1 && path[0] in EMITTER_RANGES;
|
|
111
|
+
let value;
|
|
112
|
+
if (bound === 'bool')
|
|
113
|
+
value = 'bool';
|
|
114
|
+
else if (bound === 'color')
|
|
115
|
+
value = 'color';
|
|
116
|
+
else if (range || typeof at === 'number')
|
|
117
|
+
value = 'number';
|
|
118
|
+
else if (Array.isArray(at) && (at.length === 2 || at.length === 3))
|
|
119
|
+
value = at.length === 2 ? 'vec2' : 'vec3';
|
|
120
|
+
else
|
|
121
|
+
return `${target}: ${refusal(k, rest, at)}`;
|
|
122
|
+
const m = path.indexOf('material');
|
|
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 };
|
|
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
|
+
}
|
|
166
|
+
const num = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
|
|
167
|
+
function checkTracks(d, tracks, at, fail) {
|
|
168
|
+
if (!Array.isArray(tracks) || tracks.length > TIMELINE_LIMITS.tracks)
|
|
169
|
+
fail(`${at} must be a list of 0-${TIMELINE_LIMITS.tracks} tracks`);
|
|
170
|
+
const seen = new Set();
|
|
171
|
+
return tracks.map((raw, i) => {
|
|
172
|
+
const ta = `${at}[${i}]`;
|
|
173
|
+
if (!raw || typeof raw !== 'object' || Array.isArray(raw))
|
|
174
|
+
fail(`${ta} must be { target, keys, interp? }`);
|
|
175
|
+
for (const k of Object.keys(raw))
|
|
176
|
+
if (!['target', 'keys', 'interp'].includes(k))
|
|
177
|
+
fail(`${ta}.${k} is not a track field (expected target, keys, interp)`);
|
|
178
|
+
const t = raw;
|
|
179
|
+
const r = resolveTarget(d, t.target);
|
|
180
|
+
if (typeof r === 'string')
|
|
181
|
+
fail(`${ta}.target ${r}`);
|
|
182
|
+
const res = r;
|
|
183
|
+
if (seen.has(t.target))
|
|
184
|
+
fail(`${ta}.target "${t.target}" is animated twice in this clip`);
|
|
185
|
+
seen.add(t.target);
|
|
186
|
+
if (t.interp !== undefined && !['linear', 'smooth', 'step'].includes(t.interp))
|
|
187
|
+
fail(`${ta}.interp must be "linear", "smooth" or "step"`);
|
|
188
|
+
if (!Array.isArray(t.keys) || t.keys.length < 1 || t.keys.length > TIMELINE_LIMITS.keys)
|
|
189
|
+
fail(`${ta}.keys must be a list of 1-${TIMELINE_LIMITS.keys} keys [time, value, ease?]`);
|
|
190
|
+
const [lo, hi] = res.bounds;
|
|
191
|
+
const shape = res.value === 'bool' ? 'true or false' : res.value === 'color' ? '"#rrggbb"' : res.value === 'number' ? `a number ${lo}-${hi}${res.range ? ' (a plain number while a track drives it, not [min, max])' : ''}` : `[${res.value === 'vec2' ? 'u, v' : 'x, y, z'}], each ${lo}-${hi}`;
|
|
192
|
+
t.keys.forEach((key, j) => {
|
|
193
|
+
const ka = `${ta}.keys[${j}]`;
|
|
194
|
+
if (!Array.isArray(key) || key.length < 2 || key.length > 3)
|
|
195
|
+
fail(`${ka} must be [time, value] or [time, value, ease]`);
|
|
196
|
+
if (!num(key[0], 0, 60))
|
|
197
|
+
fail(`${ka} time must be 0-60 seconds`);
|
|
198
|
+
if (j > 0 && !(key[0] > t.keys[j - 1][0]))
|
|
199
|
+
fail(`${ta}.keys must be in increasing time`);
|
|
200
|
+
const v = key[1];
|
|
201
|
+
const ok = res.value === 'bool' ? typeof v === 'boolean' : res.value === 'color' ? typeof v === 'string' && HEX.test(v)
|
|
202
|
+
: res.value === 'number' ? num(v, lo, hi) : Array.isArray(v) && v.length === (res.value === 'vec2' ? 2 : 3) && v.every((x) => num(x, lo, hi));
|
|
203
|
+
if (!ok)
|
|
204
|
+
fail(`${ka} value must be ${shape} for ${t.target}`);
|
|
205
|
+
if (key.length === 3 && !num(key[2], -100, 100))
|
|
206
|
+
fail(`${ka} ease must be a number -100-100 (Godot's transition: 1 linear, 2 ease in, 0.5 ease out, negative in-out, 0 hold)`);
|
|
207
|
+
});
|
|
208
|
+
return t;
|
|
209
|
+
});
|
|
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
|
+
}
|
|
266
|
+
/** Checks `tracks`, `clips` and `startClip` against a parsed document (layers already complete). */
|
|
267
|
+
export function parseTimeline(d, fail, checkCurve) {
|
|
268
|
+
parseParams(d, fail, checkCurve);
|
|
269
|
+
const used = d.tracks !== undefined || d.clips !== undefined || d.startClip !== undefined;
|
|
270
|
+
if (!used)
|
|
271
|
+
return;
|
|
272
|
+
if (d.version < 7)
|
|
273
|
+
fail('tracks and clips are version 7: set "version": 7 (needs @umicat/three-sdk 1.42 or later)');
|
|
274
|
+
if (d.clips !== undefined && d.tracks !== undefined)
|
|
275
|
+
fail('tracks: with clips, each clip has its own tracks -- move these into a clip');
|
|
276
|
+
if (d.startClip !== undefined && d.clips === undefined)
|
|
277
|
+
fail('startClip names a clip, but there are no clips');
|
|
278
|
+
if (d.tracks !== undefined)
|
|
279
|
+
d.tracks = checkTracks(d, d.tracks, 'tracks', fail);
|
|
280
|
+
if (d.clips === undefined)
|
|
281
|
+
return;
|
|
282
|
+
if (!Array.isArray(d.clips) || d.clips.length < 1 || d.clips.length > TIMELINE_LIMITS.clips)
|
|
283
|
+
fail(`clips must be a list of 1-${TIMELINE_LIMITS.clips}`);
|
|
284
|
+
const names = new Set();
|
|
285
|
+
d.clips.forEach((c, i) => {
|
|
286
|
+
const at = `clips[${i}]`;
|
|
287
|
+
if (!c || typeof c !== 'object' || Array.isArray(c))
|
|
288
|
+
fail(`${at} must be { name, duration, loop, next?, tracks }`);
|
|
289
|
+
for (const k of Object.keys(c))
|
|
290
|
+
if (!['name', 'duration', 'loop', 'next', 'tracks'].includes(k))
|
|
291
|
+
fail(`${at}.${k} is not a clip field (expected name, duration, loop, next, tracks)`);
|
|
292
|
+
if (typeof c.name !== 'string' || !/^[a-z0-9_-]{1,40}$/i.test(c.name))
|
|
293
|
+
fail(`${at}.name must be 1-40 of a-z 0-9 _ -`);
|
|
294
|
+
if (names.has(c.name))
|
|
295
|
+
fail(`${at}.name "${c.name}" is used twice`);
|
|
296
|
+
names.add(c.name);
|
|
297
|
+
});
|
|
298
|
+
d.clips = d.clips.map((c, i) => {
|
|
299
|
+
const at = `clips[${i}]`;
|
|
300
|
+
if (!num(c.duration, .02, 60))
|
|
301
|
+
fail(`${at}.duration must be 0.02-60`);
|
|
302
|
+
if (typeof c.loop !== 'boolean')
|
|
303
|
+
fail(`${at}.loop must be a boolean`);
|
|
304
|
+
if (c.next !== undefined) {
|
|
305
|
+
if (!names.has(c.next))
|
|
306
|
+
fail(`${at}.next "${c.next}" is not a clip in this effect`);
|
|
307
|
+
if (c.next === c.name)
|
|
308
|
+
fail(`${at}.next is the clip itself: set "loop": true instead`);
|
|
309
|
+
if (c.loop)
|
|
310
|
+
fail(`${at} loops, so it never ends and its next ("${c.next}") would never play: drop one`);
|
|
311
|
+
}
|
|
312
|
+
return { ...c, tracks: checkTracks(d, c.tracks ?? [], `${at}.tracks`, fail) };
|
|
313
|
+
});
|
|
314
|
+
if (d.startClip !== undefined && !names.has(d.startClip))
|
|
315
|
+
fail(`startClip "${d.startClip}" is not a clip in this effect`);
|
|
316
|
+
}
|
|
317
|
+
/** The clips an instance plays: the document's own, or one named `main` made of `duration`, `loop` and `tracks`. */
|
|
318
|
+
export function effectClips(d) {
|
|
319
|
+
if (d.clips?.length)
|
|
320
|
+
return { clips: d.clips, start: d.startClip ?? d.clips[0].name };
|
|
321
|
+
return { clips: [{ name: 'main', duration: d.duration, loop: d.loop, tracks: d.tracks ?? [] }], start: 'main' };
|
|
322
|
+
}
|
|
323
|
+
// ------------------------------------------------------------------ sampling
|
|
324
|
+
/** Godot's `ease(x, c)`, exactly (core/math/math_funcs.cpp). */
|
|
325
|
+
export function godotEase(x, c) {
|
|
326
|
+
x = x < 0 ? 0 : x > 1 ? 1 : x;
|
|
327
|
+
if (c > 0)
|
|
328
|
+
return c < 1 ? 1 - Math.pow(1 - x, 1 / c) : Math.pow(x, c);
|
|
329
|
+
if (c < 0)
|
|
330
|
+
return x < .5 ? Math.pow(x * 2, -c) * .5 : (1 - Math.pow(1 - (x - .5) * 2, -c)) * .5 + .5;
|
|
331
|
+
return 0;
|
|
332
|
+
}
|
|
333
|
+
const toLinear = (c) => c <= .04045 ? c / 12.92 : Math.pow((c + .055) / 1.055, 2.4);
|
|
334
|
+
const toSrgb = (c) => c <= .0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - .055;
|
|
335
|
+
const hexToLinear = (h) => [1, 3, 5].map((i) => toLinear(parseInt(h.slice(i, i + 2), 16) / 255));
|
|
336
|
+
export const linearToHex = (rgb) => '#' + rgb.map((c) => Math.round(Math.max(0, Math.min(1, toSrgb(Math.max(0, c)))) * 255).toString(16).padStart(2, '0')).join('');
|
|
337
|
+
export function prepareTrack(t, kind) {
|
|
338
|
+
const values = t.keys.map(([, v]) => kind === 'color' ? hexToLinear(v) : kind === 'bool' ? [v ? 1 : 0] : Array.isArray(v) ? [...v] : [v]);
|
|
339
|
+
return { kind, times: t.keys.map((k) => k[0]), values, eases: t.keys.map((k) => k[2] ?? 1), interp: kind === 'bool' ? 'step' : t.interp ?? 'linear' };
|
|
340
|
+
}
|
|
341
|
+
/**
|
|
342
|
+
* Godot's cubic between keys at non-uniform times (Barry-Goldman, as
|
|
343
|
+
* `cubic_interpolate_in_time`): `pre`/`post` are the neighbouring keys, or
|
|
344
|
+
* mirrored when there is none.
|
|
345
|
+
*/
|
|
346
|
+
function cubicInTime(from, to, pre, post, w, toT, preT, postT) {
|
|
347
|
+
const lerp = (a, b, x) => a + (b - a) * x;
|
|
348
|
+
const t = toT * w;
|
|
349
|
+
const a1 = lerp(pre, from, preT === 0 ? 0 : (t - preT) / -preT);
|
|
350
|
+
const a2 = lerp(from, to, toT === 0 ? .5 : t / toT);
|
|
351
|
+
const a3 = lerp(to, post, postT - toT === 0 ? 1 : (t - toT) / (postT - toT));
|
|
352
|
+
const b1 = lerp(a1, a2, toT - preT === 0 ? 0 : (t - preT) / (toT - preT));
|
|
353
|
+
const b2 = lerp(a2, a3, postT === 0 ? 1 : t / postT);
|
|
354
|
+
return lerp(b1, b2, toT === 0 ? .5 : t / toT);
|
|
355
|
+
}
|
|
356
|
+
/** 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. */
|
|
357
|
+
export function sampleTrack(s, t, out) {
|
|
358
|
+
const { times, values } = s, n = times.length;
|
|
359
|
+
out.length = values[0].length;
|
|
360
|
+
if (t <= times[0] || n === 1) {
|
|
361
|
+
for (let c = 0; c < out.length; c++)
|
|
362
|
+
out[c] = values[0][c];
|
|
363
|
+
return out;
|
|
364
|
+
}
|
|
365
|
+
if (t >= times[n - 1]) {
|
|
366
|
+
for (let c = 0; c < out.length; c++)
|
|
367
|
+
out[c] = values[n - 1][c];
|
|
368
|
+
return out;
|
|
369
|
+
}
|
|
370
|
+
let i = 0;
|
|
371
|
+
while (i < n - 2 && t >= times[i + 1])
|
|
372
|
+
i++;
|
|
373
|
+
const ease = s.eases[i];
|
|
374
|
+
if (s.interp === 'step' || ease === 0) {
|
|
375
|
+
for (let c = 0; c < out.length; c++)
|
|
376
|
+
out[c] = values[i][c];
|
|
377
|
+
return out;
|
|
378
|
+
}
|
|
379
|
+
const span = times[i + 1] - times[i];
|
|
380
|
+
let w = (t - times[i]) / span;
|
|
381
|
+
if (ease !== 1)
|
|
382
|
+
w = godotEase(w, ease);
|
|
383
|
+
for (let c = 0; c < out.length; c++) {
|
|
384
|
+
const a = values[i][c], b = values[i + 1][c];
|
|
385
|
+
if (s.interp === 'linear') {
|
|
386
|
+
out[c] = a + (b - a) * w;
|
|
387
|
+
continue;
|
|
388
|
+
}
|
|
389
|
+
const pre = i > 0 ? values[i - 1][c] : a, post = i + 2 < n ? values[i + 2][c] : b;
|
|
390
|
+
const preT = i > 0 ? times[i - 1] - times[i] : -span, postT = i + 2 < n ? times[i + 2] - times[i] : 2 * span;
|
|
391
|
+
out[c] = cubicInTime(a, b, pre, post, w, span, preT, postT);
|
|
392
|
+
}
|
|
393
|
+
return out;
|
|
394
|
+
}
|
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",
|