@umicat/three-sdk 1.35.0 → 1.36.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.
@@ -1,46 +1,180 @@
1
- export const LIMITS = { rate: 300, lifetime: 10, emitters: 8, layers: 8, particles: 4000, cells: 4096 };
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
+ export const LIMITS = { emitters: 8, layers: 8, particles: 4000, cells: 4096, bursts: 16, children: 4, curvePoints: 8, gradientStops: 16 };
19
+ /** Every emitter field's value when a document leaves it out. */
20
+ export function emitterDefaults() {
21
+ return {
22
+ enabled: true, rate: 20, bursts: [], start: 0, stop: null, lifetime: 1.5, space: 'local',
23
+ shape: { type: 'point' }, shapeOffset: [0, 0, 0], shapeScale: [1, 1, 1], rotation: [0, 0, 0],
24
+ direction: [0, 1, 0], spread: 15, flatness: 0, speed: 1, randomVelocity: [0, 0, 0], gravity: [0, 0, 0],
25
+ radialSpeed: 0, radialAccel: 0, tangentialAccel: 0, orbit: 0, damping: 0,
26
+ angle: 0, spin: 0, size: .2,
27
+ color: { stops: [[0, '#ffffff', 1]] }, intensity: 1,
28
+ look: { type: 'dot', softness: .5 }, align: 'camera', stretch: 0, blend: 'normal', children: [],
29
+ };
30
+ }
31
+ /** A new particle layer: the defaults, plus a fade-out so it reads as particles at once. */
32
+ export function emitterLayer(id, patch = {}) {
33
+ return { id, ...emitterDefaults(), alphaOverLife: { points: [[0, 0], [.1, 1], [1, 0]] }, ...patch };
34
+ }
2
35
  export function campfire() {
3
- return { version: 1, name: 'Campfire', seed: 17, duration: 4, loop: true, humanCurated: false, emitters: [
36
+ return upgradeV1({ version: 1, name: 'Campfire', seed: 17, duration: 4, loop: true, humanCurated: false, emitters: [
4
37
  { 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
38
  { 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
39
  { 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
- ] };
40
+ ] });
41
+ }
42
+ /**
43
+ * A version-1 document as the v2 document that plays the same: same spawn
44
+ * disc, speeds, jitter, gravity, colour, size and alpha over life. (Not
45
+ * bit-identical -- random numbers are drawn in a different order -- but the
46
+ * same effect.) v1 `size` was a point RADIUS; v2 `size` is the width.
47
+ */
48
+ export function upgradeV1(v1) {
49
+ const emitters = v1.emitters.map((e) => ({
50
+ ...emitterDefaults(), id: e.id, enabled: e.enabled, rate: e.rate, lifetime: e.lifetime,
51
+ shape: { type: 'ring', radius: .15, inner: 0, height: 0, axis: [0, 1, 0] },
52
+ direction: [0, 1, 0], spread: 0, speed: [e.speed * .8, e.speed * 1.2],
53
+ randomVelocity: [e.spread / 2, 0, e.spread / 2], gravity: [0, e.gravity, 0],
54
+ size: e.size * 2, sizeOverLife: { points: [[0, 1], [1, e.size > 0 ? e.endSize / e.size : 1]] },
55
+ color: { stops: [[0, '#ffffff', 1]] }, colorOverLife: { stops: [[0, e.color, 1], [1, e.endColor, 1]] },
56
+ alphaOverLife: { points: [[0, 0], [.125, .875 * e.opacity], [1, 0]] },
57
+ look: { type: 'dot', softness: .5 }, blend: e.blend,
58
+ }));
59
+ const doc = { version: 2, name: v1.name, seed: v1.seed, duration: v1.duration, loop: v1.loop, humanCurated: v1.humanCurated, emitters };
60
+ if (v1.flipbooks !== undefined)
61
+ doc.flipbooks = v1.flipbooks;
62
+ return doc;
8
63
  }
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
64
  /** Per-flipbook numeric fields and their allowed ranges. `frames` is further capped at cols x rows. */
12
65
  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
66
  const INTEGER_FIELDS = new Set(['cols', 'rows', 'frames']);
14
67
  /** A bare filename with an image extension: no folders, so it can only name a sibling of the effect. */
15
68
  export const TEXTURE_PATTERN = /^[^/\\?#]{1,200}\.(png|webp|jpe?g)$/i;
69
+ /** Numeric emitter fields that take a `Range`, with their allowed bounds. Shared with the editor's inputs. */
70
+ export const EMITTER_RANGES = {
71
+ lifetime: [.01, 30], speed: [-1000, 1000], radialSpeed: [-100, 100], radialAccel: [-1000, 1000],
72
+ tangentialAccel: [-1000, 1000], orbit: [-100, 100], damping: [0, 1000], angle: [-3600, 3600],
73
+ spin: [-36000, 36000], size: [0, 100],
74
+ };
75
+ /** Plain numeric emitter fields and their bounds. */
76
+ export const EMITTER_NUMBERS = {
77
+ rate: [0, 1000], start: [0, 60], spread: [0, 180], flatness: [0, 1], intensity: [0, 16], stretch: [0, 10],
78
+ };
79
+ /** Vector emitter fields and the bound on each component. */
80
+ export const EMITTER_VECTORS = {
81
+ shapeOffset: [-100, 100], shapeScale: [-100, 100], rotation: [-360, 360], direction: [-1000, 1000], randomVelocity: [0, 100], gravity: [-100, 100],
82
+ };
83
+ export const CURVE_FIELDS = ['speedLimit', 'radialAccelOverLife', 'orbitOverLife', 'sizeOverLife', 'alphaOverLife'];
16
84
  /** A new flipbook layer with sensible defaults, for the editor's "Add" and for the agent. */
17
85
  export function flipbookLayer(id, texture) {
18
86
  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
87
  }
20
- /** Every texture filename a document needs, once each. */
88
+ /** Every texture filename a document needs (flipbook sheets and particle images), once each. */
21
89
  export function vfxTextures(document) {
22
- return [...new Set((document.flipbooks ?? []).map((f) => f.texture))];
90
+ const names = (document.flipbooks ?? []).map((f) => f.texture);
91
+ for (const e of document.emitters)
92
+ if (e.look.type === 'texture' || e.look.type === 'sheet')
93
+ names.push(e.look.texture);
94
+ return [...new Set(names)];
23
95
  }
96
+ // ---------------------------------------------------------------- sampling
97
+ /** The value of a Range for one random number u in [0, 1). */
98
+ export function pickRange(r, u) { return typeof r === 'number' ? r : r[0] + (r[1] - r[0]) * u; }
99
+ export function rangeMax(r) { return typeof r === 'number' ? r : Math.max(r[0], r[1]); }
100
+ /** Curve value at t (0..1). Monotone cubic (Fritsch-Carlson) when `smooth`, so it never overshoots its points. */
101
+ export function sampleCurve(c, t) {
102
+ const p = c.points, n = p.length;
103
+ if (t <= p[0][0])
104
+ return p[0][1];
105
+ if (t >= p[n - 1][0])
106
+ return p[n - 1][1];
107
+ let i = 0;
108
+ while (i < n - 2 && t > p[i + 1][0])
109
+ i++;
110
+ const [x0, y0] = p[i], [x1, y1] = p[i + 1], h = x1 - x0;
111
+ if (h <= 0)
112
+ return y1;
113
+ const s = (t - x0) / h;
114
+ if (!c.smooth)
115
+ return y0 + (y1 - y0) * s;
116
+ const slope = (a) => (p[a + 1][1] - p[a][1]) / Math.max(1e-9, p[a + 1][0] - p[a][0]);
117
+ const tangent = (k) => {
118
+ if (k === 0)
119
+ return slope(0);
120
+ if (k === n - 1)
121
+ return slope(n - 2);
122
+ const a = slope(k - 1), b = slope(k);
123
+ 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);
124
+ };
125
+ const m0 = tangent(i) * h, m1 = tangent(i + 1) * h, s2 = s * s, s3 = s2 * s;
126
+ return (2 * s3 - 3 * s2 + 1) * y0 + (s3 - 2 * s2 + s) * m0 + (-2 * s3 + 3 * s2) * y1 + (s3 - s2) * m1;
127
+ }
128
+ const hex = (h, k) => parseInt(h.slice(1 + k * 2, 3 + k * 2), 16) / 255;
129
+ /** Gradient at t, written into out as [r, g, b, a] (sRGB components 0..1). */
130
+ export function sampleGradient(g, t, out = [0, 0, 0, 0]) {
131
+ const s = g.stops, n = s.length;
132
+ let a = s[0], b = s[0], f = 0;
133
+ if (t >= s[n - 1][0]) {
134
+ a = b = s[n - 1];
135
+ }
136
+ else if (t > s[0][0]) {
137
+ let i = 0;
138
+ while (i < n - 2 && t > s[i + 1][0])
139
+ i++;
140
+ a = s[i];
141
+ b = s[i + 1];
142
+ f = b[0] > a[0] ? (t - a[0]) / (b[0] - a[0]) : 1;
143
+ }
144
+ for (let k = 0; k < 3; k++)
145
+ out[k] = hex(a[1], k) + (hex(b[1], k) - hex(a[1], k)) * f;
146
+ out[3] = a[2] + (b[2] - a[2]) * f;
147
+ return out;
148
+ }
149
+ // ---------------------------------------------------------------- validation
24
150
  /**
25
151
  * Reject malformed/unsupported resources instead of silently rewriting them.
26
152
  * The message names the field and its allowed range: the agent writes these
27
153
  * documents by hand, and "Invalid VFX resource" gave it nothing to fix.
154
+ *
155
+ * Returns a COMPLETE copy: a version-1 document is upgraded, and emitter
156
+ * fields left out take `emitterDefaults()`.
28
157
  */
29
158
  export function parseVfx(value) {
30
159
  const fail = (why) => { throw new Error(`Invalid VFX resource: ${why}`); };
31
160
  if (!value || typeof value !== 'object')
32
161
  return fail('not an object');
33
- const d = value;
162
+ const raw = value;
163
+ if (raw.version === 1) {
164
+ checkV1(value, fail);
165
+ return parseVfx(upgradeV1(structuredClone(value)));
166
+ }
167
+ const d = structuredClone(value);
34
168
  const number = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
35
169
  const color = (v) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v);
36
- if (d.version !== 1)
37
- fail('version must be 1');
170
+ if (d.version !== 2)
171
+ fail('version must be 2 (or 1, which is upgraded)');
38
172
  if (typeof d.name !== 'string' || !d.name.trim() || d.name.length > 80)
39
173
  fail('name must be 1-80 characters');
40
174
  if (!number(d.seed, 1, 2147483646) || !Number.isInteger(d.seed))
41
175
  fail('seed must be an integer 1-2147483646');
42
- if (!number(d.duration, .1, 60))
43
- fail('duration must be 0.1-60');
176
+ if (!number(d.duration, .02, 60))
177
+ fail('duration must be 0.02-60');
44
178
  if (typeof d.loop !== 'boolean')
45
179
  fail('loop must be a boolean');
46
180
  if (typeof d.humanCurated !== 'boolean')
@@ -61,27 +195,177 @@ export function parseVfx(value) {
61
195
  fail(`${at}.id "${id}" is used twice`);
62
196
  ids.add(id);
63
197
  };
64
- let budget = 0;
65
- d.emitters.forEach((e, i) => {
198
+ const checkRange = (v, at, min, max) => {
199
+ if (number(v, min, max))
200
+ return;
201
+ if (Array.isArray(v) && v.length === 2 && number(v[0], min, max) && number(v[1], min, max) && v[0] <= v[1])
202
+ return;
203
+ fail(`${at} must be a number ${min}-${max}, or [min, max] within that`);
204
+ };
205
+ const checkVec = (v, at, min, max) => {
206
+ if (!Array.isArray(v) || v.length !== 3 || !v.every((x) => number(x, min, max)))
207
+ fail(`${at} must be [x, y, z], each ${min}-${max}`);
208
+ };
209
+ const checkCurve = (v, at) => {
210
+ const c = v;
211
+ if (!c || typeof c !== 'object' || !Array.isArray(c.points) || c.points.length < 1 || c.points.length > LIMITS.curvePoints)
212
+ fail(`${at} must be { points: [[t, value], ...] } with 1-${LIMITS.curvePoints} points`);
213
+ c.points.forEach((p, i) => {
214
+ if (!Array.isArray(p) || p.length !== 2 || !number(p[0], 0, 1) || !number(p[1], -1000, 1000))
215
+ fail(`${at}.points[${i}] must be [t 0-1, value -1000-1000]`);
216
+ if (i > 0 && p[0] < c.points[i - 1][0])
217
+ fail(`${at}.points must be in increasing t`);
218
+ });
219
+ if (c.smooth !== undefined && typeof c.smooth !== 'boolean')
220
+ fail(`${at}.smooth must be a boolean`);
221
+ };
222
+ const checkGradient = (v, at) => {
223
+ const g = v;
224
+ if (!g || typeof g !== 'object' || !Array.isArray(g.stops) || g.stops.length < 1 || g.stops.length > LIMITS.gradientStops)
225
+ fail(`${at} must be { stops: [[t, "#rrggbb", alpha], ...] } with 1-${LIMITS.gradientStops} stops`);
226
+ g.stops.forEach((s, i) => {
227
+ if (!Array.isArray(s) || s.length !== 3 || !number(s[0], 0, 1) || !color(s[1]) || !number(s[2], 0, 1))
228
+ fail(`${at}.stops[${i}] must be [t 0-1, "#rrggbb", alpha 0-1]`);
229
+ if (i > 0 && s[0] < g.stops[i - 1][0])
230
+ fail(`${at}.stops must be in increasing t`);
231
+ });
232
+ };
233
+ const emitterIds = new Set();
234
+ d.emitters = d.emitters.map((input, i) => {
66
235
  const at = `emitters[${i}]`;
67
- if (!e || typeof e !== 'object')
236
+ if (!input || typeof input !== 'object' || Array.isArray(input))
68
237
  fail(`${at} is not an object`);
69
- checkId(e.id, at);
238
+ checkId(input.id, at);
239
+ emitterIds.add(input.id);
240
+ const known = new Set(['id', ...Object.keys(emitterDefaults()), ...CURVE_FIELDS, 'colorOverLife']);
241
+ for (const key of Object.keys(input))
242
+ if (!known.has(key))
243
+ fail(`${at}.${key} is not an emitter field (a version-1 field? set "version": 1, or see emitterDefaults())`);
244
+ const e = { ...emitterDefaults(), ...input };
70
245
  if (typeof e.enabled !== 'boolean')
71
246
  fail(`${at}.enabled must be a boolean`);
72
- for (const [key, min, max] of EMITTER_RANGES)
247
+ for (const [key, [min, max]] of Object.entries(EMITTER_NUMBERS))
73
248
  if (!number(e[key], min, max))
74
249
  fail(`${at}.${key} must be ${min}-${max}`);
75
- for (const key of ['color', 'endColor'])
76
- if (!color(e[key]))
77
- fail(`${at}.${key} must be #rrggbb`);
250
+ for (const [key, [min, max]] of Object.entries(EMITTER_RANGES))
251
+ checkRange(e[key], `${at}.${key}`, min, max);
252
+ for (const [key, [min, max]] of Object.entries(EMITTER_VECTORS))
253
+ checkVec(e[key], `${at}.${key}`, min, max);
254
+ if (typeof e.lifetime === 'number' ? e.lifetime < .01 : e.lifetime[0] < .01)
255
+ fail(`${at}.lifetime must be at least 0.01`);
256
+ if (e.stop !== null && !(number(e.stop, 0, 60) && e.stop > e.start))
257
+ fail(`${at}.stop must be null or a time after start (${e.start}), up to 60`);
258
+ if (!Array.isArray(e.bursts) || e.bursts.length > LIMITS.bursts)
259
+ fail(`${at}.bursts must be a list of 0-${LIMITS.bursts}`);
260
+ e.bursts.forEach((b, k) => {
261
+ if (!b || !number(b.time, 0, 60) || !number(b.count, 1, 1000) || !Number.isInteger(b.count) || !number(b.over, 0, 60))
262
+ fail(`${at}.bursts[${k}] must be { time 0-60, count 1-1000 whole, over 0-60 }`);
263
+ });
264
+ if (!['local', 'world'].includes(e.space))
265
+ fail(`${at}.space must be "local" or "world"`);
266
+ const s = e.shape;
267
+ const sat = `${at}.shape`;
268
+ if (!s || typeof s !== 'object')
269
+ fail(`${sat} must be an object with a type`);
270
+ else if (s.type === 'point') { /* nothing */ }
271
+ else if (s.type === 'sphere') {
272
+ if (!number(s.radius, 0, 100))
273
+ fail(`${sat}.radius must be 0-100`);
274
+ if (typeof s.surface !== 'boolean')
275
+ fail(`${sat}.surface must be a boolean`);
276
+ }
277
+ else if (s.type === 'box')
278
+ checkVec(s.extents, `${sat}.extents`, 0, 100);
279
+ else if (s.type === 'ring') {
280
+ if (!number(s.radius, 0, 100))
281
+ fail(`${sat}.radius must be 0-100`);
282
+ if (!number(s.inner, 0, s.radius))
283
+ fail(`${sat}.inner must be 0-radius (${s.radius})`);
284
+ if (!number(s.height, 0, 100))
285
+ fail(`${sat}.height must be 0-100`);
286
+ checkVec(s.axis, `${sat}.axis`, -1, 1);
287
+ if (Math.hypot(...s.axis) < 1e-6)
288
+ fail(`${sat}.axis must not be [0, 0, 0]`);
289
+ }
290
+ else
291
+ fail(`${sat}.type must be point, sphere, box or ring`);
292
+ for (const key of CURVE_FIELDS)
293
+ if (e[key] !== undefined)
294
+ checkCurve(e[key], `${at}.${key}`);
295
+ checkGradient(e.color, `${at}.color`);
296
+ if (e.colorOverLife !== undefined)
297
+ checkGradient(e.colorOverLife, `${at}.colorOverLife`);
298
+ const l = e.look, lat = `${at}.look`;
299
+ if (!l || typeof l !== 'object')
300
+ fail(`${lat} must be an object with a type`);
301
+ else if (l.type === 'dot') {
302
+ if (!number(l.softness, 0, 1))
303
+ fail(`${lat}.softness must be 0-1`);
304
+ }
305
+ else if (l.type === 'glow') { /* nothing */ }
306
+ else if (l.type === 'star') {
307
+ if (!number(l.points, 3, 12) || !Number.isInteger(l.points))
308
+ fail(`${lat}.points must be a whole number 3-12`);
309
+ if (!number(l.sharpness, 0, 1))
310
+ fail(`${lat}.sharpness must be 0-1`);
311
+ }
312
+ else if (l.type === 'texture' || l.type === 'sheet') {
313
+ if (typeof l.texture !== 'string' || !TEXTURE_PATTERN.test(l.texture))
314
+ fail(`${lat}.texture must be the filename of a png, webp or jpg image in the same folder (no path)`);
315
+ if (l.type === 'sheet') {
316
+ for (const k of ['cols', 'rows', 'frames'])
317
+ if (!number(l[k], 1, k === 'frames' ? 4096 : 64) || !Number.isInteger(l[k]))
318
+ fail(`${lat}.${k} must be a whole number 1-${k === 'frames' ? 4096 : 64}`);
319
+ if (l.frames > l.cols * l.rows)
320
+ fail(`${lat}.frames is ${l.frames} but a ${l.cols}x${l.rows} grid has only ${l.cols * l.rows} cells`);
321
+ if (l.fps !== 'life' && !number(l.fps, 1, 120))
322
+ fail(`${lat}.fps must be 1-120 or "life"`);
323
+ }
324
+ }
325
+ else
326
+ fail(`${lat}.type must be dot, glow, star, texture or sheet`);
327
+ if (!['camera', 'velocity', 'ground', 'axis'].includes(e.align))
328
+ fail(`${at}.align must be "camera", "velocity", "ground" or "axis"`);
78
329
  if (!['normal', 'additive'].includes(e.blend))
79
330
  fail(`${at}.blend must be "normal" or "additive"`);
80
- if (e.enabled)
81
- budget += Math.ceil(e.rate * e.lifetime);
331
+ if (!Array.isArray(e.children) || e.children.length > LIMITS.children)
332
+ fail(`${at}.children must be a list of 0-${LIMITS.children}`);
333
+ return e;
82
334
  });
335
+ // Sub-emitters: a real emitter, not itself, no loops.
336
+ const childrenOf = new Map(d.emitters.map((e) => [e.id, e.children.map((c) => c.emitter)]));
337
+ d.emitters.forEach((e, i) => e.children.forEach((c, k) => {
338
+ const at = `emitters[${i}].children[${k}]`;
339
+ if (!c || typeof c !== 'object')
340
+ fail(`${at} is not an object`);
341
+ if (!emitterIds.has(c.emitter))
342
+ fail(`${at}.emitter "${c.emitter}" is not an emitter in this effect`);
343
+ if (!['birth', 'life', 'death'].includes(c.when))
344
+ fail(`${at}.when must be "birth", "life" or "death"`);
345
+ if (!number(c.count, 0, 100) || !Number.isInteger(c.count))
346
+ fail(`${at}.count must be a whole number 0-100`);
347
+ if (!number(c.rate, 0, 240))
348
+ fail(`${at}.rate must be 0-240`);
349
+ if (typeof c.inheritVelocity !== 'boolean')
350
+ fail(`${at}.inheritVelocity must be a boolean`);
351
+ }));
352
+ const visiting = new Set(), done = new Set();
353
+ const walk = (id) => {
354
+ if (done.has(id))
355
+ return;
356
+ if (visiting.has(id))
357
+ fail(`emitter "${id}" spawns itself through its children`);
358
+ visiting.add(id);
359
+ for (const c of childrenOf.get(id) ?? [])
360
+ walk(c);
361
+ visiting.delete(id);
362
+ done.add(id);
363
+ };
364
+ for (const id of emitterIds)
365
+ walk(id);
366
+ const budget = particleBudget(d);
83
367
  if (budget > LIMITS.particles)
84
- fail(`too many live particles: the sum of rate x lifetime over enabled layers is ${budget}, the limit is ${LIMITS.particles}`);
368
+ 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
369
  flipbooks.forEach((f, i) => {
86
370
  const at = `flipbooks[${i}]`;
87
371
  if (!f || typeof f !== 'object')
@@ -108,7 +392,50 @@ export function parseVfx(value) {
108
392
  if (f.blend !== 'normal' && f.blend !== 'additive')
109
393
  fail(`${at}.blend must be "normal" or "additive"`);
110
394
  });
111
- return structuredClone(d);
395
+ return d;
396
+ }
397
+ /**
398
+ * The most particles an effect can have alive at once, estimated: per enabled
399
+ * emitter, rate x longest life plus every burst, and for sub-emitters, the
400
+ * parent's count times what each parent particle spawns.
401
+ */
402
+ export function particleBudget(d) {
403
+ const byId = new Map(d.emitters.map((e) => [e.id, e]));
404
+ const isChild = new Set(d.emitters.flatMap((e) => e.children.map((c) => c.emitter)));
405
+ const live = new Map();
406
+ const own = (e) => isChild.has(e.id) ? 0 : e.rate * rangeMax(e.lifetime) + e.bursts.reduce((s, b) => s + b.count, 0);
407
+ const total = (id, seen = new Set()) => {
408
+ if (live.has(id))
409
+ return live.get(id);
410
+ const e = byId.get(id);
411
+ if (!e || !e.enabled || seen.has(id))
412
+ return 0;
413
+ seen.add(id);
414
+ let n = own(e);
415
+ for (const parent of d.emitters)
416
+ for (const c of parent.children)
417
+ if (c.emitter === id && parent.enabled) {
418
+ n += total(parent.id, seen) * (c.when === 'life' ? c.rate * rangeMax(e.lifetime) : c.count);
419
+ }
420
+ live.set(id, n);
421
+ return n;
422
+ };
423
+ return d.emitters.reduce((s, e) => s + total(e.id), 0);
424
+ }
425
+ function checkV1(d, fail) {
426
+ if (!Array.isArray(d.emitters))
427
+ fail('emitters must be a list');
428
+ const fields = ['rate', 'lifetime', 'speed', 'spread', 'gravity', 'size', 'endSize', 'opacity'];
429
+ d.emitters.forEach((e, i) => {
430
+ if (!e || typeof e !== 'object')
431
+ fail(`emitters[${i}] is not an object`);
432
+ for (const k of fields)
433
+ if (typeof e[k] !== 'number')
434
+ fail(`emitters[${i}].${k} must be a number (version 1)`);
435
+ for (const k of ['color', 'endColor'])
436
+ if (typeof e[k] !== 'string' || !/^#[0-9a-f]{6}$/i.test(e[k]))
437
+ fail(`emitters[${i}].${k} must be #rrggbb`);
438
+ });
112
439
  }
113
440
  /** An effect is a project ASSET named `<stem>.vfx.json`; the server keeps the
114
441
  * whole compound extension, so this suffix is what marks one. */
@@ -1,4 +1,4 @@
1
- import { campfire } from './document.js';
1
+ import { campfire, upgradeV1, emitterLayer } from './document.js';
2
2
  /**
3
3
  * Starting points for "New effect". They ship WITH the editor rather than
4
4
  * coming from the Store, so creating an effect never depends on somebody
@@ -11,28 +11,30 @@ import { campfire } from './document.js';
11
11
  * that falls back, not a sphere.
12
12
  */
13
13
  const layer = (id, e) => ({ id, enabled: true, ...e });
14
+ // The ready-made ones were written in the version-1 model and are upgraded on the way out.
15
+ const v1 = (d) => upgradeV1({ version: 1, ...d });
14
16
  const TEMPLATES = {
15
17
  // Blank is ONE plain layer, not zero: a document needs at least one emitter,
16
18
  // and something on screen to change is a better start than an empty view.
17
- blank: () => ({ version: 1, name: 'New Effect', seed: 7, duration: 3, loop: true, humanCurated: false, emitters: [
18
- layer('layer-1', { rate: 20, lifetime: 1.5, speed: 1, spread: .5, gravity: 0, size: .15, endSize: .05, opacity: .8, color: '#ffffff', endColor: '#9aa3b2', blend: 'normal' })
19
+ blank: () => ({ version: 2, name: 'New Effect', seed: 7, duration: 3, loop: true, humanCurated: false, emitters: [
20
+ emitterLayer('layer-1', { size: .3, sizeOverLife: { points: [[0, 1], [1, .35]] }, color: { stops: [[0, '#ffffff', .8]] }, colorOverLife: { stops: [[0, '#ffffff', 1], [1, '#9aa3b2', 1]] } })
19
21
  ] }),
20
22
  campfire,
21
- smoke: () => ({ version: 1, name: 'Smoke', seed: 23, duration: 4, loop: true, humanCurated: false, emitters: [
23
+ smoke: () => v1({ name: 'Smoke', seed: 23, duration: 4, loop: true, humanCurated: false, emitters: [
22
24
  layer('puff', { rate: 14, lifetime: 4, speed: .6, spread: .35, gravity: .05, size: .25, endSize: 1.2, opacity: .35, color: '#8a8f99', endColor: '#3d424b', blend: 'normal' }),
23
25
  layer('wisp', { rate: 6, lifetime: 3, speed: .9, spread: .2, gravity: 0, size: .12, endSize: .6, opacity: .2, color: '#b4b8c0', endColor: '#5b616b', blend: 'normal' })
24
26
  ] }),
25
- sparks: () => ({ version: 1, name: 'Sparks', seed: 31, duration: 3, loop: true, humanCurated: false, emitters: [
27
+ sparks: () => v1({ name: 'Sparks', seed: 31, duration: 3, loop: true, humanCurated: false, emitters: [
26
28
  layer('sparks', { rate: 80, lifetime: .9, speed: 3.2, spread: 2.4, gravity: -6, size: .04, endSize: .01, opacity: 1, color: '#fff3b0', endColor: '#ff7a1a', blend: 'additive' }),
27
29
  layer('glow', { rate: 20, lifetime: .25, speed: .3, spread: .3, gravity: 0, size: .35, endSize: .1, opacity: .5, color: '#ffd27a', endColor: '#ff8a2a', blend: 'additive' })
28
30
  ] }),
29
- explosion: () => ({ version: 1, name: 'Explosion', seed: 41, duration: .15, loop: false, humanCurated: false, emitters: [
31
+ explosion: () => v1({ name: 'Explosion', seed: 41, duration: .15, loop: false, humanCurated: false, emitters: [
30
32
  layer('flash', { rate: 300, lifetime: .35, speed: 1.2, spread: 4, gravity: 0, size: .9, endSize: .2, opacity: .9, color: '#fff2c4', endColor: '#ff6a1a', blend: 'additive' }),
31
33
  layer('fire', { rate: 300, lifetime: .8, speed: 2.5, spread: 5, gravity: -1.5, size: .45, endSize: .1, opacity: .8, color: '#ffb347', endColor: '#d4290f', blend: 'additive' }),
32
34
  layer('debris', { rate: 300, lifetime: 1.4, speed: 4, spread: 5, gravity: -7, size: .05, endSize: .02, opacity: 1, color: '#ffe08a', endColor: '#ff4d00', blend: 'additive' }),
33
35
  layer('smoke', { rate: 200, lifetime: 2.5, speed: .8, spread: 2, gravity: .4, size: .4, endSize: 1.4, opacity: .25, color: '#5a5550', endColor: '#2a2724', blend: 'normal' })
34
36
  ] }),
35
- magic: () => ({ version: 1, name: 'Magic Aura', seed: 53, duration: 4, loop: true, humanCurated: false, emitters: [
37
+ magic: () => v1({ name: 'Magic Aura', seed: 53, duration: 4, loop: true, humanCurated: false, emitters: [
36
38
  layer('motes', { rate: 40, lifetime: 2, speed: .6, spread: .9, gravity: .2, size: .08, endSize: .01, opacity: .9, color: '#b98cff', endColor: '#3fd3ff', blend: 'additive' }),
37
39
  layer('core', { rate: 12, lifetime: 1.2, speed: .2, spread: .2, gravity: .4, size: .5, endSize: .15, opacity: .35, color: '#7a5cff', endColor: '#2bb8ff', blend: 'additive' }),
38
40
  layer('sparkle', { rate: 18, lifetime: .6, speed: 1.4, spread: 1.2, gravity: -.5, size: .05, endSize: .005, opacity: 1, color: '#ffffff', endColor: '#c9a8ff', blend: 'additive' })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.35.0",
3
+ "version": "1.36.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",