@umicat/three-sdk 1.34.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.
@@ -0,0 +1,332 @@
1
+ /**
2
+ * The `.vfx.json` effect document: what the VFX Editor writes, what the agent
3
+ * writes, and what a game plays. Two kinds of layer:
4
+ *
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.
10
+ * - `flipbooks`: a sprite sheet played frame by frame on one quad -- an
11
+ * explosion, a muzzle flash, a slash. The sheet is an IMAGE ASSET next to the
12
+ * effect, named by `texture`; the grid is `cols` x `rows`, read left to
13
+ * right, top to bottom, and the first `frames` cells are played.
14
+ *
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
+ /** 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
+ }
102
+ export interface Emitter {
103
+ id: string;
104
+ enabled: boolean;
105
+ /** Particles a second while the emitter runs; 0 for bursts only. */
106
+ rate: 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;
127
+ spread: number;
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;
171
+ blend: 'normal' | 'additive';
172
+ children: SubEmitter[];
173
+ }
174
+ export interface Flipbook {
175
+ id: string;
176
+ enabled: boolean;
177
+ /** Filename of an image asset (png / webp / jpg) in the same folder as the effect. */
178
+ texture: string;
179
+ cols: number;
180
+ rows: number;
181
+ frames: number;
182
+ fps: number;
183
+ /** Repeat while the effect is running; otherwise play once. */
184
+ loop: boolean;
185
+ /** Seconds after the effect starts before the first frame shows. */
186
+ delay: number;
187
+ /** World WIDTH of one cell; the height follows the cell's own aspect. */
188
+ size: number;
189
+ /** Where the effect's origin sits inside the cell: 0..1 from the cell's LEFT and TOP edge. */
190
+ originU: number;
191
+ originV: number;
192
+ /** `camera`: a billboard that always faces the viewer. `ground`: lies flat (an area ring, a scorch mark). */
193
+ facing: 'camera' | 'ground';
194
+ opacity: number;
195
+ /** Multiplied with the sheet's colours; #ffffff leaves them unchanged. */
196
+ color: string;
197
+ blend: 'normal' | 'additive';
198
+ }
199
+ export interface VfxDocument {
200
+ version: 2;
201
+ name: string;
202
+ seed: number;
203
+ /** Seconds in one cycle. A looping effect repeats it; a one-shot stops emitting after it. */
204
+ duration: number;
205
+ loop: boolean;
206
+ humanCurated: boolean;
207
+ emitters: Emitter[];
208
+ flipbooks?: Flipbook[];
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
+ }
226
+ export declare const LIMITS: {
227
+ readonly emitters: 8;
228
+ readonly layers: 8;
229
+ readonly particles: 4000;
230
+ readonly cells: 4096;
231
+ readonly bursts: 16;
232
+ readonly children: 4;
233
+ readonly curvePoints: 8;
234
+ readonly gradientStops: 16;
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;
240
+ export declare function campfire(): VfxDocument;
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;
257
+ /** Per-flipbook numeric fields and their allowed ranges. `frames` is further capped at cols x rows. */
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]];
259
+ /** A bare filename with an image extension: no folders, so it can only name a sibling of the effect. */
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"];
293
+ /** A new flipbook layer with sensible defaults, for the editor's "Add" and for the agent. */
294
+ export declare function flipbookLayer(id: string, texture: string): Flipbook;
295
+ /** Every texture filename a document needs (flipbook sheets and particle images), once each. */
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[];
304
+ /**
305
+ * Reject malformed/unsupported resources instead of silently rewriting them.
306
+ * The message names the field and its allowed range: the agent writes these
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()`.
311
+ */
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;
319
+ /** An effect is a project ASSET named `<stem>.vfx.json`; the server keeps the
320
+ * whole compound extension, so this suffix is what marks one. */
321
+ export declare const VFX_SUFFIX = ".vfx.json";
322
+ export declare function isVfxFilename(filename: string): boolean;
323
+ /**
324
+ * A filename for a NEW effect, shaped the way the server's sanitizer will keep
325
+ * it (lowercase ASCII letters, digits, `-` and `_`) and free in this project.
326
+ *
327
+ * It has to be free client-side: an upload whose name the project already
328
+ * holds REPLACES that file -- that is the intended behaviour for re-uploading
329
+ * your own asset, and silent data loss for "New effect" twice in a row.
330
+ * A name with no ASCII in it (any CJK name) becomes `effect`.
331
+ */
332
+ export declare function vfxFilename(name: string, taken: Iterable<string>): string;