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