@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 +7 -0
- package/dist/vfx/VfxInstance.d.ts +13 -0
- package/dist/vfx/VfxInstance.js +37 -2
- package/package.json +1 -1
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. */
|
package/dist/vfx/VfxInstance.js
CHANGED
|
@@ -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
|
|
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.
|
|
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",
|