@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.
@@ -1,46 +1,188 @@
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
+ * 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
- return [...new Set((document.flipbooks ?? []).map((f) => f.texture))];
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 d = value;
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 !== 1)
37
- fail('version must be 1');
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, .1, 60))
43
- fail('duration must be 0.1-60');
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
- let budget = 0;
65
- d.emitters.forEach((e, i) => {
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 (!e || typeof e !== 'object')
244
+ if (!input || typeof input !== 'object' || Array.isArray(input))
68
245
  fail(`${at} is not an object`);
69
- checkId(e.id, at);
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 EMITTER_RANGES)
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 of ['color', 'endColor'])
76
- if (!color(e[key]))
77
- fail(`${at}.${key} must be #rrggbb`);
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.enabled)
81
- budget += Math.ceil(e.rate * e.lifetime);
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 sum of rate x lifetime over enabled layers is ${budget}, the limit is ${LIMITS.particles}`);
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 structuredClone(d);
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. */
@@ -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
@@ -6,4 +6,5 @@
6
6
  export * from './document.js';
7
7
  export * from './templates.js';
8
8
  export { VfxInstance } from './VfxInstance.js';
9
+ export * from './material.js';
9
10
  export { loadVfx, VfxEffect, siblingUrl, prepareSheetTexture } from './load.js';
@@ -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 {};