@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.
@@ -2,31 +2,174 @@
2
2
  * The `.vfx.json` effect document: what the VFX Editor writes, what the agent
3
3
  * writes, and what a game plays. Two kinds of layer:
4
4
  *
5
- * - `emitters`: CPU-simulated point particles. Particles start on a small disc
6
- * at the origin and fire UPWARD; `spread` is horizontal jitter and `gravity`
7
- * a vertical acceleration (positive rises, negative falls).
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.
8
10
  * - `flipbooks`: a sprite sheet played frame by frame on one quad -- an
9
11
  * explosion, a muzzle flash, a slash. The sheet is an IMAGE ASSET next to the
10
12
  * effect, named by `texture`; the grid is `cols` x `rows`, read left to
11
13
  * right, top to bottom, and the first `frames` cells are played.
12
14
  *
13
- * `flipbooks` is optional, so every document written before it existed is
14
- * still valid unchanged.
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.
15
17
  */
18
+ /** A number, or `[min, max]`: picked uniformly per particle. */
19
+ export type Range = number | [number, number];
20
+ export type Vec3 = [number, number, number];
21
+ /**
22
+ * A value over a particle's life (t = 0 at birth, 1 at death): 1-8 points
23
+ * `[t, value]` with increasing t. Straight lines between points, or a monotone
24
+ * cubic when `smooth`. Before the first point and after the last the value is
25
+ * held.
26
+ */
27
+ export interface Curve {
28
+ points: [number, number][];
29
+ smooth?: boolean;
30
+ }
31
+ /** 1-16 stops `[t, "#rrggbb", alpha]` with increasing t; linear in between. */
32
+ export interface Gradient {
33
+ stops: [number, string, number][];
34
+ }
35
+ export type EmissionShape = {
36
+ type: 'point';
37
+ }
38
+ /** Inside a sphere (denser towards the middle, as Godot), or on its surface. */
39
+ | {
40
+ type: 'sphere';
41
+ radius: number;
42
+ surface: boolean;
43
+ }
44
+ /** `extents` are HALF sizes, as Godot's emission_box_extents. */
45
+ | {
46
+ type: 'box';
47
+ extents: Vec3;
48
+ }
49
+ /** A flat ring (or a disc when `inner` is 0) around `axis`; `height` thickens it into a tube. */
50
+ | {
51
+ type: 'ring';
52
+ radius: number;
53
+ inner: number;
54
+ height: number;
55
+ axis: Vec3;
56
+ };
57
+ export type ParticleLook =
58
+ /** A round soft dot. softness 0 is a hard disc, 0.5 the classic falloff, 1 very soft. */
59
+ {
60
+ type: 'dot';
61
+ softness: number;
62
+ }
63
+ /** A bright core with a long soft halo. */
64
+ | {
65
+ type: 'glow';
66
+ }
67
+ /** A star with `points` arms; sharpness 0 is nearly round, 1 thin spikes. */
68
+ | {
69
+ type: 'star';
70
+ points: number;
71
+ sharpness: number;
72
+ }
73
+ /** An image asset next to the effect, tinted by the particle colour. */
74
+ | {
75
+ type: 'texture';
76
+ texture: string;
77
+ }
78
+ /** A sprite sheet: `fps` frames a second from each particle's birth, or `life` to play it once across the particle's life. */
79
+ | {
80
+ type: 'sheet';
81
+ texture: string;
82
+ cols: number;
83
+ rows: number;
84
+ frames: number;
85
+ fps: number | 'life';
86
+ };
87
+ export interface Burst {
88
+ time: number;
89
+ count: number;
90
+ over: number;
91
+ }
92
+ export interface SubEmitter {
93
+ /** The id of another emitter. It then emits ONLY from this one's particles. */
94
+ emitter: string;
95
+ /** birth / death: `count` particles at that moment. life: `rate` a second while the particle lives. */
96
+ when: 'birth' | 'life' | 'death';
97
+ count: number;
98
+ rate: number;
99
+ /** Children start with the parent particle's velocity added to their own. */
100
+ inheritVelocity: boolean;
101
+ }
16
102
  export interface Emitter {
17
103
  id: string;
18
104
  enabled: boolean;
105
+ /** Particles a second while the emitter runs; 0 for bursts only. */
19
106
  rate: number;
20
- lifetime: number;
21
- speed: number;
107
+ /** At `time` seconds into each cycle, `count` particles, spread over `over` seconds (0 = at once). */
108
+ bursts: Burst[];
109
+ /** The window of each cycle in which `rate` emits; `stop` null means to the end. */
110
+ start: number;
111
+ stop: number | null;
112
+ lifetime: Range;
113
+ /** local: particles move with the effect. world: they stay where they were born when the effect moves. */
114
+ space: 'local' | 'world';
115
+ shape: EmissionShape;
116
+ shapeOffset: Vec3;
117
+ shapeScale: Vec3;
118
+ /**
119
+ * The emitter's own orientation, XYZ Euler degrees (Godot rotates the
120
+ * GPUParticles3D node): turns its shape, offset, direction and random
121
+ * velocity, and the plane a `ground`-facing particle lies in. Gravity stays
122
+ * in world axes.
123
+ */
124
+ rotation: Vec3;
125
+ /** The cone's axis; `spread` is its half-angle in degrees (180 = every way). */
126
+ direction: Vec3;
22
127
  spread: number;
23
- gravity: number;
24
- size: number;
25
- endSize: number;
26
- opacity: number;
27
- color: string;
28
- endColor: string;
128
+ /** 0-1: flattens the cone towards a fan (Godot `flatness`). */
129
+ flatness: number;
130
+ speed: Range;
131
+ /** Extra per-axis velocity, uniform in +-value. */
132
+ randomVelocity: Vec3;
133
+ gravity: Vec3;
134
+ /** Away from the emitter's origin, metres a second (negative = inwards). Moves the particle without building up velocity. */
135
+ radialSpeed: Range;
136
+ radialAccel: Range;
137
+ /** Around the Y axis through the origin. */
138
+ tangentialAccel: Range;
139
+ /** Turns a second around the Y axis through the origin. */
140
+ orbit: Range;
141
+ /** Speed lost per second. */
142
+ damping: Range;
143
+ /** Maximum speed over life. */
144
+ speedLimit?: Curve;
145
+ radialAccelOverLife?: Curve;
146
+ orbitOverLife?: Curve;
147
+ /** Degrees, and degrees a second. */
148
+ angle: Range;
149
+ spin: Range;
150
+ /** World width of one particle. */
151
+ size: Range;
152
+ sizeOverLife?: Curve;
153
+ /** One stop: that colour. More: each particle picks a point on it at random. */
154
+ color: Gradient;
155
+ /** Multiplies `color` over life. */
156
+ colorOverLife?: Gradient;
157
+ alphaOverLife?: Curve;
158
+ /** Brightness multiplier; above 1 is HDR (glows under bloom). */
159
+ intensity: number;
160
+ look: ParticleLook;
161
+ /**
162
+ * camera: faces the viewer. velocity: the image's up runs along the
163
+ * particle's 3D motion and foreshortens with it (sparks, streaks). axis: the
164
+ * same, along the emitter's own direction (turned by `rotation`) -- a flame
165
+ * or beam that stays pinned to a barrel. ground: lies flat in the emitter's
166
+ * XZ plane. `angle` turns the image inside the quad in every mode.
167
+ */
168
+ align: 'camera' | 'velocity' | 'ground' | 'axis';
169
+ /** With align `velocity`: extra length per metre-a-second of speed. */
170
+ stretch: number;
29
171
  blend: 'normal' | 'additive';
172
+ children: SubEmitter[];
30
173
  }
