@umicat/three-sdk 1.35.0 → 1.37.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 +32 -9
- package/dist/vfx/VfxInstance.d.ts +28 -8
- package/dist/vfx/VfxInstance.js +505 -60
- package/dist/vfx/document.d.ts +263 -19
- package/dist/vfx/document.js +375 -24
- package/dist/vfx/index.d.ts +1 -0
- package/dist/vfx/index.js +1 -0
- package/dist/vfx/material.d.ts +191 -0
- package/dist/vfx/material.js +500 -0
- package/dist/vfx/templates.js +9 -7
- package/package.json +1 -1
package/dist/vfx/document.js
CHANGED
|
@@ -1,46 +1,188 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* The `.vfx.json` effect document: what the VFX Editor writes, what the agent
|
|
3
|
+
* writes, and what a game plays. Two kinds of layer:
|
|
4
|
+
*
|
|
5
|
+
* - `emitters`: particle systems modelled on Godot's ParticleProcessMaterial
|
|
6
|
+
* -- an emission shape, a direction cone, velocities and accelerations,
|
|
7
|
+
* random ranges, curves and gradients over each particle's life, a look
|
|
8
|
+
* (a procedural dot / glow / star, an image, or a sprite sheet), and
|
|
9
|
+
* sub-emitters. Design: umicat-design ADR-054.
|
|
10
|
+
* - `flipbooks`: a sprite sheet played frame by frame on one quad -- an
|
|
11
|
+
* explosion, a muzzle flash, a slash. The sheet is an IMAGE ASSET next to the
|
|
12
|
+
* effect, named by `texture`; the grid is `cols` x `rows`, read left to
|
|
13
|
+
* right, top to bottom, and the first `frames` cells are played.
|
|
14
|
+
*
|
|
15
|
+
* Version 2. A version-1 document (the upward-firing disc emitter of 1.35) is
|
|
16
|
+
* still accepted: `parseVfx` upgrades it to the v2 emitter that plays the same.
|
|
17
|
+
*
|
|
18
|
+
* Version 3 (1.37) adds the effect MATERIAL (`look: { type: 'material' }`,
|
|
19
|
+
* ADR-055). A document that uses none of it is still written as version 2 --
|
|
20
|
+
* `minimumVersion()` -- so games whose lockfile holds 1.36 keep playing it.
|
|
21
|
+
*/
|
|
22
|
+
import { parseMaterial, materialTextures } from './material.js';
|
|
23
|
+
export const LIMITS = { emitters: 8, layers: 8, particles: 4000, cells: 4096, bursts: 16, children: 4, curvePoints: 8, gradientStops: 16 };
|
|
24
|
+
/** Every emitter field's value when a document leaves it out. */
|
|
25
|
+
export function emitterDefaults() {
|
|
26
|
+
return {
|
|
27
|
+
enabled: true, rate: 20, bursts: [], start: 0, stop: null, lifetime: 1.5, space: 'local',
|
|
28
|
+
shape: { type: 'point' }, shapeOffset: [0, 0, 0], shapeScale: [1, 1, 1], rotation: [0, 0, 0],
|
|
29
|
+
direction: [0, 1, 0], spread: 15, flatness: 0, speed: 1, randomVelocity: [0, 0, 0], gravity: [0, 0, 0],
|
|
30
|
+
radialSpeed: 0, radialAccel: 0, tangentialAccel: 0, orbit: 0, damping: 0,
|
|
31
|
+
angle: 0, spin: 0, size: .2,
|
|
32
|
+
color: { stops: [[0, '#ffffff', 1]] }, intensity: 1,
|
|
33
|
+
look: { type: 'dot', softness: .5 }, align: 'camera', stretch: 0, blend: 'normal', children: [],
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
/** A new particle layer: the defaults, plus a fade-out so it reads as particles at once. */
|
|
37
|
+
export function emitterLayer(id, patch = {}) {
|
|
38
|
+
return { id, ...emitterDefaults(), alphaOverLife: { points: [[0, 0], [.1, 1], [1, 0]] }, ...patch };
|
|
39
|
+
}
|
|
2
40
|
export function campfire() {
|
|
3
|
-
return { version: 1, name: 'Campfire', seed: 17, duration: 4, loop: true, humanCurated: false, emitters: [
|
|
41
|
+
return upgradeV1({ version: 1, name: 'Campfire', seed: 17, duration: 4, loop: true, humanCurated: false, emitters: [
|
|
4
42
|
{ id: 'flame', enabled: true, rate: 55, lifetime: 1.1, speed: 1.3, spread: .25, gravity: .3, size: .28, endSize: .02, opacity: .8, color: '#ff9b32', endColor: '#e93616', blend: 'additive' },
|
|
5
43
|
{ id: 'embers', enabled: true, rate: 10, lifetime: 2, speed: 1.8, spread: .45, gravity: -.25, size: .035, endSize: .005, opacity: 1, color: '#ffce72', endColor: '#fa5214', blend: 'additive' },
|
|
6
44
|
{ id: 'smoke', enabled: true, rate: 12, lifetime: 3.5, speed: .55, spread: .2, gravity: .1, size: .18, endSize: .8, opacity: .12, color: '#777b85', endColor: '#333943', blend: 'normal' }
|
|
7
|
-
] };
|
|
45
|
+
] });
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* A version-1 document as the v2 document that plays the same: same spawn
|
|
49
|
+
* disc, speeds, jitter, gravity, colour, size and alpha over life. (Not
|
|
50
|
+
* bit-identical -- random numbers are drawn in a different order -- but the
|
|
51
|
+
* same effect.) v1 `size` was a point RADIUS; v2 `size` is the width.
|
|
52
|
+
*/
|
|
53
|
+
export function upgradeV1(v1) {
|
|
54
|
+
const emitters = v1.emitters.map((e) => ({
|
|
55
|
+
...emitterDefaults(), id: e.id, enabled: e.enabled, rate: e.rate, lifetime: e.lifetime,
|
|
56
|
+
shape: { type: 'ring', radius: .15, inner: 0, height: 0, axis: [0, 1, 0] },
|
|
57
|
+
direction: [0, 1, 0], spread: 0, speed: [e.speed * .8, e.speed * 1.2],
|
|
58
|
+
randomVelocity: [e.spread / 2, 0, e.spread / 2], gravity: [0, e.gravity, 0],
|
|
59
|
+
size: e.size * 2, sizeOverLife: { points: [[0, 1], [1, e.size > 0 ? e.endSize / e.size : 1]] },
|
|
60
|
+
color: { stops: [[0, '#ffffff', 1]] }, colorOverLife: { stops: [[0, e.color, 1], [1, e.endColor, 1]] },
|
|
61
|
+
alphaOverLife: { points: [[0, 0], [.125, .875 * e.opacity], [1, 0]] },
|
|
62
|
+
look: { type: 'dot', softness: .5 }, blend: e.blend,
|
|
63
|
+
}));
|
|
64
|
+
const doc = { version: 2, name: v1.name, seed: v1.seed, duration: v1.duration, loop: v1.loop, humanCurated: v1.humanCurated, emitters };
|
|
65
|
+
if (v1.flipbooks !== undefined)
|
|
66
|
+
doc.flipbooks = v1.flipbooks;
|
|
67
|
+
return doc;
|
|
8
68
|
}
|
|
9
|
-
/** Per-emitter numeric fields and their allowed ranges (shared with the editor's inputs). */
|
|
10
|
-
export const EMITTER_RANGES = [['rate', 0, 300], ['lifetime', .1, 10], ['speed', 0, 10], ['spread', 0, 5], ['gravity', -10, 10], ['size', .001, 5], ['endSize', .001, 5], ['opacity', 0, 1]];
|
|
11
69
|
/** Per-flipbook numeric fields and their allowed ranges. `frames` is further capped at cols x rows. */
|
|
12
70
|
export const FLIPBOOK_RANGES = [['cols', 1, 64], ['rows', 1, 64], ['frames', 1, 4096], ['fps', 1, 120], ['delay', 0, 60], ['size', .01, 50], ['originU', 0, 1], ['originV', 0, 1], ['opacity', 0, 1]];
|
|
13
71
|
const INTEGER_FIELDS = new Set(['cols', 'rows', 'frames']);
|
|
14
72
|
/** A bare filename with an image extension: no folders, so it can only name a sibling of the effect. */
|
|
15
73
|
export const TEXTURE_PATTERN = /^[^/\\?#]{1,200}\.(png|webp|jpe?g)$/i;
|
|
74
|
+
/** Numeric emitter fields that take a `Range`, with their allowed bounds. Shared with the editor's inputs. */
|
|
75
|
+
export const EMITTER_RANGES = {
|
|
76
|
+
lifetime: [.01, 30], speed: [-1000, 1000], radialSpeed: [-100, 100], radialAccel: [-1000, 1000],
|
|
77
|
+
tangentialAccel: [-1000, 1000], orbit: [-100, 100], damping: [0, 1000], angle: [-3600, 3600],
|
|
78
|
+
spin: [-36000, 36000], size: [0, 100],
|
|
79
|
+
};
|
|
80
|
+
/** Plain numeric emitter fields and their bounds. */
|
|
81
|
+
export const EMITTER_NUMBERS = {
|
|
82
|
+
rate: [0, 1000], start: [0, 60], spread: [0, 180], flatness: [0, 1], intensity: [0, 16], stretch: [0, 10],
|
|
83
|
+
};
|
|
84
|
+
/** Vector emitter fields and the bound on each component. */
|
|
85
|
+
export const EMITTER_VECTORS = {
|
|
86
|
+
shapeOffset: [-100, 100], shapeScale: [-100, 100], rotation: [-360, 360], direction: [-1000, 1000], randomVelocity: [0, 100], gravity: [-100, 100],
|
|
87
|
+
};
|
|
88
|
+
export const CURVE_FIELDS = ['speedLimit', 'radialAccelOverLife', 'orbitOverLife', 'sizeOverLife', 'alphaOverLife'];
|
|
16
89
|
/** A new flipbook layer with sensible defaults, for the editor's "Add" and for the agent. */
|
|
17
90
|
export function flipbookLayer(id, texture) {
|
|
18
91
|
return { id, enabled: true, texture, cols: 4, rows: 4, frames: 16, fps: 24, loop: true, delay: 0, size: 1.5, originU: .5, originV: .5, facing: 'camera', opacity: 1, color: '#ffffff', blend: 'additive' };
|
|
19
92
|
}
|
|
20
|
-
/** Every texture filename a document needs, once each. */
|
|
93
|
+
/** Every texture filename a document needs (flipbook sheets and particle images), once each. */
|
|
21
94
|
export function vfxTextures(document) {
|
|
22
|
-
|
|
95
|
+
const names = (document.flipbooks ?? []).map((f) => f.texture);
|
|
96
|
+
for (const e of document.emitters) {
|
|
97
|
+
if (e.look.type === 'texture' || e.look.type === 'sheet')
|
|
98
|
+
names.push(e.look.texture);
|
|
99
|
+
else if (e.look.type === 'material')
|
|
100
|
+
names.push(...materialTextures(e.look.material));
|
|
101
|
+
}
|
|
102
|
+
return [...new Set(names)];
|
|
103
|
+
}
|
|
104
|
+
// ---------------------------------------------------------------- sampling
|
|
105
|
+
/** The value of a Range for one random number u in [0, 1). */
|
|
106
|
+
export function pickRange(r, u) { return typeof r === 'number' ? r : r[0] + (r[1] - r[0]) * u; }
|
|
107
|
+
export function rangeMax(r) { return typeof r === 'number' ? r : Math.max(r[0], r[1]); }
|
|
108
|
+
/** Curve value at t (0..1). Monotone cubic (Fritsch-Carlson) when `smooth`, so it never overshoots its points. */
|
|
109
|
+
export function sampleCurve(c, t) {
|
|
110
|
+
const p = c.points, n = p.length;
|
|
111
|
+
if (t <= p[0][0])
|
|
112
|
+
return p[0][1];
|
|
113
|
+
if (t >= p[n - 1][0])
|
|
114
|
+
return p[n - 1][1];
|
|
115
|
+
let i = 0;
|
|
116
|
+
while (i < n - 2 && t > p[i + 1][0])
|
|
117
|
+
i++;
|
|
118
|
+
const [x0, y0] = p[i], [x1, y1] = p[i + 1], h = x1 - x0;
|
|
119
|
+
if (h <= 0)
|
|
120
|
+
return y1;
|
|
121
|
+
const s = (t - x0) / h;
|
|
122
|
+
if (!c.smooth)
|
|
123
|
+
return y0 + (y1 - y0) * s;
|
|
124
|
+
const slope = (a) => (p[a + 1][1] - p[a][1]) / Math.max(1e-9, p[a + 1][0] - p[a][0]);
|
|
125
|
+
const tangent = (k) => {
|
|
126
|
+
if (k === 0)
|
|
127
|
+
return slope(0);
|
|
128
|
+
if (k === n - 1)
|
|
129
|
+
return slope(n - 2);
|
|
130
|
+
const a = slope(k - 1), b = slope(k);
|
|
131
|
+
return a * b <= 0 ? 0 : 3 * (p[k + 1][0] - p[k - 1][0]) / ((2 * p[k + 1][0] - p[k][0] - p[k - 1][0]) / a + (p[k + 1][0] + p[k][0] - 2 * p[k - 1][0]) / b);
|
|
132
|
+
};
|
|
133
|
+
const m0 = tangent(i) * h, m1 = tangent(i + 1) * h, s2 = s * s, s3 = s2 * s;
|
|
134
|
+
return (2 * s3 - 3 * s2 + 1) * y0 + (s3 - 2 * s2 + s) * m0 + (-2 * s3 + 3 * s2) * y1 + (s3 - s2) * m1;
|
|
135
|
+
}
|
|
136
|
+
const hex = (h, k) => parseInt(h.slice(1 + k * 2, 3 + k * 2), 16) / 255;
|
|
137
|
+
/** Gradient at t, written into out as [r, g, b, a] (sRGB components 0..1). */
|
|
138
|
+
export function sampleGradient(g, t, out = [0, 0, 0, 0]) {
|
|
139
|
+
const s = g.stops, n = s.length;
|
|
140
|
+
let a = s[0], b = s[0], f = 0;
|
|
141
|
+
if (t >= s[n - 1][0]) {
|
|
142
|
+
a = b = s[n - 1];
|
|
143
|
+
}
|
|
144
|
+
else if (t > s[0][0]) {
|
|
145
|
+
let i = 0;
|
|
146
|
+
while (i < n - 2 && t > s[i + 1][0])
|
|
147
|
+
i++;
|
|
148
|
+
a = s[i];
|
|
149
|
+
b = s[i + 1];
|
|
150
|
+
f = b[0] > a[0] ? (t - a[0]) / (b[0] - a[0]) : 1;
|
|
151
|
+
}
|
|
152
|
+
for (let k = 0; k < 3; k++)
|
|
153
|
+
out[k] = hex(a[1], k) + (hex(b[1], k) - hex(a[1], k)) * f;
|
|
154
|
+
out[3] = a[2] + (b[2] - a[2]) * f;
|
|
155
|
+
return out;
|
|
23
156
|
}
|
|
157
|
+
// ---------------------------------------------------------------- validation
|
|
24
158
|
/**
|
|
25
159
|
* Reject malformed/unsupported resources instead of silently rewriting them.
|
|
26
160
|
* The message names the field and its allowed range: the agent writes these
|
|
27
161
|
* documents by hand, and "Invalid VFX resource" gave it nothing to fix.
|
|
162
|
+
*
|
|
163
|
+
* Returns a COMPLETE copy: a version-1 document is upgraded, and emitter
|
|
164
|
+
* fields left out take `emitterDefaults()`.
|
|
28
165
|
*/
|
|
29
166
|
export function parseVfx(value) {
|
|
30
167
|
const fail = (why) => { throw new Error(`Invalid VFX resource: ${why}`); };
|
|
31
168
|
if (!value || typeof value !== 'object')
|
|
32
169
|
return fail('not an object');
|
|
33
|
-
const
|
|
170
|
+
const raw = value;
|
|
171
|
+
if (raw.version === 1) {
|
|
172
|
+
checkV1(value, fail);
|
|
173
|
+
return parseVfx(upgradeV1(structuredClone(value)));
|
|
174
|
+
}
|
|
175
|
+
const d = structuredClone(value);
|
|
34
176
|
const number = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
|
|
35
177
|
const color = (v) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v);
|
|
36
|
-
if (d.version !==
|
|
37
|
-
fail(
|
|
178
|
+
if (d.version !== 2 && d.version !== 3)
|
|
179
|
+
fail(`version must be 2 or 3 (or 1, which is upgraded)${typeof d.version === 'number' && d.version > 3 ? ` -- version ${d.version} was written by a newer editor: update @umicat/three-sdk` : ''}`);
|
|
38
180
|
if (typeof d.name !== 'string' || !d.name.trim() || d.name.length > 80)
|
|
39
181
|
fail('name must be 1-80 characters');
|
|
40
182
|
if (!number(d.seed, 1, 2147483646) || !Number.isInteger(d.seed))
|
|
41
183
|
fail('seed must be an integer 1-2147483646');
|
|
42
|
-
if (!number(d.duration, .
|
|
43
|
-
fail('duration must be 0.
|
|
184
|
+
if (!number(d.duration, .02, 60))
|
|
185
|
+
fail('duration must be 0.02-60');
|
|
44
186
|
if (typeof d.loop !== 'boolean')
|
|
45
187
|
fail('loop must be a boolean');
|
|
46
188
|
if (typeof d.humanCurated !== 'boolean')
|
|
@@ -61,27 +203,185 @@ export function parseVfx(value) {
|
|
|
61
203
|
fail(`${at}.id "${id}" is used twice`);
|
|
62
204
|
ids.add(id);
|
|
63
205
|
};
|
|
64
|
-
|
|
65
|
-
|
|
206
|
+
const checkRange = (v, at, min, max) => {
|
|
207
|
+
if (number(v, min, max))
|
|
208
|
+
return;
|
|
209
|
+
if (Array.isArray(v) && v.length === 2 && number(v[0], min, max) && number(v[1], min, max) && v[0] <= v[1])
|
|
210
|
+
return;
|
|
211
|
+
fail(`${at} must be a number ${min}-${max}, or [min, max] within that`);
|
|
212
|
+
};
|
|
213
|
+
const checkVec = (v, at, min, max) => {
|
|
214
|
+
if (!Array.isArray(v) || v.length !== 3 || !v.every((x) => number(x, min, max)))
|
|
215
|
+
fail(`${at} must be [x, y, z], each ${min}-${max}`);
|
|
216
|
+
};
|
|
217
|
+
const checkCurve = (v, at) => {
|
|
218
|
+
const c = v;
|
|
219
|
+
if (!c || typeof c !== 'object' || !Array.isArray(c.points) || c.points.length < 1 || c.points.length > LIMITS.curvePoints)
|
|
220
|
+
fail(`${at} must be { points: [[t, value], ...] } with 1-${LIMITS.curvePoints} points`);
|
|
221
|
+
c.points.forEach((p, i) => {
|
|
222
|
+
if (!Array.isArray(p) || p.length !== 2 || !number(p[0], 0, 1) || !number(p[1], -1000, 1000))
|
|
223
|
+
fail(`${at}.points[${i}] must be [t 0-1, value -1000-1000]`);
|
|
224
|
+
if (i > 0 && p[0] < c.points[i - 1][0])
|
|
225
|
+
fail(`${at}.points must be in increasing t`);
|
|
226
|
+
});
|
|
227
|
+
if (c.smooth !== undefined && typeof c.smooth !== 'boolean')
|
|
228
|
+
fail(`${at}.smooth must be a boolean`);
|
|
229
|
+
};
|
|
230
|
+
const checkGradient = (v, at) => {
|
|
231
|
+
const g = v;
|
|
232
|
+
if (!g || typeof g !== 'object' || !Array.isArray(g.stops) || g.stops.length < 1 || g.stops.length > LIMITS.gradientStops)
|
|
233
|
+
fail(`${at} must be { stops: [[t, "#rrggbb", alpha], ...] } with 1-${LIMITS.gradientStops} stops`);
|
|
234
|
+
g.stops.forEach((s, i) => {
|
|
235
|
+
if (!Array.isArray(s) || s.length !== 3 || !number(s[0], 0, 1) || !color(s[1]) || !number(s[2], 0, 1))
|
|
236
|
+
fail(`${at}.stops[${i}] must be [t 0-1, "#rrggbb", alpha 0-1]`);
|
|
237
|
+
if (i > 0 && s[0] < g.stops[i - 1][0])
|
|
238
|
+
fail(`${at}.stops must be in increasing t`);
|
|
239
|
+
});
|
|
240
|
+
};
|
|
241
|
+
const emitterIds = new Set();
|
|
242
|
+
d.emitters = d.emitters.map((input, i) => {
|
|
66
243
|
const at = `emitters[${i}]`;
|
|
67
|
-
if (!
|
|
244
|
+
if (!input || typeof input !== 'object' || Array.isArray(input))
|
|
68
245
|
fail(`${at} is not an object`);
|
|
69
|
-
checkId(
|
|
246
|
+
checkId(input.id, at);
|
|
247
|
+
emitterIds.add(input.id);
|
|
248
|
+
const known = new Set(['id', ...Object.keys(emitterDefaults()), ...CURVE_FIELDS, 'colorOverLife']);
|
|
249
|
+
for (const key of Object.keys(input))
|
|
250
|
+
if (!known.has(key))
|
|
251
|
+
fail(`${at}.${key} is not an emitter field (a version-1 field? set "version": 1, or see emitterDefaults())`);
|
|
252
|
+
const e = { ...emitterDefaults(), ...input };
|
|
70
253
|
if (typeof e.enabled !== 'boolean')
|
|
71
254
|
fail(`${at}.enabled must be a boolean`);
|
|
72
|
-
for (const [key, min, max] of
|
|
255
|
+
for (const [key, [min, max]] of Object.entries(EMITTER_NUMBERS))
|
|
73
256
|
if (!number(e[key], min, max))
|
|
74
257
|
fail(`${at}.${key} must be ${min}-${max}`);
|
|
75
|
-
for (const key
|
|
76
|
-
|
|
77
|
-
|
|
258
|
+
for (const [key, [min, max]] of Object.entries(EMITTER_RANGES))
|
|
259
|
+
checkRange(e[key], `${at}.${key}`, min, max);
|
|
260
|
+
for (const [key, [min, max]] of Object.entries(EMITTER_VECTORS))
|
|
261
|
+
checkVec(e[key], `${at}.${key}`, min, max);
|
|
262
|
+
if (typeof e.lifetime === 'number' ? e.lifetime < .01 : e.lifetime[0] < .01)
|
|
263
|
+
fail(`${at}.lifetime must be at least 0.01`);
|
|
264
|
+
if (e.stop !== null && !(number(e.stop, 0, 60) && e.stop > e.start))
|
|
265
|
+
fail(`${at}.stop must be null or a time after start (${e.start}), up to 60`);
|
|
266
|
+
if (!Array.isArray(e.bursts) || e.bursts.length > LIMITS.bursts)
|
|
267
|
+
fail(`${at}.bursts must be a list of 0-${LIMITS.bursts}`);
|
|
268
|
+
e.bursts.forEach((b, k) => {
|
|
269
|
+
if (!b || !number(b.time, 0, 60) || !number(b.count, 1, 1000) || !Number.isInteger(b.count) || !number(b.over, 0, 60))
|
|
270
|
+
fail(`${at}.bursts[${k}] must be { time 0-60, count 1-1000 whole, over 0-60 }`);
|
|
271
|
+
});
|
|
272
|
+
if (!['local', 'world'].includes(e.space))
|
|
273
|
+
fail(`${at}.space must be "local" or "world"`);
|
|
274
|
+
const s = e.shape;
|
|
275
|
+
const sat = `${at}.shape`;
|
|
276
|
+
if (!s || typeof s !== 'object')
|
|
277
|
+
fail(`${sat} must be an object with a type`);
|
|
278
|
+
else if (s.type === 'point') { /* nothing */ }
|
|
279
|
+
else if (s.type === 'sphere') {
|
|
280
|
+
if (!number(s.radius, 0, 100))
|
|
281
|
+
fail(`${sat}.radius must be 0-100`);
|
|
282
|
+
if (typeof s.surface !== 'boolean')
|
|
283
|
+
fail(`${sat}.surface must be a boolean`);
|
|
284
|
+
}
|
|
285
|
+
else if (s.type === 'box')
|
|
286
|
+
checkVec(s.extents, `${sat}.extents`, 0, 100);
|
|
287
|
+
else if (s.type === 'ring') {
|
|
288
|
+
if (!number(s.radius, 0, 100))
|
|
289
|
+
fail(`${sat}.radius must be 0-100`);
|
|
290
|
+
if (!number(s.inner, 0, s.radius))
|
|
291
|
+
fail(`${sat}.inner must be 0-radius (${s.radius})`);
|
|
292
|
+
if (!number(s.height, 0, 100))
|
|
293
|
+
fail(`${sat}.height must be 0-100`);
|
|
294
|
+
checkVec(s.axis, `${sat}.axis`, -1, 1);
|
|
295
|
+
if (Math.hypot(...s.axis) < 1e-6)
|
|
296
|
+
fail(`${sat}.axis must not be [0, 0, 0]`);
|
|
297
|
+
}
|
|
298
|
+
else
|
|
299
|
+
fail(`${sat}.type must be point, sphere, box or ring`);
|
|
300
|
+
for (const key of CURVE_FIELDS)
|
|
301
|
+
if (e[key] !== undefined)
|
|
302
|
+
checkCurve(e[key], `${at}.${key}`);
|
|
303
|
+
checkGradient(e.color, `${at}.color`);
|
|
304
|
+
if (e.colorOverLife !== undefined)
|
|
305
|
+
checkGradient(e.colorOverLife, `${at}.colorOverLife`);
|
|
306
|
+
const l = e.look, lat = `${at}.look`;
|
|
307
|
+
if (!l || typeof l !== 'object')
|
|
308
|
+
fail(`${lat} must be an object with a type`);
|
|
309
|
+
else if (l.type === 'dot') {
|
|
310
|
+
if (!number(l.softness, 0, 1))
|
|
311
|
+
fail(`${lat}.softness must be 0-1`);
|
|
312
|
+
}
|
|
313
|
+
else if (l.type === 'glow') { /* nothing */ }
|
|
314
|
+
else if (l.type === 'star') {
|
|
315
|
+
if (!number(l.points, 3, 12) || !Number.isInteger(l.points))
|
|
316
|
+
fail(`${lat}.points must be a whole number 3-12`);
|
|
317
|
+
if (!number(l.sharpness, 0, 1))
|
|
318
|
+
fail(`${lat}.sharpness must be 0-1`);
|
|
319
|
+
}
|
|
320
|
+
else if (l.type === 'texture' || l.type === 'sheet') {
|
|
321
|
+
if (typeof l.texture !== 'string' || !TEXTURE_PATTERN.test(l.texture))
|
|
322
|
+
fail(`${lat}.texture must be the filename of a png, webp or jpg image in the same folder (no path)`);
|
|
323
|
+
if (l.type === 'sheet') {
|
|
324
|
+
for (const k of ['cols', 'rows', 'frames'])
|
|
325
|
+
if (!number(l[k], 1, k === 'frames' ? 4096 : 64) || !Number.isInteger(l[k]))
|
|
326
|
+
fail(`${lat}.${k} must be a whole number 1-${k === 'frames' ? 4096 : 64}`);
|
|
327
|
+
if (l.frames > l.cols * l.rows)
|
|
328
|
+
fail(`${lat}.frames is ${l.frames} but a ${l.cols}x${l.rows} grid has only ${l.cols * l.rows} cells`);
|
|
329
|
+
if (l.fps !== 'life' && !number(l.fps, 1, 120))
|
|
330
|
+
fail(`${lat}.fps must be 1-120 or "life"`);
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
else if (l.type === 'material') {
|
|
334
|
+
if (d.version < 3)
|
|
335
|
+
fail(`${lat}.type "material" is version 3: set "version": 3 (needs @umicat/three-sdk 1.37 or later)`);
|
|
336
|
+
for (const k of Object.keys(l))
|
|
337
|
+
if (k !== 'type' && k !== 'material')
|
|
338
|
+
fail(`${lat}.${k} is not a field here (expected type, material)`);
|
|
339
|
+
l.material = parseMaterial(l.material, `${lat}.material`, fail, { checkCurve, checkGradient, texturePattern: TEXTURE_PATTERN });
|
|
340
|
+
}
|
|
341
|
+
else
|
|
342
|
+
fail(`${lat}.type must be dot, glow, star, texture, sheet or material`);
|
|
343
|
+
if (!['camera', 'velocity', 'ground', 'axis'].includes(e.align))
|
|
344
|
+
fail(`${at}.align must be "camera", "velocity", "ground" or "axis"`);
|
|
78
345
|
if (!['normal', 'additive'].includes(e.blend))
|
|
79
346
|
fail(`${at}.blend must be "normal" or "additive"`);
|
|
80
|
-
if (e.
|
|
81
|
-
|
|
347
|
+
if (!Array.isArray(e.children) || e.children.length > LIMITS.children)
|
|
348
|
+
fail(`${at}.children must be a list of 0-${LIMITS.children}`);
|
|
349
|
+
return e;
|
|
82
350
|
});
|
|
351
|
+
// Sub-emitters: a real emitter, not itself, no loops.
|
|
352
|
+
const childrenOf = new Map(d.emitters.map((e) => [e.id, e.children.map((c) => c.emitter)]));
|
|
353
|
+
d.emitters.forEach((e, i) => e.children.forEach((c, k) => {
|
|
354
|
+
const at = `emitters[${i}].children[${k}]`;
|
|
355
|
+
if (!c || typeof c !== 'object')
|
|
356
|
+
fail(`${at} is not an object`);
|
|
357
|
+
if (!emitterIds.has(c.emitter))
|
|
358
|
+
fail(`${at}.emitter "${c.emitter}" is not an emitter in this effect`);
|
|
359
|
+
if (!['birth', 'life', 'death'].includes(c.when))
|
|
360
|
+
fail(`${at}.when must be "birth", "life" or "death"`);
|
|
361
|
+
if (!number(c.count, 0, 100) || !Number.isInteger(c.count))
|
|
362
|
+
fail(`${at}.count must be a whole number 0-100`);
|
|
363
|
+
if (!number(c.rate, 0, 240))
|
|
364
|
+
fail(`${at}.rate must be 0-240`);
|
|
365
|
+
if (typeof c.inheritVelocity !== 'boolean')
|
|
366
|
+
fail(`${at}.inheritVelocity must be a boolean`);
|
|
367
|
+
}));
|
|
368
|
+
const visiting = new Set(), done = new Set();
|
|
369
|
+
const walk = (id) => {
|
|
370
|
+
if (done.has(id))
|
|
371
|
+
return;
|
|
372
|
+
if (visiting.has(id))
|
|
373
|
+
fail(`emitter "${id}" spawns itself through its children`);
|
|
374
|
+
visiting.add(id);
|
|
375
|
+
for (const c of childrenOf.get(id) ?? [])
|
|
376
|
+
walk(c);
|
|
377
|
+
visiting.delete(id);
|
|
378
|
+
done.add(id);
|
|
379
|
+
};
|
|
380
|
+
for (const id of emitterIds)
|
|
381
|
+
walk(id);
|
|
382
|
+
const budget = particleBudget(d);
|
|
83
383
|
if (budget > LIMITS.particles)
|
|
84
|
-
fail(`too many live particles: the
|
|
384
|
+
fail(`too many live particles: the most this effect can have alive at once is about ${Math.ceil(budget)} (rate x lifetime + bursts, times sub-emitters), the limit is ${LIMITS.particles}`);
|
|
85
385
|
flipbooks.forEach((f, i) => {
|
|
86
386
|
const at = `flipbooks[${i}]`;
|
|
87
387
|
if (!f || typeof f !== 'object')
|
|
@@ -108,7 +408,58 @@ export function parseVfx(value) {
|
|
|
108
408
|
if (f.blend !== 'normal' && f.blend !== 'additive')
|
|
109
409
|
fail(`${at}.blend must be "normal" or "additive"`);
|
|
110
410
|
});
|
|
111
|
-
return
|
|
411
|
+
return d;
|
|
412
|
+
}
|
|
413
|
+
/**
|
|
414
|
+
* The lowest format version that can express this document: 3 when any
|
|
415
|
+
* emitter uses the material look, else 2. The editor and the agent write
|
|
416
|
+
* this, so an effect that needs nothing new still plays on 1.36.
|
|
417
|
+
*/
|
|
418
|
+
export function minimumVersion(d) {
|
|
419
|
+
return d.emitters.some((e) => e.look?.type === 'material') ? 3 : 2;
|
|
420
|
+
}
|
|
421
|
+
/**
|
|
422
|
+
* The most particles an effect can have alive at once, estimated: per enabled
|
|
423
|
+
* emitter, rate x longest life plus every burst, and for sub-emitters, the
|
|
424
|
+
* parent's count times what each parent particle spawns.
|
|
425
|
+
*/
|
|
426
|
+
export function particleBudget(d) {
|
|
427
|
+
const byId = new Map(d.emitters.map((e) => [e.id, e]));
|
|
428
|
+
const isChild = new Set(d.emitters.flatMap((e) => e.children.map((c) => c.emitter)));
|
|
429
|
+
const live = new Map();
|
|
430
|
+
const own = (e) => isChild.has(e.id) ? 0 : e.rate * rangeMax(e.lifetime) + e.bursts.reduce((s, b) => s + b.count, 0);
|
|
431
|
+
const total = (id, seen = new Set()) => {
|
|
432
|
+
if (live.has(id))
|
|
433
|
+
return live.get(id);
|
|
434
|
+
const e = byId.get(id);
|
|
435
|
+
if (!e || !e.enabled || seen.has(id))
|
|
436
|
+
return 0;
|
|
437
|
+
seen.add(id);
|
|
438
|
+
let n = own(e);
|
|
439
|
+
for (const parent of d.emitters)
|
|
440
|
+
for (const c of parent.children)
|
|
441
|
+
if (c.emitter === id && parent.enabled) {
|
|
442
|
+
n += total(parent.id, seen) * (c.when === 'life' ? c.rate * rangeMax(e.lifetime) : c.count);
|
|
443
|
+
}
|
|
444
|
+
live.set(id, n);
|
|
445
|
+
return n;
|
|
446
|
+
};
|
|
447
|
+
return d.emitters.reduce((s, e) => s + total(e.id), 0);
|
|
448
|
+
}
|
|
449
|
+
function checkV1(d, fail) {
|
|
450
|
+
if (!Array.isArray(d.emitters))
|
|
451
|
+
fail('emitters must be a list');
|
|
452
|
+
const fields = ['rate', 'lifetime', 'speed', 'spread', 'gravity', 'size', 'endSize', 'opacity'];
|
|
453
|
+
d.emitters.forEach((e, i) => {
|
|
454
|
+
if (!e || typeof e !== 'object')
|
|
455
|
+
fail(`emitters[${i}] is not an object`);
|
|
456
|
+
for (const k of fields)
|
|
457
|
+
if (typeof e[k] !== 'number')
|
|
458
|
+
fail(`emitters[${i}].${k} must be a number (version 1)`);
|
|
459
|
+
for (const k of ['color', 'endColor'])
|
|
460
|
+
if (typeof e[k] !== 'string' || !/^#[0-9a-f]{6}$/i.test(e[k]))
|
|
461
|
+
fail(`emitters[${i}].${k} must be #rrggbb`);
|
|
462
|
+
});
|
|
112
463
|
}
|
|
113
464
|
/** An effect is a project ASSET named `<stem>.vfx.json`; the server keeps the
|
|
114
465
|
* whole compound extension, so this suffix is what marks one. */
|
package/dist/vfx/index.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
export * from './document.js';
|
|
2
2
|
export * from './templates.js';
|
|
3
3
|
export { VfxInstance } from './VfxInstance.js';
|
|
4
|
+
export * from './material.js';
|
|
4
5
|
export type { VfxInstanceOptions, VfxTextureSource } from './VfxInstance.js';
|
|
5
6
|
export { loadVfx, VfxEffect, siblingUrl, prepareSheetTexture } from './load.js';
|
|
6
7
|
export type { LoadVfxOptions } from './load.js';
|
package/dist/vfx/index.js
CHANGED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The effect MATERIAL (format v3, umicat-design ADR-055): how a particle (and,
|
|
3
|
+
* later, a mesh layer) is drawn. Plain data, compiled into one shader.
|
|
4
|
+
*
|
|
5
|
+
* Modelled on the general material the Binbun packs ship
|
|
6
|
+
* (`shared/shader/transparent.gdshader`, their most-used shader):
|
|
7
|
+
*
|
|
8
|
+
* 1. up to three MASKS -- procedural noise, a gradient, a shape or an image,
|
|
9
|
+
* each scaled / scrolled / spun / optionally in polar UVs -- combined
|
|
10
|
+
* into one value m (0..1);
|
|
11
|
+
* 2. DISSOLVE d is taken off m: v = m - d;
|
|
12
|
+
* 3. alpha = smoothstep(threshold, threshold + softness, v);
|
|
13
|
+
* 4. the colour is the GRADIENT MAP `color` at v (a colour ramp indexed by
|
|
14
|
+
* the mask -- the white-hot core of a flame), optionally with a glowing
|
|
15
|
+
* EDGE where v is just above the threshold;
|
|
16
|
+
* 5. x `emission` (HDR) x the particle's own colour and alpha.
|
|
17
|
+
*
|
|
18
|
+
* Numbers marked `Animated` are a constant or `{ overLife: Curve }` --
|
|
19
|
+
* sampled at the particle's age. That is what Binbun's shaders do by reading
|
|
20
|
+
* the particle COLOR as data; here the file says what the number is for.
|
|
21
|
+
*/
|
|
22
|
+
import * as T from 'three';
|
|
23
|
+
import { type Curve, type Gradient } from './document.js';
|
|
24
|
+
export type Animated = number | {
|
|
25
|
+
overLife: Curve;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Generated in the browser, tileable. `frequency` is cells across the tile.
|
|
29
|
+
* Godot's simplex maps to perlin (same look, a periodic version is simpler).
|
|
30
|
+
* cellular: distance to the nearest feature point (Voronoi blobs);
|
|
31
|
+
* cellEdges: F2 - F1 (bright cell walls).
|
|
32
|
+
*/
|
|
33
|
+
export interface NoiseSource {
|
|
34
|
+
type: 'noise';
|
|
35
|
+
kind: 'perlin' | 'value' | 'cellular' | 'cellEdges';
|
|
36
|
+
fractal: 'none' | 'fbm' | 'ridged' | 'pingpong';
|
|
37
|
+
octaves: number;
|
|
38
|
+
frequency: number;
|
|
39
|
+
seed: number;
|
|
40
|
+
/** Domain warp: each sample is pushed by a second, smooth noise, by up to this many cells -- swirls and smears (Godot domain_warp). 0 = off. */
|
|
41
|
+
warp: number;
|
|
42
|
+
/** pingpong only: how many times the value folds back (Godot's fractal_ping_pong_strength, default 2). Higher = thinner strands. */
|
|
43
|
+
pingpong: number;
|
|
44
|
+
/** Texture side in pixels. */
|
|
45
|
+
size: 64 | 128 | 256 | 512;
|
|
46
|
+
}
|
|
47
|
+
export type MaskSource = NoiseSource
|
|
48
|
+
/**
|
|
49
|
+
* linear: 0 at the left edge to 1 at the right. radial: 1 at `center` to 0
|
|
50
|
+
* half a tile away. square: the same, square. `center` is in UVs, v up.
|
|
51
|
+
*/
|
|
52
|
+
| {
|
|
53
|
+
type: 'gradient';
|
|
54
|
+
fill: 'linear' | 'radial' | 'square';
|
|
55
|
+
center: [number, number];
|
|
56
|
+
}
|
|
57
|
+
/** The part-1 particle shapes, plus a ring (`radius` and `width` as fractions of the half-size). */
|
|
58
|
+
| {
|
|
59
|
+
type: 'shape';
|
|
60
|
+
shape: 'dot' | 'glow' | 'star' | 'ring';
|
|
61
|
+
softness: number;
|
|
62
|
+
points: number;
|
|
63
|
+
sharpness: number;
|
|
64
|
+
radius: number;
|
|
65
|
+
width: number;
|
|
66
|
+
}
|
|
67
|
+
/** An image asset next to the effect. `channel` luma = brightness x alpha. */
|
|
68
|
+
| {
|
|
69
|
+
type: 'image';
|
|
70
|
+
texture: string;
|
|
71
|
+
channel: 'luma' | 'r' | 'a';
|
|
72
|
+
};
|
|
73
|
+
/** Binbun's twelve (`util/blend.gdshaderinc`), in its order. dodge is a / (1 - b); linearBurn a + b - 1. */
|
|
74
|
+
export declare const MASK_BLENDS: readonly ["add", "subtract", "multiply", "min", "max", "screen", "overlay", "hardLight", "softLight", "dodge", "burn", "linearBurn"];
|
|
75
|
+
export type MaskBlend = typeof MASK_BLENDS[number];
|
|
76
|
+
export interface Mask {
|
|
77
|
+
source: MaskSource;
|
|
78
|
+
/** UV repeats across the surface. */
|
|
79
|
+
scale: [number, number];
|
|
80
|
+
/** Tiles a second the texture moves: +u to the right, +v up (Godot's v scroll has the same sign; negate its u). */
|
|
81
|
+
scroll: [number, number];
|
|
82
|
+
/** Degrees a second, around the middle. */
|
|
83
|
+
spin: number;
|
|
84
|
+
/** A fixed turn of the texture, degrees around the middle (Binbun's uv alignment modes are 90-degree turns). */
|
|
85
|
+
rotation: number;
|
|
86
|
+
/** Map the UVs to (angle, distance from the middle): a scroll in v then flows outward. */
|
|
87
|
+
polar: boolean;
|
|
88
|
+
/** Each particle starts at its own place in the texture, so a crowd of particles is not identical. */
|
|
89
|
+
randomOffset: boolean;
|
|
90
|
+
invert: boolean;
|
|
91
|
+
/** Reshape the value with smoothstep(lo, hi, value) -- a soft threshold on this mask alone. null = as is. */
|
|
92
|
+
levels: [number, number] | null;
|
|
93
|
+
/**
|
|
94
|
+
* Added to this mask's value, then clamped to 0..1. Animate it over life
|
|
95
|
+
* with a linear gradient mask and `subtract` for a wipe that eats the
|
|
96
|
+
* particle from one side.
|
|
97
|
+
*/
|
|
98
|
+
offset: Animated;
|
|
99
|
+
/** How this mask combines into the ones before it (ignored on the first). */
|
|
100
|
+
blend: MaskBlend;
|
|
101
|
+
strength: Animated;
|
|
102
|
+
}
|
|
103
|
+
export interface Material {
|
|
104
|
+
masks: Mask[];
|
|
105
|
+
/** Taken off the mask value: 0 = whole, 1 = gone. Animate it over life to erode a particle away. */
|
|
106
|
+
dissolve: Animated;
|
|
107
|
+
/**
|
|
108
|
+
* alpha = ramp(threshold, threshold + softness, mask - dissolve) ^ power.
|
|
109
|
+
* `ramp` smooth is a smoothstep; linear a straight line (Binbun's
|
|
110
|
+
* transparent shader is linear with power 3).
|
|
111
|
+
*/
|
|
112
|
+
threshold: Animated;
|
|
113
|
+
softness: number;
|
|
114
|
+
ramp: 'smooth' | 'linear';
|
|
115
|
+
power: number;
|
|
116
|
+
/** A glowing rim where the material is about to dissolve. width 0 = none. */
|
|
117
|
+
edge: {
|
|
118
|
+
width: number;
|
|
119
|
+
color: string;
|
|
120
|
+
emission: number;
|
|
121
|
+
};
|
|
122
|
+
/** The gradient map: the colour at each mask value (t = 0 the faint parts, 1 the strongest). */
|
|
123
|
+
color: Gradient;
|
|
124
|
+
opacity: Animated;
|
|
125
|
+
/** Brightness; above 1 is HDR. Multiplies the emitter's `intensity`. */
|
|
126
|
+
emission: Animated;
|
|
127
|
+
/** blend: soft alpha. cutout: hard edge at alpha 0.5. dither: a stipple instead of transparency. */
|
|
128
|
+
alphaMode: 'blend' | 'cutout' | 'dither';
|
|
129
|
+
}
|
|
130
|
+
export declare const MATERIAL_LIMITS: {
|
|
131
|
+
readonly masks: 3;
|
|
132
|
+
readonly curves: 8;
|
|
133
|
+
};
|
|
134
|
+
export declare const ANIMATED_FIELDS: {
|
|
135
|
+
readonly dissolve: readonly [-1, 2];
|
|
136
|
+
readonly threshold: readonly [-1, 2];
|
|
137
|
+
readonly opacity: readonly [0, 1];
|
|
138
|
+
readonly emission: readonly [0, 16];
|
|
139
|
+
};
|
|
140
|
+
export declare function noiseDefaults(): NoiseSource;
|
|
141
|
+
export declare function maskDefaults(source?: MaskSource): Mask;
|
|
142
|
+
export declare function shapeSource(shape?: 'dot' | 'glow' | 'star' | 'ring'): MaskSource;
|
|
143
|
+
/** A soft round particle with a noise texture: a blank material that already reads as something. */
|
|
144
|
+
export declare function materialDefaults(): Material;
|
|
145
|
+
/** The value of an Animated number at life t (0..1). */
|
|
146
|
+
export declare function sampleAnimated(a: Animated, t: number): number;
|
|
147
|
+
/** Every image filename a material reads. */
|
|
148
|
+
export declare function materialTextures(m: Material): string[];
|
|
149
|
+
type Fail = (why: string) => never;
|
|
150
|
+
/**
|
|
151
|
+
* Fills omitted fields from the defaults, refuses unknown ones, checks
|
|
152
|
+
* ranges. `checkCurve` / `checkGradient` / `texturePattern` come from the
|
|
153
|
+
* document parser so the messages read the same.
|
|
154
|
+
*/
|
|
155
|
+
export declare function parseMaterial(input: unknown, at: string, fail: Fail, h: {
|
|
156
|
+
checkCurve: (v: unknown, at: string) => void;
|
|
157
|
+
checkGradient: (v: unknown, at: string) => void;
|
|
158
|
+
texturePattern: RegExp;
|
|
159
|
+
}): Material;
|
|
160
|
+
/**
|
|
161
|
+
* The noise as `size * size` bytes, normalised to the full 0..255 range (as
|
|
162
|
+
* Godot's NoiseTexture2D does by default). Tileable: every octave is periodic
|
|
163
|
+
* in a whole number of cells. Deterministic per source.
|
|
164
|
+
*/
|
|
165
|
+
export declare function generateNoise(n: NoiseSource): Uint8Array;
|
|
166
|
+
export declare function acquireNoiseTexture(n: NoiseSource): T.DataTexture;
|
|
167
|
+
export declare function releaseNoiseTexture(t: T.Texture): void;
|
|
168
|
+
/** For tests: how many distinct noise textures are alive. */
|
|
169
|
+
export declare function noiseTexturesAlive(): number;
|
|
170
|
+
/**
|
|
171
|
+
* A compiled material: the fragment-shader body for these features, the
|
|
172
|
+
* uniforms it reads, and what to free. The GLSL depends only on the
|
|
173
|
+
* material's STRUCTURE (which sources, blends, which numbers are curves), not
|
|
174
|
+
* its numbers, so editing a number never recompiles.
|
|
175
|
+
*/
|
|
176
|
+
export interface CompiledMaterial {
|
|
177
|
+
/** Declarations + `vec4 vfxMaterial(vec2 uv, vec2 life)`. life = (t, random). */
|
|
178
|
+
code: string;
|
|
179
|
+
uniforms: Record<string, T.IUniform>;
|
|
180
|
+
/** Image filenames, by mask index, the caller binds into `uMask<i>`. */
|
|
181
|
+
images: Map<number, string>;
|
|
182
|
+
alphaMode: Material['alphaMode'];
|
|
183
|
+
dispose(): void;
|
|
184
|
+
}
|
|
185
|
+
export declare function compileMaterial(m: Material): CompiledMaterial;
|
|
186
|
+
/**
|
|
187
|
+
* Starting points, so nobody begins from a blank material. Each is what one
|
|
188
|
+
* of the reference rebuilds needed (ADR-055), with the numbers rounded.
|
|
189
|
+
*/
|
|
190
|
+
export declare const MATERIAL_PRESETS: Record<string, () => Material>;
|
|
191
|
+
export {};
|