@umicat/three-sdk 1.38.0 → 1.39.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 CHANGED
@@ -110,7 +110,16 @@ velocity with `align: velocity`). Materials gained rim (fresnel),
110
110
  displacement, a cutout threshold and a band gradient; emitters gained
111
111
  per-axis `sizeOverLifeXYZ`. Meshes draw before particles.
112
112
 
113
- **Write the lowest version.** `minimumVersion(doc)` is 4 with meshes, 3 with a
113
+ **Lights and scale (version 5, 1.39.0, ADR-055 step 3).** `lights: [...]`
114
+ (at most 2 point lights: position, colour, candela intensity, range, a
115
+ start/life window, intensity over life, flicker). They are created once and
116
+ dimmed to 0 when off, because adding or removing a three.js light recompiles
117
+ every lit material in the scene; `new VfxInstance(doc, { lights: false })` or
118
+ `effect.spawn({ lights: false })` builds none. An effect placed at a scale
119
+ scales everything: world-space particles take it in speed and size, and a
120
+ light's range follows it.
121
+
122
+ **Write the lowest version.** `minimumVersion(doc)` is 5 with lights, 4 with meshes, 3 with a
114
123
  material, else 2; the editor and the agent write that, so an effect that needs nothing
115
124
  new stays version 2 and keeps playing on 1.36.
116
125
 
@@ -6,6 +6,12 @@ import { type VfxDocument, type Vec3 } from './document.js';
6
6
  export type VfxTextureSource = Map<string, T.Texture> | Record<string, T.Texture> | ((filename: string) => T.Texture | undefined);
7
7
  export interface VfxInstanceOptions {
8
8
  textures?: VfxTextureSource;
9
+ /**
10
+ * false: build no lights at all (an unlit or mobile-heavy game). Default
11
+ * true. Either way the number of lights never changes after construction,
12
+ * so a scene's lit materials never recompile because an effect played.
13
+ */
14
+ lights?: boolean;
9
15
  }
10
16
  /**
11
17
  * One playing copy of an effect. Shared by the VFX Editor and games: it owns
@@ -25,6 +31,7 @@ export declare class VfxInstance {
25
31
  private byId;
26
32
  private flipbookLayers;
27
33
  private meshLayers;
34
+ private lightLayers;
28
35
  private state;
29
36
  /** Particles born so far: hashed into each particle's `seed`. */
30
37
  private serial;
