@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
package/dist/vfx/document.js
CHANGED
|
@@ -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-
|
|
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:
|
|
547
|
-
*
|
|
548
|
-
*
|
|
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)
|
package/dist/vfx/index.d.ts
CHANGED
|
@@ -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
package/dist/vfx/material.d.ts
CHANGED
|
@@ -206,7 +206,18 @@ export interface CompiledMaterial {
|
|
|
206
206
|
displace: boolean;
|
|
207
207
|
dispose(): void;
|
|
208
208
|
}
|
|
209
|
-
|
|
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.
|
package/dist/vfx/material.js
CHANGED
|
@@ -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
|
-
|
|
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 {};
|