31
174
  export interface Flipbook {
32
175
  id: string;
@@ -54,40 +197,125 @@ export interface Flipbook {
54
197
  blend: 'normal' | 'additive';
55
198
  }
56
199
  export interface VfxDocument {
57
- version: 1;
200
+ version: 2;
58
201
  name: string;
59
202
  seed: number;
203
+ /** Seconds in one cycle. A looping effect repeats it; a one-shot stops emitting after it. */
60
204
  duration: number;
61
205
  loop: boolean;
62
206
  humanCurated: boolean;
63
207
  emitters: Emitter[];
64
208
  flipbooks?: Flipbook[];
65
209
  }
210
+ /** A version-1 emitter: a disc firing upward with linear colour/size/alpha. Read, never written. */
211
+ export interface EmitterV1 {
212
+ id: string;
213
+ enabled: boolean;
214
+ rate: number;
215
+ lifetime: number;
216
+ speed: number;
217
+ spread: number;
218
+ gravity: number;
219
+ size: number;
220
+ endSize: number;
221
+ opacity: number;
222
+ color: string;
223
+ endColor: string;
224
+ blend: 'normal' | 'additive';
225
+ }
66
226
  export declare const LIMITS: {
67
- readonly rate: 300;
68
- readonly lifetime: 10;
69
227
  readonly emitters: 8;
70
228
  readonly layers: 8;
71
229
  readonly particles: 4000;
72
230
  readonly cells: 4096;
231
+ readonly bursts: 16;
232
+ readonly children: 4;
233
+ readonly curvePoints: 8;
234
+ readonly gradientStops: 16;
73
235
  };
236
+ /** Every emitter field's value when a document leaves it out. */
237
+ export declare function emitterDefaults(): Omit<Emitter, 'id'>;
238
+ /** A new particle layer: the defaults, plus a fade-out so it reads as particles at once. */
239
+ export declare function emitterLayer(id: string, patch?: Partial<Emitter>): Emitter;
74
240
  export declare function campfire(): VfxDocument;
75
- /** Per-emitter numeric fields and their allowed ranges (shared with the editor's inputs). */
76
- export declare const EMITTER_RANGES: readonly [readonly ["rate", 0, 300], readonly ["lifetime", 0.1, 10], readonly ["speed", 0, 10], readonly ["spread", 0, 5], readonly ["gravity", -10, 10], readonly ["size", 0.001, 5], readonly ["endSize", 0.001, 5], readonly ["opacity", 0, 1]];
241
+ /**
242
+ * A version-1 document as the v2 document that plays the same: same spawn
243
+ * disc, speeds, jitter, gravity, colour, size and alpha over life. (Not
244
+ * bit-identical -- random numbers are drawn in a different order -- but the
245
+ * same effect.) v1 `size` was a point RADIUS; v2 `size` is the width.
246
+ */
247
+ export declare function upgradeV1(v1: {
248
+ version: 1;
249
+ name: string;
250
+ seed: number;
251
+ duration: number;
252
+ loop: boolean;
253
+ humanCurated: boolean;
254
+ emitters: EmitterV1[];
255
+ flipbooks?: Flipbook[];
256
+ }): VfxDocument;
77
257
  /** Per-flipbook numeric fields and their allowed ranges. `frames` is further capped at cols x rows. */
78
258
  export declare const FLIPBOOK_RANGES: readonly [readonly ["cols", 1, 64], readonly ["rows", 1, 64], readonly ["frames", 1, 4096], readonly ["fps", 1, 120], readonly ["delay", 0, 60], readonly ["size", 0.01, 50], readonly ["originU", 0, 1], readonly ["originV", 0, 1], readonly ["opacity", 0, 1]];
79
259
  /** A bare filename with an image extension: no folders, so it can only name a sibling of the effect. */
80
260
  export declare const TEXTURE_PATTERN: RegExp;
261
+ /** Numeric emitter fields that take a `Range`, with their allowed bounds. Shared with the editor's inputs. */
262
+ export declare const EMITTER_RANGES: {
263
+ readonly lifetime: readonly [0.01, 30];
264
+ readonly speed: readonly [-1000, 1000];
265
+ readonly radialSpeed: readonly [-100, 100];
266
+ readonly radialAccel: readonly [-1000, 1000];
267
+ readonly tangentialAccel: readonly [-1000, 1000];
268
+ readonly orbit: readonly [-100, 100];
269
+ readonly damping: readonly [0, 1000];
270
+ readonly angle: readonly [-3600, 3600];
271
+ readonly spin: readonly [-36000, 36000];
272
+ readonly size: readonly [0, 100];
273
+ };
274
+ /** Plain numeric emitter fields and their bounds. */
275
+ export declare const EMITTER_NUMBERS: {
276
+ readonly rate: readonly [0, 1000];
277
+ readonly start: readonly [0, 60];
278
+ readonly spread: readonly [0, 180];
279
+ readonly flatness: readonly [0, 1];
280
+ readonly intensity: readonly [0, 16];
281
+ readonly stretch: readonly [0, 10];
282
+ };
283
+ /** Vector emitter fields and the bound on each component. */
284
+ export declare const EMITTER_VECTORS: {
285
+ readonly shapeOffset: readonly [-100, 100];
286
+ readonly shapeScale: readonly [-100, 100];
287
+ readonly rotation: readonly [-360, 360];
288
+ readonly direction: readonly [-1000, 1000];
289
+ readonly randomVelocity: readonly [0, 100];
290
+ readonly gravity: readonly [-100, 100];
291
+ };
292
+ export declare const CURVE_FIELDS: readonly ["speedLimit", "radialAccelOverLife", "orbitOverLife", "sizeOverLife", "alphaOverLife"];
81
293
  /** A new flipbook layer with sensible defaults, for the editor's "Add" and for the agent. */
82
294
  export declare function flipbookLayer(id: string, texture: string): Flipbook;
83
- /** Every texture filename a document needs, once each. */
295
+ /** Every texture filename a document needs (flipbook sheets and particle images), once each. */
84
296
  export declare function vfxTextures(document: VfxDocument): string[];
297
+ /** The value of a Range for one random number u in [0, 1). */
298
+ export declare function pickRange(r: Range, u: number): number;
299
+ export declare function rangeMax(r: Range): number;
300
+ /** Curve value at t (0..1). Monotone cubic (Fritsch-Carlson) when `smooth`, so it never overshoots its points. */
301
+ export declare function sampleCurve(c: Curve, t: number): number;
302
+ /** Gradient at t, written into out as [r, g, b, a] (sRGB components 0..1). */
303
+ export declare function sampleGradient(g: Gradient, t: number, out?: number[]): number[];
85
304
  /**
86
305
  * Reject malformed/unsupported resources instead of silently rewriting them.
87
306
  * The message names the field and its allowed range: the agent writes these
88
307
  * documents by hand, and "Invalid VFX resource" gave it nothing to fix.
308
+ *
309
+ * Returns a COMPLETE copy: a version-1 document is upgraded, and emitter
310
+ * fields left out take `emitterDefaults()`.
89
311
  */
90
312
  export declare function parseVfx(value: unknown): VfxDocument;
313
+ /**
314
+ * The most particles an effect can have alive at once, estimated: per enabled
315
+ * emitter, rate x longest life plus every burst, and for sub-emitters, the
316
+ * parent's count times what each parent particle spawns.
317
+ */
318
+ export declare function particleBudget(d: VfxDocument): number;
91
319
  /** An effect is a project ASSET named `<stem>.vfx.json`; the server keeps the
92
320
  * whole compound extension, so this suffix is what marks one. */
93
321
  export declare const VFX_SUFFIX = ".vfx.json";