@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.
- package/README.md +19 -9
- package/dist/vfx/VfxInstance.d.ts +26 -8
- package/dist/vfx/VfxInstance.js +447 -60
- package/dist/vfx/document.d.ts +247 -19
- package/dist/vfx/document.js +351 -24
- package/dist/vfx/templates.js +9 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -61,7 +61,7 @@ guide**, which nothing here points at.
|
|
|
61
61
|
your game gameplay
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
## Effects — `@umicat/three-sdk/vfx` (1.
|
|
64
|
+
## Effects — `@umicat/three-sdk/vfx` (format v2 since 1.36.0)
|
|
65
65
|
|
|
66
66
|
Plays `.vfx.json` effects made in the VFX Editor. A separate entry point that
|
|
67
67
|
imports `three` and nothing else, so the editor and any game can use it
|
|
@@ -69,18 +69,28 @@ without the physics or platform layers.
|
|
|
69
69
|
|
|
70
70
|
```ts
|
|
71
71
|
import { loadVfx } from '@umicat/three-sdk/vfx';
|
|
72
|
-
const fire = await loadVfx('uploaded/campfire.vfx.json'); // + every
|
|
73
|
-
const fx = fire.spawn(); // many copies share the
|
|
72
|
+
const fire = await loadVfx('uploaded/campfire.vfx.json'); // + every image it names
|
|
73
|
+
const fx = fire.spawn(); // many copies share the images
|
|
74
74
|
scene.add(fx.root);
|
|
75
|
-
fx.setViewportHeight(renderer.domElement.height); // particle sizes are pixels
|
|
76
75
|
// each frame: fx.update(dt); one-shot: if (fx.finished) fx.dispose();
|
|
77
76
|
```
|
|
78
77
|
|
|
79
|
-
An effect has two kinds of layer
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
78
|
+
An effect has two kinds of layer. **Emitters** are particle systems modelled
|
|
79
|
+
on Godot's `ParticleProcessMaterial` (umicat-design ADR-054): an emission
|
|
80
|
+
shape (point, sphere, box, ring), a direction cone, random ranges, gravity /
|
|
81
|
+
damping / radial / tangential / orbit motion, curves and gradients over each
|
|
82
|
+
particle's life, a look (soft dot, glow, star, an image or a sprite sheet)
|
|
83
|
+
facing the camera, stretched along its motion or flat on the ground, bursts,
|
|
84
|
+
and sub-emitters. Simulation is seeded, fixed-step and on the CPU; each layer
|
|
85
|
+
draws as one instanced quad mesh. **Flipbooks** are a sprite sheet played
|
|
86
|
+
frame by frame on one quad. Images are named by bare filename; `loadVfx`
|
|
87
|
+
resolves them beside the effect file and rejects, naming the image, if one
|
|
88
|
+
cannot load.
|
|
89
|
+
|
|
90
|
+
`parseVfx` accepts version-1 documents (1.35's upward-firing disc) and
|
|
91
|
+
upgrades them to the v2 emitter that plays the same, and fills every emitter
|
|
92
|
+
field a document leaves out from `emitterDefaults()`. The editor and the agent
|
|
93
|
+
always write version 2, which **needs 1.36.0 to play**.
|
|
84
94
|
|
|
85
95
|
## What is proven, and by what
|
|
86
96
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import * as T from 'three';
|
|
2
|
-
import { type VfxDocument } from './document.js';
|
|
3
|
-
/** Where a flipbook's sheet comes from. A
|
|
4
|
-
*
|
|
5
|
-
* nothing rather than failing the whole effect. */
|
|
2
|
+
import { type VfxDocument, type Vec3 } from './document.js';
|
|
3
|
+
/** Where a texture (a flipbook's sheet, a particle's image) comes from. A
|
|
4
|
+
* Map / record keyed by the document's filename, or a function. A layer
|
|
5
|
+
* whose texture is missing draws nothing rather than failing the whole effect. */
|
|
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;
|
|
@@ -12,8 +12,9 @@ export interface VfxInstanceOptions {
|
|
|
12
12
|
* no renderer, no DOM and no animation loop -- add `root` to a scene and call
|
|
13
13
|
* `update(seconds)` from your own frame loop.
|
|
14
14
|
*
|
|
15
|
-
* Simulation is fixed-step (1/60 s) and
|
|
16
|
-
* same way at any frame rate, and `reset()` replays it
|
|
15
|
+
* Simulation is fixed-step (1/60 s), seeded and on the CPU, so the same
|
|
16
|
+
* document plays the same way at any frame rate, and `reset()` replays it
|
|
17
|
+
* exactly. Each particle layer draws as one instanced quad mesh.
|
|
17
18
|
*/
|
|
18
19
|
export declare class VfxInstance {
|
|
19
20
|
readonly root: T.Group<T.Object3DEventMap>;
|
|
@@ -21,11 +22,15 @@ export declare class VfxInstance {
|
|
|
21
22
|
/** Seconds of simulated time since start (or the last reset). */
|
|
22
23
|
time: number;
|
|
23
24
|
private particleLayers;
|
|
25
|
+
private byId;
|
|
24
26
|
private flipbookLayers;
|
|
25
27
|
private state;
|
|
26
28
|
private accumulator;
|
|
29
|
+
private live;
|
|
27
30
|
constructor(document: VfxDocument, options?: VfxInstanceOptions);
|
|
28
31
|
private buildParticles;
|
|
32
|
+
/** (Re)creates the per-instance buffers with room for `capacity` particles. */
|
|
33
|
+
private allocate;
|
|
29
34
|
private buildFlipbook;
|
|
30
35
|
private random;
|
|
31
36
|
/** Back to time 0 with the original seed: a replay is identical to the first play. */
|
|
@@ -35,13 +40,19 @@ export declare class VfxInstance {
|
|
|
35
40
|
* died and every flipbook has played out -- the moment to `dispose()` a
|
|
36
41
|
* one-shot. Always false for a looping effect. */
|
|
37
42
|
get finished(): boolean;
|
|
38
|
-
/**
|
|
39
|
-
setViewportHeight(
|
|
43
|
+
/** Kept for 1.35 callers. Particles are world-sized quads now, so the viewport no longer matters. */
|
|
44
|
+
setViewportHeight(_height: number): void;
|
|
40
45
|
/** Advance by `delta` seconds. Gaps over 250 ms are capped, so a backgrounded tab does not dump a burst. */
|
|
41
46
|
update(delta: number): void;
|
|
42
47
|
/** Whether the effect is still starting new particles / new flipbook cycles. */
|
|
43
48
|
private get running();
|
|
49
|
+
/** The emitter's origin in its own simulation space. */
|
|
50
|
+
private origin;
|
|
44
51
|
private step;
|
|
52
|
+
private move;
|
|
53
|
+
/** A new particle on `layer`, from its own emission shape -- around a parent particle when `at` is given. */
|
|
54
|
+
private spawn;
|
|
55
|
+
private spawnChildren;
|
|
45
56
|
/** The frame a flipbook shows now, or -1 for none. A looping flipbook keeps
|
|
46
57
|
* cycling while the effect runs and, once it stops, finishes its current
|
|
47
58
|
* cycle -- the flipbook counterpart of particles draining. */
|
|
@@ -51,3 +62,10 @@ export declare class VfxInstance {
|
|
|
51
62
|
* shared between instances and belong to whoever loaded them (`VfxEffect`). */
|
|
52
63
|
dispose(): void;
|
|
53
64
|
}
|
|
65
|
+
/**
|
|
66
|
+
* A random direction inside the cone around `direction` with half-angle
|
|
67
|
+
* `spread` (radians), following Godot's ParticleProcessMaterial: one angle in
|
|
68
|
+
* the cone's first plane, a second one scaled down by `flatness`, so
|
|
69
|
+
* flatness 1 is a flat fan.
|
|
70
|
+
*/
|
|
71
|
+
export declare function coneDirection(direction: Vec3, spread: number, flatness: number, u1: number, u2: number): Vec3;
|