@umicat/three-sdk 1.40.0 → 1.41.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
@@ -73,6 +73,7 @@ const fire = await loadVfx('uploaded/campfire.vfx.json'); // + every image it na
73
73
  const fx = fire.spawn(); // many copies share the images
74
74
  scene.add(fx.root);
75
75
  // each frame: fx.update(dt); one-shot: if (fx.finished) fx.dispose();
76
+ // a looping effect (a status aura): fx.stop() when it should end -- it drains, then fx.finished
76
77
  ```
77
78
 
78
79
  An effect has two kinds of layer. **Emitters** are particle systems modelled
@@ -126,6 +127,12 @@ shader (no camera needed). u runs from the particle (0) to the tail end (1);
126
127
  without a material the trail takes the particle's colour and fades out. At
127
128
  most 8000 trail points per effect, checked at parse.
128
129
 
130
+ **`stop()` (1.41.0, ADR-056).** Ends an effect the way it was meant to end:
131
+ emission stops, particles alive finish their lives, a looping sprite sheet
132
+ finishes its cycle, a mesh layer or light with a window plays it out and a
133
+ whole-cycle one goes out; then `finished` turns true. Works on every format
134
+ version, which is how a game ends a looping effect.
135
+
129
136
  **Write the lowest version.** `minimumVersion(doc)` is 6 with trails, 5 with lights, 4 with meshes, 3 with a
130
137
  material, else 2; the editor and the agent write that, so an effect that needs nothing
131
138
  new stays version 2 and keeps playing on 1.36.
@@ -33,6 +33,8 @@ export declare class VfxInstance {
33
33
  private meshLayers;
34
34
  private lightLayers;
35
35
  private state;
36
+ /** Effect time when `stop()` was called, or null. */
37
+ private stoppedAt;
36
38
  /** Particles born so far: hashed into each particle's `seed`. */
37
39
  private serial;
38
40
  private accumulator;
@@ -48,6 +50,17 @@ export declare class VfxInstance {
48
50
  private buildFlipbook;
49
51
  private random;
50
52
  /** Back to time 0 with the original seed: a replay is identical to the first play. */
53
+ /**
54
+ * End the effect the way it was meant to end (ADR-056): emission stops,
55
+ * particles already alive finish their lives, a looping sprite sheet
56
+ * finishes its cycle, a mesh layer or light with a window plays it out, and
57
+ * whole-cycle ones go out. `finished` turns true once all of that is done --
58
+ * so a looping status effect can be ended and then disposed. Works on every
59
+ * format version; `reset()` undoes it.
60
+ */
61
+ stop(): void;
62
+ /** True after `stop()`, until `reset()`. */
63
+ get stopped(): boolean;
51
64
  reset(): void;
52
65
  get particleCount(): number;
53
66
  /** The point lights this instance made (empty with `{ lights: false }`). Never changes after construction. */
@@ -169,6 +169,8 @@ export class VfxInstance {
169
169
  this.meshLayers = [];
170
170
  this.lightLayers = [];
171
171
  this.state = 1;
172
+ /** Effect time when `stop()` was called, or null. */
173
+ this.stoppedAt = null;
172
174
  /** Particles born so far: hashed into each particle's `seed`. */
173
175
  this.serial = 0;
174
176
  this.accumulator = 0;
@@ -316,6 +318,20 @@ export class VfxInstance {
316
318
  if (!c.enabled)
317
319
  return -1;
318
320
  const d = this.document.duration, life = c.life ?? Math.max(.01, d - c.start);
321
+ if (this.stoppedAt !== null) {
322
+ // Stopped: a whole-cycle layer goes out; a window that had begun plays out; nothing new begins.
323
+ if (c.life === null)
324
+ return -1;
325
+ const base = this.document.loop ? Math.floor(this.stoppedAt / d) * d : 0;
326
+ for (const begin of [base + c.start, base - d + c.start]) {
327
+ if (begin > this.stoppedAt || (begin < 0))
328
+ continue;
329
+ const t = (this.time - begin) / life;
330
+ if (t >= 0 && t < 1)
331
+ return t;
332
+ }
333
+ return -1;
334
+ }
319
335
  const cycleTime = this.document.loop ? this.time % d : this.time;
320
336
  let t = (cycleTime - c.start) / life;
321
337
  // A looping layer that outlives its cycle carries over into the next one.
@@ -343,7 +359,20 @@ export class VfxInstance {
343
359
  }
344
360
  random() { this.state = this.state * 16807 % 2147483647; return (this.state - 1) / 2147483646; }
345
361
  /** Back to time 0 with the original seed: a replay is identical to the first play. */
362
+ /**
363
+ * End the effect the way it was meant to end (ADR-056): emission stops,
364
+ * particles already alive finish their lives, a looping sprite sheet
365
+ * finishes its cycle, a mesh layer or light with a window plays it out, and
366
+ * whole-cycle ones go out. `finished` turns true once all of that is done --
367
+ * so a looping status effect can be ended and then disposed. Works on every
368
+ * format version; `reset()` undoes it.
369
+ */
370
+ stop() { if (this.stoppedAt === null)
371
+ this.stoppedAt = this.time; }
372
+ /** True after `stop()`, until `reset()`. */
373
+ get stopped() { return this.stoppedAt !== null; }
346
374
  reset() {
375
+ this.stoppedAt = null;
347
376
  this.time = 0;
348
377
  this.accumulator = 0;
349
378
  this.state = this.document.seed;
@@ -366,6 +395,11 @@ export class VfxInstance {
366
395
  * died and every flipbook has played out -- the moment to `dispose()` a
367
396
  * one-shot. Always false for a looping effect. */
368
397
  get finished() {
398
+ if (this.stoppedAt !== null) {
399
+ // After stop(): no layer begins again, so done = nothing showing now.
400
+ const quiet = this.meshLayers.every(({ config }) => this.meshLife(config) < 0) && this.lightLayers.every(({ config }) => this.meshLife(config) < 0);
401
+ return this.live === 0 && quiet && this.flipbookLayers.every((f) => f.done);
402
+ }
369
403
  if (this.document.loop || this.time < this.document.duration)
370
404
  return false;
371
405
  const over = (c) => !c.enabled || this.time >= c.start + (c.life ?? Math.max(.01, this.document.duration - c.start));
@@ -386,7 +420,7 @@ export class VfxInstance {
386
420
  this.draw();
387
421
  }
388
422
  /** Whether the effect is still starting new particles / new flipbook cycles. */
389
- get running() { return this.document.loop || this.time < this.document.duration; }
423
+ get running() { return this.stoppedAt === null && (this.document.loop || this.time < this.document.duration); }
390
424
  /** The emitter's origin in its own simulation space. */
391
425
  origin(layer, out) {
392
426
  if (layer.config.space === 'world')
@@ -670,7 +704,8 @@ export class VfxInstance {
670
704
  if (this.running)
671
705
  return n % f.frames;
672
706
  // Stopped: the cycle that was playing when the effect stopped may finish.
673
- const stoppedAt = Math.floor(Math.max(0, this.document.duration - f.delay) * f.fps);
707
+ const end = this.document.loop ? (this.stoppedAt ?? this.document.duration) : Math.min(this.stoppedAt ?? Infinity, this.document.duration);
708
+ const stoppedAt = Math.floor(Math.max(0, end - f.delay) * f.fps);
674
709
  const cycleEnd = (Math.floor(stoppedAt / f.frames) + 1) * f.frames;
675
710
  return n < cycleEnd ? n % f.frames : -1;
676
711
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.40.0",
3
+ "version": "1.41.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",