@@ -35,13 +42,15 @@ export declare class VfxInstance {
35
42
  /** (Re)creates the per-instance buffers with room for `capacity` particles. */
36
43
  private allocate;
37
44
  private buildMesh;
38
- /** A mesh layer's life fraction now, or -1 when it is not showing. */
45
+ /** A mesh layer's or light's life fraction now, or -1 when it is not showing. */
39
46
  private meshLife;
40
47
  private buildFlipbook;
41
48
  private random;
42
49
  /** Back to time 0 with the original seed: a replay is identical to the first play. */
43
50
  reset(): void;
44
51
  get particleCount(): number;
52
+ /** The point lights this instance made (empty with `{ lights: false }`). Never changes after construction. */
53
+ get lights(): readonly T.PointLight[];
45
54
  /** True once a NON-looping effect has stopped emitting, every particle has
46
55
  * died and every flipbook has played out -- the moment to `dispose()` a
47
56
  * one-shot. Always false for a looping effect. */
@@ -147,6 +147,7 @@ function resolveTexture(source, name) {
147
147
  const scratchColor = new T.Color();
148
148
  const scratchRgba = [0, 0, 0, 0];
149
149
  const scratchVec = new T.Vector3();
150
+ const scratchBasis = new T.Matrix3();
150
151
  /**
151
152
  * One playing copy of an effect. Shared by the VFX Editor and games: it owns
152
153
  * no renderer, no DOM and no animation loop -- add `root` to a scene and call
@@ -165,6 +166,7 @@ export class VfxInstance {
165
166
  this.byId = new Map();
166
167
  this.flipbookLayers = [];
167
168
  this.meshLayers = [];
169
+ this.lightLayers = [];
168
170
  this.state = 1;
169
171
  /** Particles born so far: hashed into each particle's `seed`. */
170
172
  this.serial = 0;
@@ -182,6 +184,16 @@ export class VfxInstance {
182
184
  for (const config of this.document.flipbooks ?? [])
183
185
  this.flipbookLayers.push(this.buildFlipbook(config, resolveTexture(options.textures, config.texture)));
184
186
  (this.document.meshes ?? []).forEach((config, i) => this.meshLayers.push(this.buildMesh(config, i, (name) => resolveTexture(options.textures, name))));
187
+ if (options.lights !== false)
188
+ (this.document.lights ?? []).forEach((config, i) => {
189
+ // Created now and dimmed to 0 when off: never added or removed later.
190
+ const light = new T.PointLight(new T.Color(config.color), 0, config.range, 2);
191
+ light.name = config.id;
192
+ light.position.set(...config.position);
193
+ light.castShadow = false;
194
+ this.root.add(light);
195
+ this.lightLayers.push({ config, light, seed: seedOf(this.document.seed, 200000 + i) });
196
+ });
185
197
  this.draw();
186
198
  }
187
199
  buildParticles(config, index, root, textureOf) {
@@ -276,7 +288,7 @@ export class VfxInstance {
276
288
  this.root.add(mesh);
277
289
  return { config, mesh, geometry, material, compiled, images, repeats, seed: seedOf(this.document.seed, 100000 + index) };
278
290
  }
279
- /** A mesh layer's life fraction now, or -1 when it is not showing. */
291
+ /** A mesh layer's or light's life fraction now, or -1 when it is not showing. */
280
292
  meshLife(c) {
281
293
  if (!c.enabled)
282
294
  return -1;
@@ -325,13 +337,16 @@ export class VfxInstance {
325
337
  this.draw();
326
338
  }
327
339
  get particleCount() { return this.live; }
340
+ /** The point lights this instance made (empty with `{ lights: false }`). Never changes after construction. */
341
+ get lights() { return this.lightLayers.map((l) => l.light); }
328
342
  /** True once a NON-looping effect has stopped emitting, every particle has
329
343
  * died and every flipbook has played out -- the moment to `dispose()` a
330
344
  * one-shot. Always false for a looping effect. */
331
345
  get finished() {
332
346
  if (this.document.loop || this.time < this.document.duration)
333
347
  return false;
334
- const meshesDone = this.meshLayers.every(({ config: c }) => !c.enabled || this.time >= c.start + (c.life ?? Math.max(.01, this.document.duration - c.start)));
348
+ const over = (c) => !c.enabled || this.time >= c.start + (c.life ?? Math.max(.01, this.document.duration - c.start));
349
+ const meshesDone = this.meshLayers.every(({ config }) => over(config)) && this.lightLayers.every(({ config }) => over(config));
335
350
  return this.live === 0 && meshesDone && this.flipbookLayers.every((f) => f.done);
336
351
  }
337
352
  /** Kept for 1.35 callers. Particles are world-sized quads now, so the viewport no longer matters. */
@@ -521,7 +536,8 @@ export class VfxInstance {
521
536
  x = p.x;
522
537
  y = p.y;
523
538
  z = p.z;
524
- const v = scratchVec.set(vx, vy, vz).transformDirection(m).multiplyScalar(Math.hypot(vx, vy, vz));
539
+ // The linear part, scale included: an effect placed at 2x throws its particles twice as fast (Godot's emission transform).
540
+ const v = scratchVec.set(vx, vy, vz).applyMatrix3(scratchBasis.setFromMatrix4(m));
525
541
  vx = v.x;
526
542
  vy = v.y;
527
543
  vz = v.z;
@@ -532,6 +548,7 @@ export class VfxInstance {
532
548
  angle: pickRange(c.angle, r()) * DEG, spin: pickRange(c.spin, r()) * DEG, size: pickRange(c.size, r()),
533
549
  r: scratchRgba[0], g: scratchRgba[1], b: scratchRgba[2], a: scratchRgba[3],
534
550
  seed: seedOf(this.document.seed, this.serial++),
551
+ scale: c.space === 'world' ? this.root.matrixWorld.getMaxScaleOnAxis() : 1,
535
552
  radialSpeed: pickRange(c.radialSpeed, r()), radialAccel: pickRange(c.radialAccel, r()),
536
553
  tangentialAccel: pickRange(c.tangentialAccel, r()), orbit: pickRange(c.orbit, r()), damping: pickRange(c.damping, r()),
537
554
  owed: c.children.map(() => 0),
@@ -626,7 +643,7 @@ export class VfxInstance {
626
643
  C[i * 4 + 1] = scratchColor.g * c.intensity;
627
644
  C[i * 4 + 2] = scratchColor.b * c.intensity;
628
645
  C[i * 4 + 3] = Math.min(1, a);
629
- M[i * 4] = p.size * (c.sizeOverLife ? Math.max(0, sampleCurve(c.sizeOverLife, t)) : 1);
646
+ M[i * 4] = p.size * p.scale * (c.sizeOverLife ? Math.max(0, sampleCurve(c.sizeOverLife, t)) : 1);
630
647
  M[i * 4 + 1] = p.angle;
631
648
  L[i * 2] = t;
632
649
  L[i * 2 + 1] = p.seed;
@@ -646,6 +663,22 @@ export class VfxInstance {
646
663
  if (c.space === 'world')
647
664
  l.mesh.matrix.copy(this.root.matrixWorld).invert();
648
665
  }
666
+ if (this.lightLayers.length) {
667
+ this.root.updateWorldMatrix(true, false);
668
+ const k = this.root.matrixWorld.getMaxScaleOnAxis();
669
+ for (const l of this.lightLayers) {
670
+ const c = l.config, t = this.meshLife(c);
671
+ let power = t < 0 ? 0 : c.intensity * (c.intensityOverLife ? Math.max(0, sampleCurve(c.intensityOverLife, t)) : 1);
672
+ if (power > 0 && c.flicker > 0) {
673
+ // Three incommensurate sines: steady-looking randomness, the same on every replay.
674
+ const x = this.time + l.seed * 17, n = Math.sin(x * 23.1) * .5 + Math.sin(x * 37.7) * .3 + Math.sin(x * 61.3) * .2;
675
+ power *= 1 - c.flicker * .5 * (1 + n);
676
+ }
677
+ l.light.intensity = power;
678
+ // A bigger effect lights further.
679
+ l.light.distance = c.range * k;
680
+ }
681
+ }
649
682
  for (const m of this.meshLayers) {
650
683
  const c = m.config, t = this.meshLife(c);
651
684
  const ready = m.images.every((x) => !!x?.image?.width);
@@ -709,9 +742,12 @@ export class VfxInstance {
709
742
  for (const r of m.repeats)
710
743
  r.copy.dispose();
711
744
  }
745
+ for (const l of this.lightLayers)
746
+ l.light.dispose();
712
747
  this.particleLayers = [];
713
748
  this.flipbookLayers = [];
714
749
  this.meshLayers = [];
750
+ this.lightLayers = [];
715
751
  this.byId.clear();
716
752
  this.live = 0;
717
753
  this.root.removeFromParent();
@@ -15,6 +15,8 @@
15
15
  * Version 2. A version-1 document (the upward-firing disc emitter of 1.35) is
16
16
  * still accepted: `parseVfx` upgrades it to the v2 emitter that plays the same.
17
17
  *
18
+ * Version 5 (1.39) adds LIGHTS (`lights`, point lights, ADR-055 step 3).
19
+ *
18
20
  * Version 4 (1.38) adds MESHES: mesh layers (`meshes`) and mesh-shaped
19
21
  * particles (`emitter.mesh`), ADR-055 step 2. A 1.37 reader ignores unknown
20
22
  * top-level fields, so meshes needed their own version to fail loudly there.
@@ -229,7 +231,7 @@ export interface Flipbook {
229
231
  blend: 'normal' | 'additive';
230
232
  }
231
233
  export interface VfxDocument {
232
- version: 2 | 3 | 4;
234
+ version: 2 | 3 | 4 | 5;
233
235
  name: string;
234
236
  seed: number;
235
237
  /** Seconds in one cycle. A looping effect repeats it; a one-shot stops emitting after it. */
@@ -238,8 +240,31 @@ export interface VfxDocument {
238
240
  humanCurated: boolean;
239
241
  emitters: Emitter[];
240
242
  flipbooks?: Flipbook[];
241
- /** (version 3) Meshes with a material: a shockwave ring, a fireball sphere, a ground disc. */
243
+ /** (version 4) Meshes with a material: a shockwave ring, a fireball sphere, a ground disc. */
242
244
  meshes?: MeshLayer[];
245
+ /** (version 5) Point lights: the flash of a muzzle, the glow a fire throws on the ground. At most 2. */
246
+ lights?: LightLayer[];
247
+ }
248
+ /**
249
+ * A point light, created once with the effect and dimmed to 0 when it is off
250
+ * -- adding or removing a light in three.js recompiles every lit material in
251
+ * the scene, which would stall a game on every shot. `intensity` is three.js
252
+ * candela with physical (inverse-square) falloff, cut off at `range`.
253
+ */
254
+ export interface LightLayer {
255
+ id: string;
256
+ enabled: boolean;
257
+ position: Vec3;
258
+ color: string;
259
+ intensity: number;
260
+ range: number;
261
+ /** Seconds into each cycle it comes on, and for how long (null: to the end of the cycle). */
262
+ start: number;
263
+ life: number | null;
264
+ /** Over the light's own life; multiplies `intensity`. */
265
+ intensityOverLife?: Curve;
266
+ /** 0-1: how much it flickers (a fire); 0 = steady. */
267
+ flicker: number;
243
268
  }
244
269
  /** A version-1 emitter: a disc firing upward with linear colour/size/alpha. Read, never written. */
245
270
  export interface EmitterV1 {
@@ -261,6 +286,7 @@ export declare const LIMITS: {
261
286
  readonly emitters: 8;
262
287
  readonly layers: 8;
263
288
  readonly meshes: 8;
289
+ readonly lights: 2;
264
290
  readonly particles: 4000;
265
291
  readonly cells: 4096;
266
292
  readonly bursts: 16;
@@ -350,9 +376,12 @@ export declare function parseVfx(value: unknown): VfxDocument;
350
376
  * emitter uses the material look, else 2. The editor and the agent write
351
377
  * this, so an effect that needs nothing new still plays on 1.36.
352
378
  */
353
- export declare function minimumVersion(d: Pick<VfxDocument, 'emitters' | 'meshes'>): 2 | 3 | 4;
379
+ export declare function minimumVersion(d: Pick<VfxDocument, 'emitters' | 'meshes' | 'lights'>): 2 | 3 | 4 | 5;
354
380
  /** A new mesh layer: a soft additive ring on the ground, for the editor's "Add" and the agent. */
355
381
  export declare function meshLayerDefaults(): Omit<MeshLayer, 'id'>;
382
+ /** A new light: a warm glow just above the origin, lit for the whole cycle. */
383
+ export declare function lightLayerDefaults(): Omit<LightLayer, 'id'>;
384
+ export declare function lightLayer(id: string, patch?: Partial<LightLayer>): LightLayer;
356
385
  export declare function meshLayer(id: string, patch?: Partial<MeshLayer>): MeshLayer;
357
386
  /**
358
387
  * The most particles an effect can have alive at once, estimated: per enabled
@@ -15,6 +15,8 @@
15
15
  * Version 2. A version-1 document (the upward-firing disc emitter of 1.35) is
16
16
  * still accepted: `parseVfx` upgrades it to the v2 emitter that plays the same.
17
17
  *
18
+ * Version 5 (1.39) adds LIGHTS (`lights`, point lights, ADR-055 step 3).
19
+ *
18
20
  * Version 4 (1.38) adds MESHES: mesh layers (`meshes`) and mesh-shaped
19
21
  * particles (`emitter.mesh`), ADR-055 step 2. A 1.37 reader ignores unknown
20
22
  * top-level fields, so meshes needed their own version to fail loudly there.
@@ -25,7 +27,7 @@
25
27
  */
26
28
  import { parseMaterial, materialTextures, materialDefaults } from './material.js';
27
29
  import { parseMeshShape } from './mesh.js';
28
- export const LIMITS = { emitters: 8, layers: 8, meshes: 8, particles: 4000, cells: 4096, bursts: 16, children: 4, curvePoints: 8, gradientStops: 16 };
30
+ export const LIMITS = { emitters: 8, layers: 8, meshes: 8, lights: 2, particles: 4000, cells: 4096, bursts: 16, children: 4, curvePoints: 8, gradientStops: 16 };
29
31
  /** Every emitter field's value when a document leaves it out. */
30
32
  export function emitterDefaults() {
31
33
  return {
@@ -182,8 +184,8 @@ export function parseVfx(value) {
182
184
  const d = structuredClone(value);
183
185
  const number = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
184
186
  const color = (v) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v);
185
- if (d.version !== 2 && d.version !== 3 && d.version !== 4)
186
- fail(`version must be 2, 3 or 4 (or 1, which is upgraded)${typeof d.version === 'number' && d.version > 4 ? ` -- version ${d.version} was written by a newer editor: update @umicat/three-sdk` : ''}`);
187
+ if (![2, 3, 4, 5].includes(d.version))
188
+ fail(`version must be 2, 3, 4 or 5 (or 1, which is upgraded)${typeof d.version === 'number' && d.version > 5 ? ` -- version ${d.version} was written by a newer editor: update @umicat/three-sdk` : ''}`);
187
189
  if (typeof d.name !== 'string' || !d.name.trim() || d.name.length > 80)
188
190
  fail('name must be 1-80 characters');
189
191
  if (!number(d.seed, 1, 2147483646) || !Number.isInteger(d.seed))
@@ -410,6 +412,41 @@ export function parseVfx(value) {
410
412
  const budget = particleBudget(d);
411
413
  if (budget > LIMITS.particles)
412
414
  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}`);
415
+ if (d.lights !== undefined) {
416
+ if (!Array.isArray(d.lights) || d.lights.length > LIMITS.lights)
417
+ fail(`lights must be a list of 0-${LIMITS.lights}`);
418
+ if (d.version < 5)
419
+ fail('lights are version 5: set "version": 5 (needs @umicat/three-sdk 1.39 or later)');
420
+ d.lights = d.lights.map((raw, i) => {
421
+ const at = `lights[${i}]`;
422
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw))
423
+ fail(`${at} is not an object`);
424
+ checkId(raw.id, at);
425
+ const base = lightLayerDefaults();
426
+ for (const k of Object.keys(raw))
427
+ if (!(k in base) && k !== 'id' && k !== 'intensityOverLife')
428
+ fail(`${at}.${k} is not a light field (expected id, ${Object.keys(base).join(', ')}, intensityOverLife)`);
429
+ const l = { ...base, ...raw };
430
+ if (typeof l.enabled !== 'boolean')
431
+ fail(`${at}.enabled must be a boolean`);
432
+ checkVec(l.position, `${at}.position`, -100, 100);
433
+ if (!color(l.color))
434
+ fail(`${at}.color must be #rrggbb`);
435
+ if (!number(l.intensity, 0, 1000))
436
+ fail(`${at}.intensity must be 0-1000 (candela)`);
437
+ if (!number(l.range, .1, 100))
438
+ fail(`${at}.range must be 0.1-100`);
439
+ if (!number(l.start, 0, 60))
440
+ fail(`${at}.start must be 0-60`);
441
+ if (l.life !== null && !number(l.life, .01, 60))
442
+ fail(`${at}.life must be null (to the end of the cycle) or 0.01-60`);
443
+ if (l.intensityOverLife !== undefined)
444
+ checkCurve(l.intensityOverLife, `${at}.intensityOverLife`);
445
+ if (!number(l.flicker, 0, 1))
446
+ fail(`${at}.flicker must be 0-1`);
447
+ return l;
448
+ });
449
+ }
413
450
  if (d.meshes)
414
451
  d.meshes = d.meshes.map((raw, i) => {
415
452
  const at = `meshes[${i}]`;
@@ -483,6 +520,8 @@ export function parseVfx(value) {
483
520
  * this, so an effect that needs nothing new still plays on 1.36.
484
521
  */
485
522
  export function minimumVersion(d) {
523
+ if (d.lights !== undefined)
524
+ return 5;
486
525
  if (d.emitters.some((e) => e.mesh !== undefined || e.sizeOverLifeXYZ !== undefined) || d.meshes !== undefined)
487
526
  return 4;
488
527
  return d.emitters.some((e) => e.look?.type === 'material') ? 3 : 2;
@@ -495,6 +534,11 @@ export function meshLayerDefaults() {
495
534
  material: { ...materialDefaults(), masks: [] },
496
535
  };
497
536
  }
537
+ /** A new light: a warm glow just above the origin, lit for the whole cycle. */
538
+ export function lightLayerDefaults() {
539
+ return { enabled: true, position: [0, .5, 0], color: '#ffb066', intensity: 8, range: 6, start: 0, life: null, flicker: 0 };
540
+ }
541
+ export function lightLayer(id, patch = {}) { return { id, ...lightLayerDefaults(), ...patch }; }
498
542
  export function meshLayer(id, patch = {}) { return { id, ...meshLayerDefaults(), ...patch }; }
499
543
  /**
500
544
  * The most particles an effect can have alive at once, estimated: per enabled
@@ -19,7 +19,10 @@ export declare class VfxEffect {
19
19
  readonly textures: Map<string, T.Texture>;
20
20
  private disposed;
21
21
  constructor(document: VfxDocument, textures: Map<string, T.Texture>);
22
- spawn(): VfxInstance;
22
+ /** `{ lights: false }`: this copy builds no lights (see VfxInstanceOptions). */
23
+ spawn(options?: {
24
+ lights?: boolean;
25
+ }): VfxInstance;
23
26
  /** Frees the shared textures. Dispose the spawned instances first. */
24
27
  dispose(): void;
25
28
  }
package/dist/vfx/load.js CHANGED
@@ -18,10 +18,11 @@ export class VfxEffect {
18
18
  this.textures = textures;
19
19
  this.disposed = false;
20
20
  }
21
- spawn() {
21
+ /** `{ lights: false }`: this copy builds no lights (see VfxInstanceOptions). */
22
+ spawn(options = {}) {
22
23
  if (this.disposed)
23
24
  throw new Error(`VfxEffect "${this.document.name}" was disposed`);
24
- return new VfxInstance(this.document, { textures: this.textures });
25
+ return new VfxInstance(this.document, { textures: this.textures, lights: options.lights });
25
26
  }
26
27
  /** Frees the shared textures. Dispose the spawned instances first. */
27
28
  dispose() { this.disposed = true; for (const t of this.textures.values())
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.38.0",
3
+ "version": "1.39.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",