@ignifx/particles 0.0.0-stage → 0.3.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/dist/index.d.ts +2173 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +6179 -0
- package/dist/index.js.map +1 -0
- package/package.json +68 -4
- package/skills/particles/SKILL.md +367 -0
- package/README.md +0 -3
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,2173 @@
|
|
|
1
|
+
import { App, AssetHandle, AssetLoader, ColorLike, Component, ComponentHooks, CurveValue, DiagnosticsGroup, ErrorContext, Extension, IgnifxError, InstancedMeshRenderer, MaterialAsset, MeshAsset, Schema, SchemaDescription, ShaderAsset, ShaderMaterialDefinition, Signal, StorageBufferAsset, System, SystemContext, TextureAsset, Vec2Like, Vec3Like } from "@ignifx/core";
|
|
2
|
+
//#region src/definition/types.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* The `format` discriminator every `.particles.json` document carries.
|
|
5
|
+
*
|
|
6
|
+
* @public
|
|
7
|
+
*/
|
|
8
|
+
export declare const PARTICLES_FORMAT = "ignifx.particles";
|
|
9
|
+
/**
|
|
10
|
+
* The document version this build reads and writes.
|
|
11
|
+
*
|
|
12
|
+
* @public
|
|
13
|
+
*/
|
|
14
|
+
export declare const PARTICLES_FORMAT_VERSION = 1;
|
|
15
|
+
/**
|
|
16
|
+
* The asset type name the loader registers.
|
|
17
|
+
*
|
|
18
|
+
* @public
|
|
19
|
+
*/
|
|
20
|
+
export declare const PARTICLE_ASSET_TYPE = "particles";
|
|
21
|
+
/**
|
|
22
|
+
* The address suffixes that select the particle loader.
|
|
23
|
+
*
|
|
24
|
+
* @public
|
|
25
|
+
*/
|
|
26
|
+
export declare const PARTICLE_FILE_EXTENSIONS: readonly string[];
|
|
27
|
+
/**
|
|
28
|
+
* How many samples a baked curve or gradient row holds. Both evaluators read the same 64 samples
|
|
29
|
+
* with the same linear rule, which is what makes the lookup the contract between them.
|
|
30
|
+
*
|
|
31
|
+
* @public
|
|
32
|
+
*/
|
|
33
|
+
export declare const LOOKUP_SAMPLES = 64;
|
|
34
|
+
/**
|
|
35
|
+
* Where a particle's position is integrated: in the emitter's space and transformed by the emitter's
|
|
36
|
+
* current world matrix at draw (`"local"`, so the effect follows its entity), or baked into world
|
|
37
|
+
* space at spawn (`"world"`, so a trail stays where it was emitted).
|
|
38
|
+
*
|
|
39
|
+
* @public
|
|
40
|
+
*/
|
|
41
|
+
export declare const PARTICLE_SIMULATION_SPACES: readonly ["local", "world"];
|
|
42
|
+
/**
|
|
43
|
+
* The union of {@link PARTICLE_SIMULATION_SPACES}.
|
|
44
|
+
*
|
|
45
|
+
* @public
|
|
46
|
+
*/
|
|
47
|
+
type ParticleSimulationSpace = (typeof PARTICLE_SIMULATION_SPACES)[number];
|
|
48
|
+
/**
|
|
49
|
+
* Every emitter shape. Directional shapes emit along the emitter's local `+Y`.
|
|
50
|
+
*
|
|
51
|
+
* @public
|
|
52
|
+
*/
|
|
53
|
+
export declare const PARTICLE_SHAPE_KINDS: readonly ["point", "sphere", "hemisphere", "cone", "box", "circle", "edge", "mesh"];
|
|
54
|
+
/**
|
|
55
|
+
* The union of {@link PARTICLE_SHAPE_KINDS}.
|
|
56
|
+
*
|
|
57
|
+
* @public
|
|
58
|
+
*/
|
|
59
|
+
type ParticleShapeKind = (typeof PARTICLE_SHAPE_KINDS)[number];
|
|
60
|
+
/**
|
|
61
|
+
* Where inside a shape particles start: anywhere in it, on its surface, or — for a cone — on its
|
|
62
|
+
* base disc.
|
|
63
|
+
*
|
|
64
|
+
* @public
|
|
65
|
+
*/
|
|
66
|
+
export declare const PARTICLE_EMIT_FROM: readonly ["volume", "shell", "base"];
|
|
67
|
+
/**
|
|
68
|
+
* The union of {@link PARTICLE_EMIT_FROM}.
|
|
69
|
+
*
|
|
70
|
+
* @public
|
|
71
|
+
*/
|
|
72
|
+
type ParticleEmitFrom = (typeof PARTICLE_EMIT_FROM)[number];
|
|
73
|
+
/**
|
|
74
|
+
* How a particle is oriented when drawn.
|
|
75
|
+
*
|
|
76
|
+
* @public
|
|
77
|
+
*/
|
|
78
|
+
export declare const PARTICLE_RENDER_MODES: readonly ["billboard", "stretched", "horizontal", "vertical", "mesh"];
|
|
79
|
+
/**
|
|
80
|
+
* The union of {@link PARTICLE_RENDER_MODES}.
|
|
81
|
+
*
|
|
82
|
+
* @public
|
|
83
|
+
*/
|
|
84
|
+
type ParticleRenderMode = (typeof PARTICLE_RENDER_MODES)[number];
|
|
85
|
+
/**
|
|
86
|
+
* How particles composite over what is behind them. `premultiplied` is the default: fire and smoke
|
|
87
|
+
* share one draw and blend front-to-back correctly.
|
|
88
|
+
*
|
|
89
|
+
* @public
|
|
90
|
+
*/
|
|
91
|
+
export declare const PARTICLE_BLEND_MODES: readonly ["premultiplied", "additive", "alpha"];
|
|
92
|
+
/**
|
|
93
|
+
* The union of {@link PARTICLE_BLEND_MODES}.
|
|
94
|
+
*
|
|
95
|
+
* @public
|
|
96
|
+
*/
|
|
97
|
+
type ParticleBlendMode = (typeof PARTICLE_BLEND_MODES)[number];
|
|
98
|
+
/**
|
|
99
|
+
* The core primitives a `"mesh"` renderer may draw, each built at unit size.
|
|
100
|
+
*
|
|
101
|
+
* @public
|
|
102
|
+
*/
|
|
103
|
+
export declare const PARTICLE_MESHES: readonly ["box", "sphere", "plane", "cylinder", "capsule", "torus"];
|
|
104
|
+
/**
|
|
105
|
+
* The union of {@link PARTICLE_MESHES}.
|
|
106
|
+
*
|
|
107
|
+
* @public
|
|
108
|
+
*/
|
|
109
|
+
type ParticleMeshName = (typeof PARTICLE_MESHES)[number];
|
|
110
|
+
/**
|
|
111
|
+
* How a sprite sheet picks its frame: from a curve over the particle's life, at random per particle,
|
|
112
|
+
* or advancing at a fixed rate.
|
|
113
|
+
*
|
|
114
|
+
* @public
|
|
115
|
+
*/
|
|
116
|
+
export declare const PARTICLE_FRAME_MODES: readonly ["curve", "random", "fps"];
|
|
117
|
+
/**
|
|
118
|
+
* The union of {@link PARTICLE_FRAME_MODES}.
|
|
119
|
+
*
|
|
120
|
+
* @public
|
|
121
|
+
*/
|
|
122
|
+
type ParticleFrameMode = (typeof PARTICLE_FRAME_MODES)[number];
|
|
123
|
+
/**
|
|
124
|
+
* One stop of a colour gradient: normalized time, then sRGB red, green, blue, and alpha in `0`–`1`.
|
|
125
|
+
*
|
|
126
|
+
* @public
|
|
127
|
+
*/
|
|
128
|
+
type GradientStop = readonly [t: number, r: number, g: number, b: number, a: number];
|
|
129
|
+
/**
|
|
130
|
+
* A number a document may give as a constant, a range, or a curve. As authored:
|
|
131
|
+
* `2`, `{ "min": 1, "max": 3 }`, or `{ "curve": { "keys": [[0, 1, 0, 0], [1, 0, 0, 0]] } }`.
|
|
132
|
+
*
|
|
133
|
+
* @public
|
|
134
|
+
*/
|
|
135
|
+
type ScalarValueInput = number | {
|
|
136
|
+
readonly min: number;
|
|
137
|
+
readonly max: number;
|
|
138
|
+
} | {
|
|
139
|
+
readonly curve: CurveValue;
|
|
140
|
+
};
|
|
141
|
+
/**
|
|
142
|
+
* A colour as a document may write it: an `{ r, g, b, a }` object or an `[r, g, b, a]` array, both
|
|
143
|
+
* sRGB in `0`–`1`.
|
|
144
|
+
*
|
|
145
|
+
* @public
|
|
146
|
+
*/
|
|
147
|
+
type ColorInput = ColorLike | readonly [r: number, g: number, b: number, a: number];
|
|
148
|
+
/**
|
|
149
|
+
* A colour a document may give as a constant, a random pick between two, or a gradient.
|
|
150
|
+
*
|
|
151
|
+
* @public
|
|
152
|
+
*/
|
|
153
|
+
type ColorValueInput = ColorInput | {
|
|
154
|
+
readonly min: ColorInput;
|
|
155
|
+
readonly max: ColorInput;
|
|
156
|
+
} | {
|
|
157
|
+
readonly gradient: readonly GradientStop[];
|
|
158
|
+
};
|
|
159
|
+
/**
|
|
160
|
+
* A resolved scalar value. A `"curve"` carries its {@link LOOKUP_SAMPLES} baked samples so the CPU
|
|
161
|
+
* side never re-evaluates the Hermite spline.
|
|
162
|
+
*
|
|
163
|
+
* @public
|
|
164
|
+
*/
|
|
165
|
+
type ScalarValue = {
|
|
166
|
+
readonly kind: "constant";
|
|
167
|
+
readonly value: number;
|
|
168
|
+
} | {
|
|
169
|
+
readonly kind: "random";
|
|
170
|
+
readonly min: number;
|
|
171
|
+
readonly max: number;
|
|
172
|
+
} | {
|
|
173
|
+
readonly kind: "curve";
|
|
174
|
+
readonly curve: CurveValue;
|
|
175
|
+
readonly samples: Float32Array;
|
|
176
|
+
};
|
|
177
|
+
/**
|
|
178
|
+
* A resolved colour value. A `"gradient"` carries its baked RGBA samples, sRGB, four floats per
|
|
179
|
+
* sample.
|
|
180
|
+
*
|
|
181
|
+
* @public
|
|
182
|
+
*/
|
|
183
|
+
type ColorValue = {
|
|
184
|
+
readonly kind: "constant";
|
|
185
|
+
readonly value: ColorLike;
|
|
186
|
+
} | {
|
|
187
|
+
readonly kind: "random";
|
|
188
|
+
readonly min: ColorLike;
|
|
189
|
+
readonly max: ColorLike;
|
|
190
|
+
} | {
|
|
191
|
+
readonly kind: "gradient";
|
|
192
|
+
readonly stops: readonly GradientStop[];
|
|
193
|
+
readonly samples: Float32Array;
|
|
194
|
+
};
|
|
195
|
+
/**
|
|
196
|
+
* The `main` module: capacity, timing, space, and playback.
|
|
197
|
+
*
|
|
198
|
+
* @public
|
|
199
|
+
*/
|
|
200
|
+
interface ParticleMain {
|
|
201
|
+
/** How many spawn records the ring holds. Older records are overwritten, alive or not. */
|
|
202
|
+
readonly capacity: number;
|
|
203
|
+
/** How long one emission cycle lasts, in seconds. */
|
|
204
|
+
readonly duration: number;
|
|
205
|
+
/** Whether the cycle repeats. A non-looping system stops when the cycle ends and the last particle dies. */
|
|
206
|
+
readonly looping: boolean;
|
|
207
|
+
/** Whether `play()` fast-forwards one full cycle first, so a looping effect starts steady. */
|
|
208
|
+
readonly prewarm: boolean;
|
|
209
|
+
/** Seconds after `play()` before emission starts. */
|
|
210
|
+
readonly startDelay: number;
|
|
211
|
+
/** Where positions live. */
|
|
212
|
+
readonly simulationSpace: ParticleSimulationSpace;
|
|
213
|
+
/** The emission seed; `0` picks one at random on `play()`. A component's `seed` field overrides it. */
|
|
214
|
+
readonly seed: number;
|
|
215
|
+
/** Whether a `ParticleSystem` starts playing the first frame it is enabled. */
|
|
216
|
+
readonly playOnAwake: boolean;
|
|
217
|
+
/** A multiplier on the system's own clock. */
|
|
218
|
+
readonly timeScale: number;
|
|
219
|
+
/** The renderer's sort key within the transparent phase; lower draws first. */
|
|
220
|
+
readonly renderOrder: number;
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* One burst: `count` particles at `time` into the cycle, repeated `cycles` times every `interval`
|
|
224
|
+
* seconds with `probability`.
|
|
225
|
+
*
|
|
226
|
+
* @public
|
|
227
|
+
*/
|
|
228
|
+
interface ParticleBurst {
|
|
229
|
+
/** Seconds into the cycle. */
|
|
230
|
+
readonly time: number;
|
|
231
|
+
/** How many particles; a random count is rolled per firing. */
|
|
232
|
+
readonly count: ScalarValue;
|
|
233
|
+
/** How many times the burst fires per cycle; `0` means until the cycle ends. */
|
|
234
|
+
readonly cycles: number;
|
|
235
|
+
/** Seconds between firings. */
|
|
236
|
+
readonly interval: number;
|
|
237
|
+
/** The chance a firing happens, `0`–`1`. */
|
|
238
|
+
readonly probability: number;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* The `emission` module.
|
|
242
|
+
*
|
|
243
|
+
* @public
|
|
244
|
+
*/
|
|
245
|
+
interface ParticleEmission {
|
|
246
|
+
/** Particles per second while the cycle runs. */
|
|
247
|
+
readonly rateOverTime: number;
|
|
248
|
+
/** Particles per metre the emitter moves. */
|
|
249
|
+
readonly rateOverDistance: number;
|
|
250
|
+
/** The bursts, in declaration order. */
|
|
251
|
+
readonly bursts: readonly ParticleBurst[];
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* The `shape` module. Every field is present; a shape reads the ones that apply to it.
|
|
255
|
+
*
|
|
256
|
+
* @public
|
|
257
|
+
*/
|
|
258
|
+
interface ParticleShape {
|
|
259
|
+
/** Which shape. */
|
|
260
|
+
readonly kind: ParticleShapeKind;
|
|
261
|
+
/** The radius of a sphere, hemisphere, circle, or cone base; half the length of an edge. */
|
|
262
|
+
readonly radius: number;
|
|
263
|
+
/** How much of a sphere, hemisphere, or circle's radius emits, `0` (surface only) to `1` (whole). */
|
|
264
|
+
readonly thickness: number;
|
|
265
|
+
/** The angular span of a sphere, hemisphere, circle, or cone, in degrees. */
|
|
266
|
+
readonly arc: number;
|
|
267
|
+
/** A cone's half-angle in degrees. */
|
|
268
|
+
readonly angle: number;
|
|
269
|
+
/** A cone's height, or an edge's length. */
|
|
270
|
+
readonly length: number;
|
|
271
|
+
/** A box's full extents. */
|
|
272
|
+
readonly size: Vec3Like;
|
|
273
|
+
/** Where inside the shape particles start. */
|
|
274
|
+
readonly emitFrom: ParticleEmitFrom;
|
|
275
|
+
/** How much of the start direction is random, `0`–`1`. */
|
|
276
|
+
readonly randomDirection: number;
|
|
277
|
+
/** How much of the start direction points away from the shape's centre, `0`–`1`. */
|
|
278
|
+
readonly spherizeDirection: number;
|
|
279
|
+
/** A `"mesh"` shape's triangle soup: three floats per vertex, three vertices per triangle. */
|
|
280
|
+
readonly vertices: Float32Array;
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* The `start` module: what a particle is born with.
|
|
284
|
+
*
|
|
285
|
+
* @public
|
|
286
|
+
*/
|
|
287
|
+
interface ParticleStart {
|
|
288
|
+
/** Seconds a particle lives. */
|
|
289
|
+
readonly lifetime: ScalarValue;
|
|
290
|
+
/** Metres per second along the start direction. */
|
|
291
|
+
readonly speed: ScalarValue;
|
|
292
|
+
/** The particle's size, in metres. */
|
|
293
|
+
readonly size: ScalarValue;
|
|
294
|
+
/** Optional per-axis multipliers on `size`, or `null` for a uniform size. */
|
|
295
|
+
readonly size3D: Vec3Like | null;
|
|
296
|
+
/** The start rotation, in degrees. */
|
|
297
|
+
readonly rotation: ScalarValue;
|
|
298
|
+
/** The start colour, sRGB. A random value picks between two colours per particle. */
|
|
299
|
+
readonly color: ColorValue;
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* A rotation about a fixed axis through the emitter.
|
|
303
|
+
*
|
|
304
|
+
* @public
|
|
305
|
+
*/
|
|
306
|
+
interface ParticleOrbit {
|
|
307
|
+
/** The axis, normalized at definition time. */
|
|
308
|
+
readonly axis: Vec3Like;
|
|
309
|
+
/** Degrees per second. */
|
|
310
|
+
readonly speed: number;
|
|
311
|
+
}
|
|
312
|
+
/**
|
|
313
|
+
* A positional noise offset sampled at the analytic position.
|
|
314
|
+
*
|
|
315
|
+
* @public
|
|
316
|
+
*/
|
|
317
|
+
interface ParticleNoise {
|
|
318
|
+
/** The largest offset, in metres. */
|
|
319
|
+
readonly strength: number;
|
|
320
|
+
/** How quickly the field varies with position. */
|
|
321
|
+
readonly frequency: number;
|
|
322
|
+
/** How the field drifts with time, in field units per second. */
|
|
323
|
+
readonly scroll: Vec3Like;
|
|
324
|
+
/** How many octaves are summed, `1` or `2`. */
|
|
325
|
+
readonly octaves: number;
|
|
326
|
+
/** A multiplier on `strength` over the particle's life. */
|
|
327
|
+
readonly influenceOverLife: ScalarValue;
|
|
328
|
+
}
|
|
329
|
+
/**
|
|
330
|
+
* The `forces` module.
|
|
331
|
+
*
|
|
332
|
+
* @public
|
|
333
|
+
*/
|
|
334
|
+
interface ParticleForces {
|
|
335
|
+
/** An explicit world gravity, or `null` to use `gravityMultiplier` times the app's gravity. */
|
|
336
|
+
readonly gravity: Vec3Like | null;
|
|
337
|
+
/** How much of the app's gravity applies when `gravity` is `null`. */
|
|
338
|
+
readonly gravityMultiplier: number;
|
|
339
|
+
/** Linear drag; `0` is none. */
|
|
340
|
+
readonly drag: number;
|
|
341
|
+
/** A constant acceleration, in metres per second squared, folded into gravity. */
|
|
342
|
+
readonly constantForce: Vec3Like;
|
|
343
|
+
/** A rotation about an axis, or `null`. */
|
|
344
|
+
readonly orbit: ParticleOrbit | null;
|
|
345
|
+
/** A noise offset, or `null`. */
|
|
346
|
+
readonly noise: ParticleNoise | null;
|
|
347
|
+
}
|
|
348
|
+
/**
|
|
349
|
+
* The `overLifetime` module.
|
|
350
|
+
*
|
|
351
|
+
* @public
|
|
352
|
+
*/
|
|
353
|
+
interface ParticleOverLifetime {
|
|
354
|
+
/** A colour multiplied onto the start colour over the particle's life, or `null`. */
|
|
355
|
+
readonly color: ColorValue | null;
|
|
356
|
+
/** A multiplier on the start size (the X axis when `sizeY` or `sizeZ` is set), or `null`. */
|
|
357
|
+
readonly size: ScalarValue | null;
|
|
358
|
+
/** A separate multiplier for the Y axis, or `null` to follow `size`. */
|
|
359
|
+
readonly sizeY: ScalarValue | null;
|
|
360
|
+
/** A separate multiplier for the Z axis, or `null` to follow `size`. */
|
|
361
|
+
readonly sizeZ: ScalarValue | null;
|
|
362
|
+
/** The angular speed, in degrees per second, or `null` for none. */
|
|
363
|
+
readonly rotation: ScalarValue | null;
|
|
364
|
+
}
|
|
365
|
+
/**
|
|
366
|
+
* A sprite sheet laid out in a grid.
|
|
367
|
+
*
|
|
368
|
+
* @public
|
|
369
|
+
*/
|
|
370
|
+
interface ParticleSheet {
|
|
371
|
+
/** Columns and rows of the grid. */
|
|
372
|
+
readonly tiles: Vec2Like;
|
|
373
|
+
/** How the frame is chosen. */
|
|
374
|
+
readonly mode: ParticleFrameMode;
|
|
375
|
+
/** The frame over the particle's life as a fraction of the sheet, for `"curve"`. */
|
|
376
|
+
readonly frameOverTime: ScalarValue;
|
|
377
|
+
/** Frames per second, for `"fps"`. */
|
|
378
|
+
readonly fps: number;
|
|
379
|
+
}
|
|
380
|
+
/**
|
|
381
|
+
* The `renderer` module.
|
|
382
|
+
*
|
|
383
|
+
* @public
|
|
384
|
+
*/
|
|
385
|
+
interface ParticleRenderer {
|
|
386
|
+
/** How particles are oriented. */
|
|
387
|
+
readonly mode: ParticleRenderMode;
|
|
388
|
+
/** The primitive a `"mesh"` renderer draws. */
|
|
389
|
+
readonly mesh: ParticleMeshName;
|
|
390
|
+
/** The texture's asset address, or `null` for a procedural soft disc. */
|
|
391
|
+
readonly texture: string | null;
|
|
392
|
+
/** The sprite-sheet layout of `texture`, or `null` for a single image. */
|
|
393
|
+
readonly sheet: ParticleSheet | null;
|
|
394
|
+
/** How particles composite. */
|
|
395
|
+
readonly blend: ParticleBlendMode;
|
|
396
|
+
/** Whether particles are shaded with the main light and the ambient colour. */
|
|
397
|
+
readonly lit: boolean;
|
|
398
|
+
/** Where the particle's origin sits inside its quad, in size units; `(0, 0)` is the centre. */
|
|
399
|
+
readonly pivot: Vec2Like;
|
|
400
|
+
/** How much of the speed a `"stretched"` particle adds to its length. */
|
|
401
|
+
readonly speedScale: number;
|
|
402
|
+
/** A multiplier on a `"stretched"` particle's length. */
|
|
403
|
+
readonly lengthScale: number;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* One row of the lookup texture: which row it is and how its bytes map back to values.
|
|
407
|
+
*
|
|
408
|
+
* @public
|
|
409
|
+
*/
|
|
410
|
+
interface LookupRow {
|
|
411
|
+
/** The row index in the texture. */
|
|
412
|
+
readonly index: number;
|
|
413
|
+
/** The value a byte of `0` decodes to. */
|
|
414
|
+
readonly min: number;
|
|
415
|
+
/** The value a byte of `255` decodes to. */
|
|
416
|
+
readonly max: number;
|
|
417
|
+
}
|
|
418
|
+
/**
|
|
419
|
+
* The baked lookup texture both evaluators sample: {@link LOOKUP_SAMPLES} texels wide, RGBA8, one
|
|
420
|
+
* row per curve or gradient the definition uses, in the order colour, size, rotation, noise
|
|
421
|
+
* influence, sheet frame. The GPU reads the bytes the CPU decodes, to the filter's precision.
|
|
422
|
+
*
|
|
423
|
+
* @public
|
|
424
|
+
*/
|
|
425
|
+
interface ParticleLookup {
|
|
426
|
+
/** How many rows the texture has; at least `1`. */
|
|
427
|
+
readonly rows: number;
|
|
428
|
+
/** The texels, `rows * LOOKUP_SAMPLES * 4` bytes, top row first. */
|
|
429
|
+
readonly pixels: Uint8Array;
|
|
430
|
+
/** The colour-over-life gradient row, or `null`. */
|
|
431
|
+
readonly color: LookupRow | null;
|
|
432
|
+
/** The size-over-life row, or `null`. Per-axis sizes use R, G, and B. */
|
|
433
|
+
readonly size: LookupRow | null;
|
|
434
|
+
/** The angular-speed-over-life row, or `null`. */
|
|
435
|
+
readonly rotation: LookupRow | null;
|
|
436
|
+
/** The noise-influence-over-life row, or `null`. */
|
|
437
|
+
readonly noise: LookupRow | null;
|
|
438
|
+
/** The frame-over-life row, or `null`. */
|
|
439
|
+
readonly frame: LookupRow | null;
|
|
440
|
+
}
|
|
441
|
+
/**
|
|
442
|
+
* The parsed and baked `.particles.json` document.
|
|
443
|
+
*
|
|
444
|
+
* @public
|
|
445
|
+
*/
|
|
446
|
+
interface ParticleDefinition {
|
|
447
|
+
/** Always `"ignifx.particles"`. */
|
|
448
|
+
readonly format: typeof PARTICLES_FORMAT;
|
|
449
|
+
/** Always `1` in this build. */
|
|
450
|
+
readonly formatVersion: number;
|
|
451
|
+
/** Capacity, timing, space, and playback. */
|
|
452
|
+
readonly main: ParticleMain;
|
|
453
|
+
/** Rates and bursts. */
|
|
454
|
+
readonly emission: ParticleEmission;
|
|
455
|
+
/** Where particles start and which way they go. */
|
|
456
|
+
readonly shape: ParticleShape;
|
|
457
|
+
/** What a particle is born with. */
|
|
458
|
+
readonly start: ParticleStart;
|
|
459
|
+
/** What acts on it. */
|
|
460
|
+
readonly forces: ParticleForces;
|
|
461
|
+
/** How it changes over its life. */
|
|
462
|
+
readonly overLifetime: ParticleOverLifetime;
|
|
463
|
+
/** How it is drawn. */
|
|
464
|
+
readonly renderer: ParticleRenderer;
|
|
465
|
+
/** The baked lookup texture. */
|
|
466
|
+
readonly lookup: ParticleLookup;
|
|
467
|
+
}
|
|
468
|
+
/**
|
|
469
|
+
* What {@link defineParticles} accepts: the document as authored, every key optional. Unknown keys
|
|
470
|
+
* are reported, because a misspelled module silently doing nothing is the worst outcome for an
|
|
471
|
+
* effect file.
|
|
472
|
+
*
|
|
473
|
+
* @public
|
|
474
|
+
*/
|
|
475
|
+
interface ParticleDefinitionInput {
|
|
476
|
+
/** Always `"ignifx.particles"` when present. */
|
|
477
|
+
readonly format?: string;
|
|
478
|
+
/** The document version. */
|
|
479
|
+
readonly formatVersion?: number;
|
|
480
|
+
/** The `main` module. */
|
|
481
|
+
readonly main?: ParticleMainInput;
|
|
482
|
+
/** The `emission` module. */
|
|
483
|
+
readonly emission?: ParticleEmissionInput;
|
|
484
|
+
/** The `shape` module. */
|
|
485
|
+
readonly shape?: ParticleShapeInput;
|
|
486
|
+
/** The `start` module. */
|
|
487
|
+
readonly start?: ParticleStartInput;
|
|
488
|
+
/** The `forces` module. */
|
|
489
|
+
readonly forces?: ParticleForcesInput;
|
|
490
|
+
/** The `overLifetime` module. */
|
|
491
|
+
readonly overLifetime?: ParticleOverLifetimeInput;
|
|
492
|
+
/** The `renderer` module. */
|
|
493
|
+
readonly renderer?: ParticleRendererInput;
|
|
494
|
+
}
|
|
495
|
+
/**
|
|
496
|
+
* The `main` module as authored.
|
|
497
|
+
*
|
|
498
|
+
* @public
|
|
499
|
+
*/
|
|
500
|
+
interface ParticleMainInput {
|
|
501
|
+
/** See {@link ParticleMain.capacity}. Defaults to `1000`. */
|
|
502
|
+
readonly capacity?: number;
|
|
503
|
+
/** See {@link ParticleMain.duration}. Defaults to `5`. */
|
|
504
|
+
readonly duration?: number;
|
|
505
|
+
/** See {@link ParticleMain.looping}. Defaults to `true`. */
|
|
506
|
+
readonly looping?: boolean;
|
|
507
|
+
/** See {@link ParticleMain.prewarm}. Defaults to `false`. */
|
|
508
|
+
readonly prewarm?: boolean;
|
|
509
|
+
/** See {@link ParticleMain.startDelay}. Defaults to `0`. */
|
|
510
|
+
readonly startDelay?: number;
|
|
511
|
+
/** See {@link ParticleMain.simulationSpace}. Defaults to `"local"`. */
|
|
512
|
+
readonly simulationSpace?: ParticleSimulationSpace;
|
|
513
|
+
/** See {@link ParticleMain.seed}. Defaults to `0`. */
|
|
514
|
+
readonly seed?: number;
|
|
515
|
+
/** See {@link ParticleMain.playOnAwake}. Defaults to `true`. */
|
|
516
|
+
readonly playOnAwake?: boolean;
|
|
517
|
+
/** See {@link ParticleMain.timeScale}. Defaults to `1`. */
|
|
518
|
+
readonly timeScale?: number;
|
|
519
|
+
/** See {@link ParticleMain.renderOrder}. Defaults to `0`. */
|
|
520
|
+
readonly renderOrder?: number;
|
|
521
|
+
}
|
|
522
|
+
/**
|
|
523
|
+
* One burst as authored.
|
|
524
|
+
*
|
|
525
|
+
* @public
|
|
526
|
+
*/
|
|
527
|
+
interface ParticleBurstInput {
|
|
528
|
+
/** Seconds into the cycle. Defaults to `0`. */
|
|
529
|
+
readonly time?: number;
|
|
530
|
+
/** How many particles. Defaults to `10`. */
|
|
531
|
+
readonly count?: ScalarValueInput;
|
|
532
|
+
/** Firings per cycle; `0` means until the cycle ends. Defaults to `1`. */
|
|
533
|
+
readonly cycles?: number;
|
|
534
|
+
/** Seconds between firings. Defaults to `0.1`. */
|
|
535
|
+
readonly interval?: number;
|
|
536
|
+
/** The chance a firing happens. Defaults to `1`. */
|
|
537
|
+
readonly probability?: number;
|
|
538
|
+
}
|
|
539
|
+
/**
|
|
540
|
+
* The `emission` module as authored.
|
|
541
|
+
*
|
|
542
|
+
* @public
|
|
543
|
+
*/
|
|
544
|
+
interface ParticleEmissionInput {
|
|
545
|
+
/** Particles per second. Defaults to `10`. */
|
|
546
|
+
readonly rateOverTime?: number;
|
|
547
|
+
/** Particles per metre moved. Defaults to `0`. */
|
|
548
|
+
readonly rateOverDistance?: number;
|
|
549
|
+
/** The bursts. Defaults to none. */
|
|
550
|
+
readonly bursts?: readonly ParticleBurstInput[];
|
|
551
|
+
}
|
|
552
|
+
/**
|
|
553
|
+
* The `shape` module as authored.
|
|
554
|
+
*
|
|
555
|
+
* @public
|
|
556
|
+
*/
|
|
557
|
+
interface ParticleShapeInput {
|
|
558
|
+
/** Which shape. Defaults to `"cone"`. */
|
|
559
|
+
readonly kind?: ParticleShapeKind;
|
|
560
|
+
/** See {@link ParticleShape.radius}. Defaults to `0.2`. */
|
|
561
|
+
readonly radius?: number;
|
|
562
|
+
/** See {@link ParticleShape.thickness}. Defaults to `1`. */
|
|
563
|
+
readonly thickness?: number;
|
|
564
|
+
/** See {@link ParticleShape.arc}. Defaults to `360`. */
|
|
565
|
+
readonly arc?: number;
|
|
566
|
+
/** See {@link ParticleShape.angle}. Defaults to `25`. */
|
|
567
|
+
readonly angle?: number;
|
|
568
|
+
/** See {@link ParticleShape.length}. Defaults to `1`. */
|
|
569
|
+
readonly length?: number;
|
|
570
|
+
/** See {@link ParticleShape.size}. Defaults to `(1, 1, 1)`. */
|
|
571
|
+
readonly size?: Vec3Like;
|
|
572
|
+
/** See {@link ParticleShape.emitFrom}. Defaults to `"base"` for a cone and `"volume"` otherwise. */
|
|
573
|
+
readonly emitFrom?: ParticleEmitFrom;
|
|
574
|
+
/** See {@link ParticleShape.randomDirection}. Defaults to `0`. */
|
|
575
|
+
readonly randomDirection?: number;
|
|
576
|
+
/** See {@link ParticleShape.spherizeDirection}. Defaults to `0`. */
|
|
577
|
+
readonly spherizeDirection?: number;
|
|
578
|
+
/** A `"mesh"` shape's triangles, nine numbers per triangle. */
|
|
579
|
+
readonly vertices?: readonly number[];
|
|
580
|
+
}
|
|
581
|
+
/**
|
|
582
|
+
* The `start` module as authored.
|
|
583
|
+
*
|
|
584
|
+
* @public
|
|
585
|
+
*/
|
|
586
|
+
interface ParticleStartInput {
|
|
587
|
+
/** Defaults to `2`. */
|
|
588
|
+
readonly lifetime?: ScalarValueInput;
|
|
589
|
+
/** Defaults to `2`. */
|
|
590
|
+
readonly speed?: ScalarValueInput;
|
|
591
|
+
/** Defaults to `0.2`. */
|
|
592
|
+
readonly size?: ScalarValueInput;
|
|
593
|
+
/** Defaults to `null`. */
|
|
594
|
+
readonly size3D?: Vec3Like | null;
|
|
595
|
+
/** Defaults to `0`. */
|
|
596
|
+
readonly rotation?: ScalarValueInput;
|
|
597
|
+
/** Defaults to opaque white. */
|
|
598
|
+
readonly color?: ColorValueInput;
|
|
599
|
+
}
|
|
600
|
+
/**
|
|
601
|
+
* The `forces` module as authored.
|
|
602
|
+
*
|
|
603
|
+
* @public
|
|
604
|
+
*/
|
|
605
|
+
interface ParticleForcesInput {
|
|
606
|
+
/** An explicit gravity, or `null`/omitted to scale the app's. */
|
|
607
|
+
readonly gravity?: Vec3Like | null;
|
|
608
|
+
/** Defaults to `0`. */
|
|
609
|
+
readonly gravityMultiplier?: number;
|
|
610
|
+
/** Defaults to `0`. */
|
|
611
|
+
readonly drag?: number;
|
|
612
|
+
/** Defaults to `(0, 0, 0)`. */
|
|
613
|
+
readonly constantForce?: Vec3Like;
|
|
614
|
+
/** Defaults to none. */
|
|
615
|
+
readonly orbit?: {
|
|
616
|
+
readonly axis?: Vec3Like;
|
|
617
|
+
readonly speed?: number;
|
|
618
|
+
} | null;
|
|
619
|
+
/** Defaults to none. */
|
|
620
|
+
readonly noise?: {
|
|
621
|
+
readonly strength?: number;
|
|
622
|
+
readonly frequency?: number;
|
|
623
|
+
readonly scroll?: Vec3Like;
|
|
624
|
+
readonly octaves?: number;
|
|
625
|
+
readonly influenceOverLife?: ScalarValueInput;
|
|
626
|
+
} | null;
|
|
627
|
+
}
|
|
628
|
+
/**
|
|
629
|
+
* The `overLifetime` module as authored.
|
|
630
|
+
*
|
|
631
|
+
* @public
|
|
632
|
+
*/
|
|
633
|
+
interface ParticleOverLifetimeInput {
|
|
634
|
+
/** A gradient, or a constant tint. */
|
|
635
|
+
readonly color?: ColorValueInput | null;
|
|
636
|
+
/** A curve or constant multiplier. */
|
|
637
|
+
readonly size?: ScalarValueInput | null;
|
|
638
|
+
/** A separate Y multiplier. */
|
|
639
|
+
readonly sizeY?: ScalarValueInput | null;
|
|
640
|
+
/** A separate Z multiplier. */
|
|
641
|
+
readonly sizeZ?: ScalarValueInput | null;
|
|
642
|
+
/** Angular speed in degrees per second. */
|
|
643
|
+
readonly rotation?: ScalarValueInput | null;
|
|
644
|
+
}
|
|
645
|
+
/**
|
|
646
|
+
* A sprite sheet as authored.
|
|
647
|
+
*
|
|
648
|
+
* @public
|
|
649
|
+
*/
|
|
650
|
+
interface ParticleSheetInput {
|
|
651
|
+
/** Columns and rows. Defaults to `(1, 1)`. */
|
|
652
|
+
readonly tiles?: Vec2Like;
|
|
653
|
+
/** A curve over life, `"random"`, or `{ fps }`. Defaults to a linear curve over the whole sheet. */
|
|
654
|
+
readonly frameOverTime?: ScalarValueInput | "random" | {
|
|
655
|
+
readonly fps: number;
|
|
656
|
+
};
|
|
657
|
+
}
|
|
658
|
+
/**
|
|
659
|
+
* The `renderer` module as authored.
|
|
660
|
+
*
|
|
661
|
+
* @public
|
|
662
|
+
*/
|
|
663
|
+
interface ParticleRendererInput {
|
|
664
|
+
/** Defaults to `"billboard"`. */
|
|
665
|
+
readonly mode?: ParticleRenderMode;
|
|
666
|
+
/** Defaults to `"box"`. */
|
|
667
|
+
readonly mesh?: ParticleMeshName;
|
|
668
|
+
/** Defaults to `null`. */
|
|
669
|
+
readonly texture?: string | null;
|
|
670
|
+
/** Defaults to `null`. */
|
|
671
|
+
readonly sheet?: ParticleSheetInput | null;
|
|
672
|
+
/** Defaults to `"premultiplied"`. */
|
|
673
|
+
readonly blend?: ParticleBlendMode;
|
|
674
|
+
/** Defaults to `false`. */
|
|
675
|
+
readonly lit?: boolean;
|
|
676
|
+
/** Defaults to `(0, 0)`. */
|
|
677
|
+
readonly pivot?: Vec2Like;
|
|
678
|
+
/** Defaults to `0`. */
|
|
679
|
+
readonly speedScale?: number;
|
|
680
|
+
/** Defaults to `1`. */
|
|
681
|
+
readonly lengthScale?: number;
|
|
682
|
+
}
|
|
683
|
+
//#endregion
|
|
684
|
+
//#region src/assets/particle-asset.d.ts
|
|
685
|
+
/**
|
|
686
|
+
* A parsed particle document.
|
|
687
|
+
*
|
|
688
|
+
* @example
|
|
689
|
+
* ```ts
|
|
690
|
+
* const handle = app.assets.load<ParticleAsset>("fx/fire.particles.json").retain();
|
|
691
|
+
* await handle.promise;
|
|
692
|
+
* handle.value.definition.main.capacity; // 1000
|
|
693
|
+
* ```
|
|
694
|
+
*
|
|
695
|
+
* @public
|
|
696
|
+
*/
|
|
697
|
+
export declare class ParticleAsset {
|
|
698
|
+
#private;
|
|
699
|
+
/** The asset type name, so `assetRef` and the inspector can round-trip a reference. */
|
|
700
|
+
static assetType: string;
|
|
701
|
+
/** Where the document was loaded from, or the `memory:` address it was published at. */
|
|
702
|
+
readonly address: string;
|
|
703
|
+
/** The parsed, baked document. */
|
|
704
|
+
readonly definition: ParticleDefinition;
|
|
705
|
+
/** The texture the renderer samples, or `null` for the procedural soft disc. */
|
|
706
|
+
readonly texture: AssetHandle<TextureAsset> | null;
|
|
707
|
+
/**
|
|
708
|
+
* Wraps a parsed document.
|
|
709
|
+
*
|
|
710
|
+
* @param address - Where it came from.
|
|
711
|
+
* @param definition - The parsed document.
|
|
712
|
+
* @param texture - The renderer's texture handle, or `null`.
|
|
713
|
+
* @param ownsTexture - Whether {@link ParticleAsset.dispose} releases the texture handle. The
|
|
714
|
+
* loader's dependency is released by the asset service; an in-memory asset holds its own.
|
|
715
|
+
*
|
|
716
|
+
* @internal
|
|
717
|
+
*/
|
|
718
|
+
constructor(address: string, definition: ParticleDefinition, texture?: AssetHandle<TextureAsset> | null, ownsTexture?: boolean);
|
|
719
|
+
/**
|
|
720
|
+
* Releases what the asset holds beyond its data. The `particles` asset type's `unload` runs it
|
|
721
|
+
* when the last holder releases the handle.
|
|
722
|
+
*/
|
|
723
|
+
dispose(): void;
|
|
724
|
+
}
|
|
725
|
+
//#endregion
|
|
726
|
+
//#region src/emitter/record-ring.d.ts
|
|
727
|
+
/**
|
|
728
|
+
* Floats per record.
|
|
729
|
+
*
|
|
730
|
+
* @beta
|
|
731
|
+
*/
|
|
732
|
+
export declare const RECORD_FLOATS = 12;
|
|
733
|
+
/**
|
|
734
|
+
* Bytes per record, matching the WGSL `Particle` struct's size.
|
|
735
|
+
*
|
|
736
|
+
* @beta
|
|
737
|
+
*/
|
|
738
|
+
export declare const RECORD_BYTES: number;
|
|
739
|
+
/**
|
|
740
|
+
* The float index of `spawnTime` inside a record.
|
|
741
|
+
*
|
|
742
|
+
* @beta
|
|
743
|
+
*/
|
|
744
|
+
export declare const RECORD_SPAWN_TIME = 0;
|
|
745
|
+
/**
|
|
746
|
+
* The float index of `lifetime` inside a record.
|
|
747
|
+
*
|
|
748
|
+
* @beta
|
|
749
|
+
*/
|
|
750
|
+
export declare const RECORD_LIFETIME = 1;
|
|
751
|
+
/**
|
|
752
|
+
* The word index of `seed` inside a record; read it from the ring's `words`, not its floats.
|
|
753
|
+
*
|
|
754
|
+
* @beta
|
|
755
|
+
*/
|
|
756
|
+
export declare const RECORD_SEED = 2;
|
|
757
|
+
/**
|
|
758
|
+
* The float index of `position.x` inside a record.
|
|
759
|
+
*
|
|
760
|
+
* @beta
|
|
761
|
+
*/
|
|
762
|
+
export declare const RECORD_POSITION = 4;
|
|
763
|
+
/**
|
|
764
|
+
* The float index of `size` inside a record.
|
|
765
|
+
*
|
|
766
|
+
* @beta
|
|
767
|
+
*/
|
|
768
|
+
export declare const RECORD_SIZE = 7;
|
|
769
|
+
/**
|
|
770
|
+
* The float index of `velocity.x` inside a record.
|
|
771
|
+
*
|
|
772
|
+
* @beta
|
|
773
|
+
*/
|
|
774
|
+
export declare const RECORD_VELOCITY = 8;
|
|
775
|
+
/**
|
|
776
|
+
* The float index of `rotation` inside a record, in radians.
|
|
777
|
+
*
|
|
778
|
+
* @beta
|
|
779
|
+
*/
|
|
780
|
+
export declare const RECORD_ROTATION = 11;
|
|
781
|
+
/**
|
|
782
|
+
* A contiguous run of records to upload, in slots.
|
|
783
|
+
*
|
|
784
|
+
* @beta
|
|
785
|
+
*/
|
|
786
|
+
interface UploadRange {
|
|
787
|
+
/** The first slot. */
|
|
788
|
+
readonly start: number;
|
|
789
|
+
/** How many records. */
|
|
790
|
+
readonly count: number;
|
|
791
|
+
}
|
|
792
|
+
/**
|
|
793
|
+
* What one reconciliation pass found.
|
|
794
|
+
*
|
|
795
|
+
* @beta
|
|
796
|
+
*/
|
|
797
|
+
interface RingCensus {
|
|
798
|
+
/** Records whose age is inside their lifetime. Exact. */
|
|
799
|
+
alive: number;
|
|
800
|
+
/** Records from the newest back to the oldest still alive: what the GPU draws. */
|
|
801
|
+
drawCount: number;
|
|
802
|
+
}
|
|
803
|
+
/**
|
|
804
|
+
* The CPU copy of a system's spawn records. Record `n` lives in slot `n % capacity`, so the newest
|
|
805
|
+
* record is the one the shader draws first and an overwritten record simply disappears.
|
|
806
|
+
*
|
|
807
|
+
* @beta
|
|
808
|
+
*/
|
|
809
|
+
export declare class SpawnRecordRing {
|
|
810
|
+
#private;
|
|
811
|
+
/** How many records the ring holds. */
|
|
812
|
+
readonly capacity: number;
|
|
813
|
+
/** The records as floats, `capacity * RECORD_FLOATS` long. */
|
|
814
|
+
readonly floats: Float32Array;
|
|
815
|
+
/** The same bytes as words, for `seed` and `flags`. */
|
|
816
|
+
readonly words: Uint32Array;
|
|
817
|
+
/**
|
|
818
|
+
* Allocates a ring.
|
|
819
|
+
*
|
|
820
|
+
* @param capacity - How many records it holds; at least one.
|
|
821
|
+
*/
|
|
822
|
+
constructor(capacity: number);
|
|
823
|
+
/**
|
|
824
|
+
* How many records have been written since the last clear.
|
|
825
|
+
*
|
|
826
|
+
* @returns The count; it never decreases except through {@link SpawnRecordRing.clear}.
|
|
827
|
+
*/
|
|
828
|
+
get written(): number;
|
|
829
|
+
/**
|
|
830
|
+
* The slot the next record goes into.
|
|
831
|
+
*
|
|
832
|
+
* @returns `written % capacity`.
|
|
833
|
+
*/
|
|
834
|
+
get head(): number;
|
|
835
|
+
/**
|
|
836
|
+
* The index of the oldest record still inside the draw window.
|
|
837
|
+
*
|
|
838
|
+
* @returns The record index, not the slot.
|
|
839
|
+
*/
|
|
840
|
+
get tail(): number;
|
|
841
|
+
/**
|
|
842
|
+
* How many records have been written and not yet uploaded, capped at the capacity because older
|
|
843
|
+
* ones were overwritten anyway.
|
|
844
|
+
*
|
|
845
|
+
* @returns The pending count.
|
|
846
|
+
*/
|
|
847
|
+
get pendingCount(): number;
|
|
848
|
+
/**
|
|
849
|
+
* The slot of a record.
|
|
850
|
+
*
|
|
851
|
+
* @param index - The record index.
|
|
852
|
+
* @returns The slot.
|
|
853
|
+
*/
|
|
854
|
+
slotOf(index: number): number;
|
|
855
|
+
/**
|
|
856
|
+
* Writes one record and returns its slot.
|
|
857
|
+
*
|
|
858
|
+
* @param spawnTime - The system clock at spawn.
|
|
859
|
+
* @param lifetime - Seconds the particle lives.
|
|
860
|
+
* @param seed - The per-record hash seed.
|
|
861
|
+
* @param flags - Reserved; write `0`.
|
|
862
|
+
* @param px - Start position X.
|
|
863
|
+
* @param py - Start position Y.
|
|
864
|
+
* @param pz - Start position Z.
|
|
865
|
+
* @param size - Start size.
|
|
866
|
+
* @param vx - Start velocity X.
|
|
867
|
+
* @param vy - Start velocity Y.
|
|
868
|
+
* @param vz - Start velocity Z.
|
|
869
|
+
* @param rotation - Start rotation, in radians.
|
|
870
|
+
* @returns The slot written.
|
|
871
|
+
*/
|
|
872
|
+
write(spawnTime: number, lifetime: number, seed: number, flags: number, px: number, py: number, pz: number, size: number, vx: number, vy: number, vz: number, rotation: number): number;
|
|
873
|
+
/**
|
|
874
|
+
* The runs of slots written since the last upload, at most two because a ring wraps at most once
|
|
875
|
+
* per frame that matters — anything older than a whole ring was overwritten.
|
|
876
|
+
*
|
|
877
|
+
* @param out - Receives up to two ranges.
|
|
878
|
+
* @returns How many of `out`'s entries are meaningful: `0`, `1`, or `2`.
|
|
879
|
+
*/
|
|
880
|
+
pendingRanges(out: [UploadRange, UploadRange]): number;
|
|
881
|
+
/** Records that everything written so far has reached the GPU. */
|
|
882
|
+
markUploaded(): void;
|
|
883
|
+
/**
|
|
884
|
+
* Advances the tail past leading dead records and counts the alive ones behind it. One pass over
|
|
885
|
+
* the draw window, no allocation.
|
|
886
|
+
*
|
|
887
|
+
* @param clock - The system clock.
|
|
888
|
+
* @param out - Receives the counts.
|
|
889
|
+
* @returns `out`.
|
|
890
|
+
*/
|
|
891
|
+
reconcile(clock: number, out: RingCensus): RingCensus;
|
|
892
|
+
/** Forgets every record, so the next frame draws nothing and uploads nothing. */
|
|
893
|
+
clear(): void;
|
|
894
|
+
}
|
|
895
|
+
//#endregion
|
|
896
|
+
//#region src/emitter/emitter-core.d.ts
|
|
897
|
+
/**
|
|
898
|
+
* What {@link ParticleEmitterCore.stop} accepts.
|
|
899
|
+
*
|
|
900
|
+
* @public
|
|
901
|
+
*/
|
|
902
|
+
interface ParticleStopOptions {
|
|
903
|
+
/** Whether to forget the live particles too. Defaults to `false`: they finish their lives. */
|
|
904
|
+
readonly clear?: boolean;
|
|
905
|
+
}
|
|
906
|
+
/**
|
|
907
|
+
* How {@link ParticleEmitterCore} is built.
|
|
908
|
+
*
|
|
909
|
+
* @beta
|
|
910
|
+
*/
|
|
911
|
+
interface ParticleEmitterCoreOptions {
|
|
912
|
+
/** The definition to emit. */
|
|
913
|
+
readonly definition: ParticleDefinition;
|
|
914
|
+
/** The ring capacity, after the app's budget clamped it. */
|
|
915
|
+
readonly capacity: number;
|
|
916
|
+
/** The seed; `0` picks a random one on `play()`. */
|
|
917
|
+
readonly seed: number;
|
|
918
|
+
}
|
|
919
|
+
/**
|
|
920
|
+
* The CPU half of a particle system: the spawn-record ring, the system clock, the seeded random
|
|
921
|
+
* stream, and the emission scheduler.
|
|
922
|
+
*
|
|
923
|
+
* @example
|
|
924
|
+
* ```ts
|
|
925
|
+
* const core = new ParticleEmitterCore({ definition, capacity: 1000, seed: 7 });
|
|
926
|
+
* core.play();
|
|
927
|
+
* core.advance(1 / 60);
|
|
928
|
+
* core.reconcile();
|
|
929
|
+
* ```
|
|
930
|
+
*
|
|
931
|
+
* @beta
|
|
932
|
+
*/
|
|
933
|
+
export declare class ParticleEmitterCore {
|
|
934
|
+
#private;
|
|
935
|
+
/** The definition every record is written from. */
|
|
936
|
+
readonly definition: ParticleDefinition;
|
|
937
|
+
/** The spawn records. */
|
|
938
|
+
readonly ring: SpawnRecordRing;
|
|
939
|
+
/**
|
|
940
|
+
* The emitter's world matrix, column-major; write it before {@link ParticleEmitterCore.advance}.
|
|
941
|
+
* A `"world"` definition bakes it into every record, and `rateOverDistance` reads its translation.
|
|
942
|
+
*/
|
|
943
|
+
readonly emitterWorld: Float32Array;
|
|
944
|
+
/** A `0`–`1` multiplier on rates and burst counts; the app's `qualityScale`. */
|
|
945
|
+
qualityScale: number;
|
|
946
|
+
/** Called once when a non-looping system runs out of cycle and particles. */
|
|
947
|
+
onStopped: (() => void) | null;
|
|
948
|
+
/**
|
|
949
|
+
* Creates the core.
|
|
950
|
+
*
|
|
951
|
+
* @param options - The definition, the clamped capacity, and the seed.
|
|
952
|
+
*/
|
|
953
|
+
constructor(options: ParticleEmitterCoreOptions);
|
|
954
|
+
/**
|
|
955
|
+
* The system clock, in seconds: what every record's age is measured against.
|
|
956
|
+
*
|
|
957
|
+
* @returns The clock.
|
|
958
|
+
*/
|
|
959
|
+
get time(): number;
|
|
960
|
+
/**
|
|
961
|
+
* Whether the system is playing, paused or not.
|
|
962
|
+
*
|
|
963
|
+
* @returns `true` between `play()` and the stop.
|
|
964
|
+
*/
|
|
965
|
+
get isPlaying(): boolean;
|
|
966
|
+
/**
|
|
967
|
+
* Whether the clock is held.
|
|
968
|
+
*
|
|
969
|
+
* @returns `true` after `pause()`.
|
|
970
|
+
*/
|
|
971
|
+
get isPaused(): boolean;
|
|
972
|
+
/**
|
|
973
|
+
* Whether the current cycle still emits.
|
|
974
|
+
*
|
|
975
|
+
* @returns `true` while emission runs.
|
|
976
|
+
*/
|
|
977
|
+
get isEmitting(): boolean;
|
|
978
|
+
/**
|
|
979
|
+
* The seed in use: the declared one, or the random one `play()` picked for a declared `0`.
|
|
980
|
+
*
|
|
981
|
+
* @returns The seed.
|
|
982
|
+
*/
|
|
983
|
+
get seed(): number;
|
|
984
|
+
/**
|
|
985
|
+
* How many particles are alive, as of the last {@link ParticleEmitterCore.reconcile}.
|
|
986
|
+
*
|
|
987
|
+
* @returns The exact count.
|
|
988
|
+
*/
|
|
989
|
+
get aliveCount(): number;
|
|
990
|
+
/**
|
|
991
|
+
* How many records the GPU draws, newest first: from the newest back to the oldest still alive.
|
|
992
|
+
*
|
|
993
|
+
* @returns The draw count.
|
|
994
|
+
*/
|
|
995
|
+
get drawCount(): number;
|
|
996
|
+
/**
|
|
997
|
+
* How many particles have been emitted since the last `play()` from an empty ring.
|
|
998
|
+
*
|
|
999
|
+
* @returns The total.
|
|
1000
|
+
*/
|
|
1001
|
+
get emittedTotal(): number;
|
|
1002
|
+
/**
|
|
1003
|
+
* How many spawns landed on a slot whose particle was still alive, so that older particle
|
|
1004
|
+
* vanished. It is what "over budget" looks like from inside a system: the capacity the app's
|
|
1005
|
+
* `maxParticles` granted is smaller than `rate × lifetime`.
|
|
1006
|
+
*
|
|
1007
|
+
* @returns The total since the last `play()` from an empty ring.
|
|
1008
|
+
*/
|
|
1009
|
+
get droppedTotal(): number;
|
|
1010
|
+
/**
|
|
1011
|
+
* Starts, or resumes after a `stop()`, emission. On an empty ring the clock restarts at zero and
|
|
1012
|
+
* a `prewarm` definition fast-forwards one cycle; otherwise the clock keeps counting.
|
|
1013
|
+
*/
|
|
1014
|
+
play(): void;
|
|
1015
|
+
/**
|
|
1016
|
+
* Stops emission. Live particles keep ageing until they die unless `clear` is set.
|
|
1017
|
+
*
|
|
1018
|
+
* @param options - Whether to clear the particles too.
|
|
1019
|
+
*/
|
|
1020
|
+
stop(options?: ParticleStopOptions): void;
|
|
1021
|
+
/** Holds the clock; emission and ageing stop until {@link ParticleEmitterCore.resume}. */
|
|
1022
|
+
pause(): void;
|
|
1023
|
+
/** Releases a `pause()`. */
|
|
1024
|
+
resume(): void;
|
|
1025
|
+
/**
|
|
1026
|
+
* Spawns particles now, at the current clock, whether or not the system is playing.
|
|
1027
|
+
*
|
|
1028
|
+
* @param count - How many; a non-integer is floored, and `qualityScale` does not apply.
|
|
1029
|
+
*/
|
|
1030
|
+
emit(count: number): void;
|
|
1031
|
+
/**
|
|
1032
|
+
* Fast-forwards the system by `seconds` in fixed sub-steps, emitting as it goes — what `prewarm`
|
|
1033
|
+
* does, and what a test does to reach a known state. The definition's `timeScale` does not apply.
|
|
1034
|
+
*
|
|
1035
|
+
* @param seconds - How far to advance the system clock.
|
|
1036
|
+
*/
|
|
1037
|
+
simulate(seconds: number): void;
|
|
1038
|
+
/**
|
|
1039
|
+
* Advances one frame. It does nothing while paused, and nothing once a stopped system's last
|
|
1040
|
+
* particle has died.
|
|
1041
|
+
*
|
|
1042
|
+
* @param dt - The frame's scaled seconds; the definition's own `timeScale` is applied here.
|
|
1043
|
+
*/
|
|
1044
|
+
advance(dt: number): void;
|
|
1045
|
+
/**
|
|
1046
|
+
* Recounts the ring at the current clock and fires `onStopped` once a non-looping system has
|
|
1047
|
+
* nothing left to do.
|
|
1048
|
+
*
|
|
1049
|
+
* @returns The census.
|
|
1050
|
+
*/
|
|
1051
|
+
reconcile(): RingCensus;
|
|
1052
|
+
}
|
|
1053
|
+
//#endregion
|
|
1054
|
+
//#region src/evaluate/particle-math.d.ts
|
|
1055
|
+
/**
|
|
1056
|
+
* Everything a particle is at one instant.
|
|
1057
|
+
*
|
|
1058
|
+
* @beta
|
|
1059
|
+
*/
|
|
1060
|
+
interface ParticleState {
|
|
1061
|
+
/** The world position. */
|
|
1062
|
+
readonly position: Float32Array;
|
|
1063
|
+
/** The world velocity. */
|
|
1064
|
+
readonly velocity: Float32Array;
|
|
1065
|
+
/** The size along each axis, in metres. */
|
|
1066
|
+
readonly size: Float32Array;
|
|
1067
|
+
/** Linear red, green, blue, and straight alpha. */
|
|
1068
|
+
readonly color: Float32Array;
|
|
1069
|
+
/** The rotation about the view axis (or the mesh's spin axis), in radians. */
|
|
1070
|
+
rotation: number;
|
|
1071
|
+
/** The sprite-sheet frame, or `0` without a sheet. */
|
|
1072
|
+
frame: number;
|
|
1073
|
+
/** Seconds since spawn. */
|
|
1074
|
+
age: number;
|
|
1075
|
+
/** `age / lifetime`, in `[0, 1]`. */
|
|
1076
|
+
life: number;
|
|
1077
|
+
}
|
|
1078
|
+
/**
|
|
1079
|
+
* Allocates an empty state.
|
|
1080
|
+
*
|
|
1081
|
+
* @returns A state with every field zeroed.
|
|
1082
|
+
*
|
|
1083
|
+
* @beta
|
|
1084
|
+
*/
|
|
1085
|
+
export declare function createParticleState(): ParticleState;
|
|
1086
|
+
/**
|
|
1087
|
+
* The per-system inputs the evaluator needs beyond the definition.
|
|
1088
|
+
*
|
|
1089
|
+
* @beta
|
|
1090
|
+
*/
|
|
1091
|
+
interface ParticleEvaluationInputs {
|
|
1092
|
+
/** The definition every record was written from. */
|
|
1093
|
+
readonly definition: ParticleDefinition;
|
|
1094
|
+
/** The effective gravity plus constant force, in the simulation space. */
|
|
1095
|
+
readonly gravity: Float32Array;
|
|
1096
|
+
/** The emitter's current world matrix, for a `"local"` definition; ignored for `"world"`. */
|
|
1097
|
+
readonly emitterWorld: Float32Array;
|
|
1098
|
+
/** The orbit centre in the simulation space: the origin for `"local"`, the emitter's position for `"world"`. */
|
|
1099
|
+
readonly orbitCenter: Float32Array;
|
|
1100
|
+
}
|
|
1101
|
+
/**
|
|
1102
|
+
* Evaluates one record at a clock.
|
|
1103
|
+
*
|
|
1104
|
+
* @param inputs - The definition and the per-system values.
|
|
1105
|
+
* @param floats - The ring's floats.
|
|
1106
|
+
* @param words - The ring's words.
|
|
1107
|
+
* @param slot - Which record.
|
|
1108
|
+
* @param clock - The system clock.
|
|
1109
|
+
* @param out - Receives the state.
|
|
1110
|
+
* @returns `true` when the particle is alive; `false` leaves `out` untouched.
|
|
1111
|
+
*
|
|
1112
|
+
* @beta
|
|
1113
|
+
*/
|
|
1114
|
+
export declare function evaluateParticle(inputs: ParticleEvaluationInputs, floats: Float32Array, words: Uint32Array, slot: number, clock: number, out: ParticleState): boolean;
|
|
1115
|
+
/**
|
|
1116
|
+
* Reads a scalar row's decoded value at a normalized time.
|
|
1117
|
+
*
|
|
1118
|
+
* @param definition - The definition.
|
|
1119
|
+
* @param row - The row, or `null` to return `fallback`.
|
|
1120
|
+
* @param life - The normalized time.
|
|
1121
|
+
* @param channel - Which channel holds the value.
|
|
1122
|
+
* @param fallback - What to return when the row is absent.
|
|
1123
|
+
* @returns The decoded value.
|
|
1124
|
+
*
|
|
1125
|
+
* @beta
|
|
1126
|
+
*/
|
|
1127
|
+
export declare function readScalarRow(definition: ParticleDefinition, row: LookupRow | null, life: number, channel: number, fallback: number): number;
|
|
1128
|
+
//#endregion
|
|
1129
|
+
//#region src/gpu/particle-system.d.ts
|
|
1130
|
+
/**
|
|
1131
|
+
* Where the update system sits in `Update`: after every script, so a script's `emit()` is drawn in
|
|
1132
|
+
* the same frame.
|
|
1133
|
+
*
|
|
1134
|
+
* @public
|
|
1135
|
+
*/
|
|
1136
|
+
export declare const PARTICLE_UPDATE_ORDER = 900;
|
|
1137
|
+
/**
|
|
1138
|
+
* Where the render system sits in `PreRender`: before core's shader-uniform (890) and render-sync
|
|
1139
|
+
* (900) systems, so this frame's records and uniforms are what the scene draws.
|
|
1140
|
+
*
|
|
1141
|
+
* @public
|
|
1142
|
+
*/
|
|
1143
|
+
export declare const PARTICLE_RENDER_ORDER = 880;
|
|
1144
|
+
/**
|
|
1145
|
+
* Draws a particle effect on its entity.
|
|
1146
|
+
*
|
|
1147
|
+
* @example
|
|
1148
|
+
* ```ts
|
|
1149
|
+
* const fire = particleAssetFromDefinition(app, particleDefinition("fire"));
|
|
1150
|
+
* const system = campfire.addComponent(ParticleSystem, { definition: fire });
|
|
1151
|
+
* system.emit(50);
|
|
1152
|
+
* ```
|
|
1153
|
+
*
|
|
1154
|
+
* @public
|
|
1155
|
+
*/
|
|
1156
|
+
export declare class ParticleSystem extends Component implements ComponentHooks {
|
|
1157
|
+
#private;
|
|
1158
|
+
/** The registration id the serializer writes into scene files. */
|
|
1159
|
+
static typeId: string;
|
|
1160
|
+
/** Several effects may share one entity; each owns its own renderer. */
|
|
1161
|
+
static allowMultiple: boolean;
|
|
1162
|
+
/** The declarative fields (ADR-0004). */
|
|
1163
|
+
static schema: Schema;
|
|
1164
|
+
/** The `.particles.json`, as a loaded handle. */
|
|
1165
|
+
definition: AssetHandle<ParticleAsset> | null;
|
|
1166
|
+
/** Whether the system plays the first frame it is enabled; the definition's `playOnAwake` must agree. */
|
|
1167
|
+
playOnAwake: boolean;
|
|
1168
|
+
/** The emission seed; `0` uses the definition's, and a definition seed of `0` picks at random. */
|
|
1169
|
+
seed: number;
|
|
1170
|
+
/** Emitted once when a non-looping system runs out of cycle and particles. */
|
|
1171
|
+
readonly onStopped: Signal<ParticleSystem>;
|
|
1172
|
+
/** Applies the schema defaults, exactly as `Component.define` would. */
|
|
1173
|
+
constructor();
|
|
1174
|
+
/**
|
|
1175
|
+
* The loaded document, or `null` while the handle is loading or unset.
|
|
1176
|
+
*
|
|
1177
|
+
* @returns The asset.
|
|
1178
|
+
*/
|
|
1179
|
+
get asset(): ParticleAsset | null;
|
|
1180
|
+
/**
|
|
1181
|
+
* Whether the system is playing, paused or not.
|
|
1182
|
+
*
|
|
1183
|
+
* @returns `true` between `play()` and the stop.
|
|
1184
|
+
*/
|
|
1185
|
+
get isPlaying(): boolean;
|
|
1186
|
+
/**
|
|
1187
|
+
* Whether the clock is held by `pause()`.
|
|
1188
|
+
*
|
|
1189
|
+
* @returns `true` while paused.
|
|
1190
|
+
*/
|
|
1191
|
+
get isPaused(): boolean;
|
|
1192
|
+
/**
|
|
1193
|
+
* How many particles are alive, exactly, as of the last frame.
|
|
1194
|
+
*
|
|
1195
|
+
* @returns The count.
|
|
1196
|
+
*/
|
|
1197
|
+
get aliveCount(): number;
|
|
1198
|
+
/**
|
|
1199
|
+
* How many records the GPU draws this frame: from the newest back to the oldest still alive.
|
|
1200
|
+
*
|
|
1201
|
+
* @returns The draw count.
|
|
1202
|
+
*/
|
|
1203
|
+
get drawCount(): number;
|
|
1204
|
+
/**
|
|
1205
|
+
* How many spawns displaced a particle that was still alive, because the capacity the app's
|
|
1206
|
+
* `maxParticles` budget granted is smaller than the definition's rate times its lifetime.
|
|
1207
|
+
*
|
|
1208
|
+
* @returns The total since the system last started from empty.
|
|
1209
|
+
*/
|
|
1210
|
+
get droppedCount(): number;
|
|
1211
|
+
/**
|
|
1212
|
+
* The system-local clock, in seconds — what every particle's age is measured against and what the
|
|
1213
|
+
* shader reads as `clock`.
|
|
1214
|
+
*
|
|
1215
|
+
* @returns The clock.
|
|
1216
|
+
*/
|
|
1217
|
+
get time(): number;
|
|
1218
|
+
/**
|
|
1219
|
+
* The ring capacity in use, after the app's budget clamped the definition's.
|
|
1220
|
+
*
|
|
1221
|
+
* @returns The capacity, or `0` before a definition is applied.
|
|
1222
|
+
*/
|
|
1223
|
+
get capacity(): number;
|
|
1224
|
+
/**
|
|
1225
|
+
* The CPU mirror of the spawn records: `capacity * 12` floats, one 48-byte record per slot, in
|
|
1226
|
+
* the layout `src/emitter/record-ring.ts` documents. Read-only; for tests and tools.
|
|
1227
|
+
*
|
|
1228
|
+
* @returns The mirror, or `null` before a definition is applied.
|
|
1229
|
+
*
|
|
1230
|
+
* @beta
|
|
1231
|
+
*/
|
|
1232
|
+
get records(): Float32Array | null;
|
|
1233
|
+
/**
|
|
1234
|
+
* The emitter core the frame drives.
|
|
1235
|
+
*
|
|
1236
|
+
* @returns The core, or `null` before a definition is applied.
|
|
1237
|
+
*
|
|
1238
|
+
* @internal
|
|
1239
|
+
*/
|
|
1240
|
+
get core(): ParticleEmitterCore | null;
|
|
1241
|
+
/**
|
|
1242
|
+
* The renderer the system draws through.
|
|
1243
|
+
*
|
|
1244
|
+
* @returns The renderer, or `null` before the GPU side is built.
|
|
1245
|
+
*
|
|
1246
|
+
* @internal
|
|
1247
|
+
*/
|
|
1248
|
+
get renderer(): InstancedMeshRenderer | null;
|
|
1249
|
+
/**
|
|
1250
|
+
* The material the system draws with.
|
|
1251
|
+
*
|
|
1252
|
+
* @returns The handle, or `null` before the GPU side is built.
|
|
1253
|
+
*
|
|
1254
|
+
* @internal
|
|
1255
|
+
*/
|
|
1256
|
+
get material(): AssetHandle<MaterialAsset> | null;
|
|
1257
|
+
/**
|
|
1258
|
+
* The storage buffer the records are streamed into.
|
|
1259
|
+
*
|
|
1260
|
+
* @returns The handle, or `null` before the GPU side is built.
|
|
1261
|
+
*
|
|
1262
|
+
* @internal
|
|
1263
|
+
*/
|
|
1264
|
+
get storage(): AssetHandle<StorageBufferAsset> | null;
|
|
1265
|
+
/**
|
|
1266
|
+
* Bytes uploaded in the last frame.
|
|
1267
|
+
*
|
|
1268
|
+
* @returns The byte count.
|
|
1269
|
+
*
|
|
1270
|
+
* @internal
|
|
1271
|
+
*/
|
|
1272
|
+
get uploadedBytes(): number;
|
|
1273
|
+
/**
|
|
1274
|
+
* Particles emitted in the last frame.
|
|
1275
|
+
*
|
|
1276
|
+
* @returns The count.
|
|
1277
|
+
*
|
|
1278
|
+
* @internal
|
|
1279
|
+
*/
|
|
1280
|
+
get emittedThisFrame(): number;
|
|
1281
|
+
/** Starts emitting, or resumes after `stop()`. A `prewarm` definition fast-forwards one cycle. */
|
|
1282
|
+
play(): void;
|
|
1283
|
+
/**
|
|
1284
|
+
* Stops emitting. Live particles finish their lives unless `clear` is set.
|
|
1285
|
+
*
|
|
1286
|
+
* @param options - Whether to clear the particles too.
|
|
1287
|
+
*/
|
|
1288
|
+
stop(options?: ParticleStopOptions): void;
|
|
1289
|
+
/** Holds the clock; every particle freezes in place. */
|
|
1290
|
+
pause(): void;
|
|
1291
|
+
/** Releases `pause()`. */
|
|
1292
|
+
resume(): void;
|
|
1293
|
+
/**
|
|
1294
|
+
* Spawns particles now, at the current clock, whether or not the system is playing. Called from a
|
|
1295
|
+
* script's `update`, they are drawn in the same frame.
|
|
1296
|
+
*
|
|
1297
|
+
* @param count - How many; floored.
|
|
1298
|
+
* @throws IgnifxError with code `IGX-1707` for a negative or non-finite count, or `IGX-1705`
|
|
1299
|
+
* when no definition is applied.
|
|
1300
|
+
*/
|
|
1301
|
+
emit(count: number): void;
|
|
1302
|
+
/**
|
|
1303
|
+
* Fast-forwards the system by `seconds`, emitting as it goes — what `prewarm` does.
|
|
1304
|
+
*
|
|
1305
|
+
* @param seconds - How far to advance.
|
|
1306
|
+
* @throws IgnifxError with code `IGX-1707` for a negative or non-finite duration, or `IGX-1705`
|
|
1307
|
+
* when no definition is applied.
|
|
1308
|
+
*/
|
|
1309
|
+
simulate(seconds: number): void;
|
|
1310
|
+
/**
|
|
1311
|
+
* Evaluates one spawn record at the current clock with the CPU evaluator, in world space — the
|
|
1312
|
+
* same arithmetic the shader runs, for tests and tools.
|
|
1313
|
+
*
|
|
1314
|
+
* @param slot - The record's slot in the ring.
|
|
1315
|
+
* @param out - Receives the state; allocate one with `createParticleState()`.
|
|
1316
|
+
* @returns `true` when the record is alive.
|
|
1317
|
+
*
|
|
1318
|
+
* @beta
|
|
1319
|
+
*/
|
|
1320
|
+
evaluate(slot: number, out?: ParticleState): boolean;
|
|
1321
|
+
/** Joins the service's live list. */
|
|
1322
|
+
onAttach(): void;
|
|
1323
|
+
/** Releases the GPU side, the budget, and the shared resources. */
|
|
1324
|
+
onDetach(): void;
|
|
1325
|
+
/**
|
|
1326
|
+
* One frame of emission. The `Update` system calls it.
|
|
1327
|
+
*
|
|
1328
|
+
* @param dt - The frame's scaled delta, or `0` while the app is paused.
|
|
1329
|
+
*
|
|
1330
|
+
* @internal
|
|
1331
|
+
*/
|
|
1332
|
+
tick(dt: number): void;
|
|
1333
|
+
/**
|
|
1334
|
+
* One frame of upload. The `PreRender` system calls it.
|
|
1335
|
+
*
|
|
1336
|
+
* @internal
|
|
1337
|
+
*/
|
|
1338
|
+
sync(): void;
|
|
1339
|
+
}
|
|
1340
|
+
//#endregion
|
|
1341
|
+
//#region src/settings.d.ts
|
|
1342
|
+
/**
|
|
1343
|
+
* The section name as it appears in `ignifx.config.ts`.
|
|
1344
|
+
*
|
|
1345
|
+
* @public
|
|
1346
|
+
*/
|
|
1347
|
+
export declare const PARTICLES_SETTINGS_SECTION = "particles";
|
|
1348
|
+
/**
|
|
1349
|
+
* The resolved `particles` settings section.
|
|
1350
|
+
*
|
|
1351
|
+
* @example
|
|
1352
|
+
* ```ts
|
|
1353
|
+
* // ignifx.config.ts
|
|
1354
|
+
* export default defineConfig({
|
|
1355
|
+
* particles: { maxParticles: 50_000, qualityScale: 1 },
|
|
1356
|
+
* });
|
|
1357
|
+
* ```
|
|
1358
|
+
*
|
|
1359
|
+
* @public
|
|
1360
|
+
*/
|
|
1361
|
+
interface ParticlesSettings {
|
|
1362
|
+
/**
|
|
1363
|
+
* The budget every `ParticleSystem`'s `capacity` is counted against. A system that would push the
|
|
1364
|
+
* total over it is clamped to what is left and `IGX-1702` is logged once.
|
|
1365
|
+
*/
|
|
1366
|
+
readonly maxParticles: number;
|
|
1367
|
+
/** A `0`–`1` multiplier on every emission rate and burst count, for settings screens. */
|
|
1368
|
+
readonly qualityScale: number;
|
|
1369
|
+
/**
|
|
1370
|
+
* The world gravity, in metres per second squared, a definition's `forces.gravityMultiplier`
|
|
1371
|
+
* scales. When `@ignifx/physics` is registered and this stays at its default, the physics
|
|
1372
|
+
* section's gravity is used instead.
|
|
1373
|
+
*/
|
|
1374
|
+
readonly gravity: Vec3Like;
|
|
1375
|
+
}
|
|
1376
|
+
/**
|
|
1377
|
+
* The values used for everything a project omits.
|
|
1378
|
+
*
|
|
1379
|
+
* @returns The default `particles` section.
|
|
1380
|
+
*
|
|
1381
|
+
* @public
|
|
1382
|
+
*/
|
|
1383
|
+
export declare function defaultParticlesSettings(): ParticlesSettings;
|
|
1384
|
+
/**
|
|
1385
|
+
* The schema the `particles` section is validated against.
|
|
1386
|
+
*
|
|
1387
|
+
* @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
|
|
1388
|
+
*
|
|
1389
|
+
* @public
|
|
1390
|
+
*/
|
|
1391
|
+
export declare function particlesSettingsSchema(): Schema;
|
|
1392
|
+
//#endregion
|
|
1393
|
+
//#region src/service/particles-service.d.ts
|
|
1394
|
+
/**
|
|
1395
|
+
* The diagnostics group name.
|
|
1396
|
+
*
|
|
1397
|
+
* @public
|
|
1398
|
+
*/
|
|
1399
|
+
export declare const PARTICLES_DIAGNOSTICS_GROUP = "particles";
|
|
1400
|
+
/**
|
|
1401
|
+
* The counters the group carries, in index order.
|
|
1402
|
+
*
|
|
1403
|
+
* @public
|
|
1404
|
+
*/
|
|
1405
|
+
export declare const PARTICLES_DIAGNOSTICS_COUNTERS: readonly string[];
|
|
1406
|
+
/**
|
|
1407
|
+
* The GPU-facing resources one definition's systems share.
|
|
1408
|
+
*
|
|
1409
|
+
* @public
|
|
1410
|
+
*/
|
|
1411
|
+
interface ParticleDefinitionResources {
|
|
1412
|
+
/** The generated program. */
|
|
1413
|
+
readonly source: string;
|
|
1414
|
+
/** The program's asset, loading until the shader adapter is in place. */
|
|
1415
|
+
readonly shader: AssetHandle<ShaderAsset>;
|
|
1416
|
+
/** The baked lookup texture. */
|
|
1417
|
+
readonly lut: AssetHandle<TextureAsset>;
|
|
1418
|
+
/** The renderer's texture, or `null` for the procedural disc. */
|
|
1419
|
+
readonly sheet: AssetHandle<TextureAsset> | null;
|
|
1420
|
+
/** The quad, or the primitive a `"mesh"` renderer draws. */
|
|
1421
|
+
readonly mesh: AssetHandle<MeshAsset>;
|
|
1422
|
+
/** The material every system builds its own copy from. */
|
|
1423
|
+
readonly materialDefinition: ShaderMaterialDefinition;
|
|
1424
|
+
/** The texture handles in the order `materialDefinition.textures` names them. */
|
|
1425
|
+
readonly textures: readonly AssetHandle<TextureAsset>[];
|
|
1426
|
+
}
|
|
1427
|
+
/**
|
|
1428
|
+
* The particles service, reached as `app.particles`.
|
|
1429
|
+
*
|
|
1430
|
+
* @example
|
|
1431
|
+
* ```ts
|
|
1432
|
+
* app.particles.qualityScale = 0.5; // half the emission everywhere, for a low setting
|
|
1433
|
+
* app.particles.systems.length; // how many ParticleSystem components are attached
|
|
1434
|
+
* ```
|
|
1435
|
+
*
|
|
1436
|
+
* @public
|
|
1437
|
+
*/
|
|
1438
|
+
export declare class ParticlesService {
|
|
1439
|
+
#private;
|
|
1440
|
+
/**
|
|
1441
|
+
* The budget every attached system's capacity is counted against. Raising it takes effect for
|
|
1442
|
+
* systems attached afterwards.
|
|
1443
|
+
*/
|
|
1444
|
+
maxParticles: number;
|
|
1445
|
+
/** A `0`–`1` multiplier on every rate and burst count, read each frame. */
|
|
1446
|
+
qualityScale: number;
|
|
1447
|
+
/**
|
|
1448
|
+
* Creates the service.
|
|
1449
|
+
*
|
|
1450
|
+
* @param app - The app it belongs to.
|
|
1451
|
+
* @param settings - The resolved `particles` section, options already merged.
|
|
1452
|
+
*/
|
|
1453
|
+
constructor(app: App, settings: ParticlesSettings);
|
|
1454
|
+
/**
|
|
1455
|
+
* The world gravity a definition's `gravityMultiplier` scales, in metres per second squared.
|
|
1456
|
+
*
|
|
1457
|
+
* @returns The service's own vector; assign to replace it.
|
|
1458
|
+
*/
|
|
1459
|
+
get gravity(): Vec3Like;
|
|
1460
|
+
/**
|
|
1461
|
+
* Copies a new world gravity in, so the caller's object is not retained.
|
|
1462
|
+
*
|
|
1463
|
+
* @param value - The gravity to copy.
|
|
1464
|
+
*/
|
|
1465
|
+
set gravity(value: Vec3Like);
|
|
1466
|
+
/**
|
|
1467
|
+
* Every attached `ParticleSystem`, in attach order.
|
|
1468
|
+
*
|
|
1469
|
+
* @returns The live list; iterate it without copying.
|
|
1470
|
+
*/
|
|
1471
|
+
get systems(): readonly ParticleSystem[];
|
|
1472
|
+
/**
|
|
1473
|
+
* How much of the budget attached systems hold.
|
|
1474
|
+
*
|
|
1475
|
+
* @returns The sum of every attached system's capacity.
|
|
1476
|
+
*/
|
|
1477
|
+
get capacityInUse(): number;
|
|
1478
|
+
/**
|
|
1479
|
+
* The `particles` diagnostics group, once the extension registered it.
|
|
1480
|
+
*
|
|
1481
|
+
* @returns The group, or `null` before registration.
|
|
1482
|
+
*/
|
|
1483
|
+
get counters(): DiagnosticsGroup | null;
|
|
1484
|
+
/**
|
|
1485
|
+
* Installs the counters group the extension registered.
|
|
1486
|
+
*
|
|
1487
|
+
* @param group - The group.
|
|
1488
|
+
*
|
|
1489
|
+
* @internal
|
|
1490
|
+
*/
|
|
1491
|
+
setCounters(group: DiagnosticsGroup): void;
|
|
1492
|
+
/**
|
|
1493
|
+
* Adds a system to the live list.
|
|
1494
|
+
*
|
|
1495
|
+
* @param system - The system.
|
|
1496
|
+
*
|
|
1497
|
+
* @internal
|
|
1498
|
+
*/
|
|
1499
|
+
attach(system: ParticleSystem): void;
|
|
1500
|
+
/**
|
|
1501
|
+
* Removes a system from the live list.
|
|
1502
|
+
*
|
|
1503
|
+
* @param system - The system.
|
|
1504
|
+
*
|
|
1505
|
+
* @internal
|
|
1506
|
+
*/
|
|
1507
|
+
detach(system: ParticleSystem): void;
|
|
1508
|
+
/**
|
|
1509
|
+
* Takes capacity out of the budget, clamping to what is left and logging `IGX-1702` when it had
|
|
1510
|
+
* to. Every renderer that spends the particle budget goes through here, `@ignifx/particles-2d`
|
|
1511
|
+
* included; pair each call with {@link ParticlesService.release}.
|
|
1512
|
+
*
|
|
1513
|
+
* @param entity - The entity's name, for the warning.
|
|
1514
|
+
* @param requested - The definition's capacity, in records.
|
|
1515
|
+
* @returns The capacity granted, at least one record.
|
|
1516
|
+
*
|
|
1517
|
+
* @beta
|
|
1518
|
+
*/
|
|
1519
|
+
reserve(entity: string, requested: number): number;
|
|
1520
|
+
/**
|
|
1521
|
+
* Gives capacity back to the budget.
|
|
1522
|
+
*
|
|
1523
|
+
* @param granted - What {@link ParticlesService.reserve} returned.
|
|
1524
|
+
*
|
|
1525
|
+
* @beta
|
|
1526
|
+
*/
|
|
1527
|
+
release(granted: number): void;
|
|
1528
|
+
/**
|
|
1529
|
+
* The shared resources of a definition, built on first use.
|
|
1530
|
+
*
|
|
1531
|
+
* @param asset - The particle asset.
|
|
1532
|
+
* @returns The resources; pair every call with {@link ParticlesService.releaseResources}.
|
|
1533
|
+
*
|
|
1534
|
+
* @internal
|
|
1535
|
+
*/
|
|
1536
|
+
acquireResources(asset: ParticleAsset): ParticleDefinitionResources;
|
|
1537
|
+
/**
|
|
1538
|
+
* Lets go of a definition's resources, disposing them with the last holder.
|
|
1539
|
+
*
|
|
1540
|
+
* @param asset - The particle asset.
|
|
1541
|
+
*
|
|
1542
|
+
* @internal
|
|
1543
|
+
*/
|
|
1544
|
+
releaseResources(asset: ParticleAsset): void;
|
|
1545
|
+
/**
|
|
1546
|
+
* Reports, once per definition, that its shader failed to load.
|
|
1547
|
+
*
|
|
1548
|
+
* @param asset - The particle asset.
|
|
1549
|
+
* @param message - The failure.
|
|
1550
|
+
*
|
|
1551
|
+
* @internal
|
|
1552
|
+
*/
|
|
1553
|
+
reportShaderFailure(asset: ParticleAsset, message: string): void;
|
|
1554
|
+
/**
|
|
1555
|
+
* An identity matrix slab at least `capacity` instances long, shared by every renderer: the
|
|
1556
|
+
* particle shader never reads the instance matrices, so one read-only slab serves all.
|
|
1557
|
+
*
|
|
1558
|
+
* @param capacity - How many instances the caller needs.
|
|
1559
|
+
* @returns The slab.
|
|
1560
|
+
*
|
|
1561
|
+
* @internal
|
|
1562
|
+
*/
|
|
1563
|
+
identitySlab(capacity: number): Float32Array;
|
|
1564
|
+
/**
|
|
1565
|
+
* Builds a system's own material from a definition's shared resources.
|
|
1566
|
+
*
|
|
1567
|
+
* @param resources - The shared resources.
|
|
1568
|
+
* @returns The material handle, with one holder — the caller.
|
|
1569
|
+
*
|
|
1570
|
+
* @internal
|
|
1571
|
+
*/
|
|
1572
|
+
createMaterial(resources: ParticleDefinitionResources): AssetHandle<MaterialAsset>;
|
|
1573
|
+
/** Releases every shared resource. The extension calls it on dispose. */
|
|
1574
|
+
dispose(): void;
|
|
1575
|
+
}
|
|
1576
|
+
//#endregion
|
|
1577
|
+
//#region src/augmentation.d.ts
|
|
1578
|
+
declare module "@ignifx/core" {
|
|
1579
|
+
interface App {
|
|
1580
|
+
/**
|
|
1581
|
+
* Particles (`docs/plan/2026-09-terrain-particles-shaders.md` §4.3): the budget, the quality
|
|
1582
|
+
* multiplier, the gravity, the counters, and the live list of `ParticleSystem` components.
|
|
1583
|
+
*/
|
|
1584
|
+
readonly particles: ParticlesService;
|
|
1585
|
+
}
|
|
1586
|
+
}
|
|
1587
|
+
//#endregion
|
|
1588
|
+
//#region src/assets/loader.d.ts
|
|
1589
|
+
/**
|
|
1590
|
+
* Builds the loader for `.particles.json` addresses.
|
|
1591
|
+
*
|
|
1592
|
+
* @returns The loader to register with `ctx.registerAssetLoader`.
|
|
1593
|
+
*
|
|
1594
|
+
* @example
|
|
1595
|
+
* ```ts
|
|
1596
|
+
* ctx.registerAssetLoader(createParticleLoader());
|
|
1597
|
+
* ```
|
|
1598
|
+
*
|
|
1599
|
+
* @public
|
|
1600
|
+
*/
|
|
1601
|
+
export declare function createParticleLoader(): AssetLoader<ParticleAsset>;
|
|
1602
|
+
/**
|
|
1603
|
+
* Publishes a definition built in code as a `particles` asset, so a `ParticleSystem`'s `definition`
|
|
1604
|
+
* field can hold it without a file. A `renderer.texture` starts loading here; the system draws the
|
|
1605
|
+
* procedural disc until it arrives. The handle has one holder, the caller.
|
|
1606
|
+
*
|
|
1607
|
+
* @param app - The app whose asset service publishes it.
|
|
1608
|
+
* @param definition - The definition, from {@link defineParticles} or a preset.
|
|
1609
|
+
* @param name - A human-readable name for diagnostics; defaults to `"particles"`.
|
|
1610
|
+
* @returns The handle, already loaded.
|
|
1611
|
+
*
|
|
1612
|
+
* @example
|
|
1613
|
+
* ```ts
|
|
1614
|
+
* const fire = particleAssetFromDefinition(app, particleDefinition("fire"));
|
|
1615
|
+
* campfire.addComponent(ParticleSystem, { definition: fire });
|
|
1616
|
+
* ```
|
|
1617
|
+
*
|
|
1618
|
+
* @public
|
|
1619
|
+
*/
|
|
1620
|
+
export declare function particleAssetFromDefinition(app: App, definition: ParticleDefinition, name?: string): AssetHandle<ParticleAsset>;
|
|
1621
|
+
//#endregion
|
|
1622
|
+
//#region src/definition/define-particles.d.ts
|
|
1623
|
+
/**
|
|
1624
|
+
* Fills in the defaults of a particle document, checks every rule the evaluators rely on, and bakes
|
|
1625
|
+
* its curves and gradients into the lookup rows both hosts sample.
|
|
1626
|
+
*
|
|
1627
|
+
* @param input - The document, as authored.
|
|
1628
|
+
* @param address - What to name in an error; defaults to `"<inline>"`.
|
|
1629
|
+
* @returns The complete, frozen definition.
|
|
1630
|
+
* @throws IgnifxError with code `IGX-1701`, naming the offending path, when the document is not
|
|
1631
|
+
* readable.
|
|
1632
|
+
*
|
|
1633
|
+
* @example
|
|
1634
|
+
* ```ts
|
|
1635
|
+
* const sparks = defineParticles({
|
|
1636
|
+
* main: { capacity: 200, duration: 1, looping: false },
|
|
1637
|
+
* emission: { rateOverTime: 0, bursts: [{ time: 0, count: 120 }] },
|
|
1638
|
+
* start: { lifetime: { min: 0.4, max: 1 }, speed: { min: 3, max: 6 }, size: 0.04 },
|
|
1639
|
+
* forces: { gravityMultiplier: 1, drag: 0.5 },
|
|
1640
|
+
* renderer: { mode: "stretched", blend: "additive" },
|
|
1641
|
+
* });
|
|
1642
|
+
* ```
|
|
1643
|
+
*
|
|
1644
|
+
* @public
|
|
1645
|
+
*/
|
|
1646
|
+
export declare function defineParticles(input: ParticleDefinitionInput, address?: string): ParticleDefinition;
|
|
1647
|
+
//#endregion
|
|
1648
|
+
//#region src/definition/presets/index.d.ts
|
|
1649
|
+
/**
|
|
1650
|
+
* Every preset name, in the order the documentation lists them.
|
|
1651
|
+
*
|
|
1652
|
+
* @public
|
|
1653
|
+
*/
|
|
1654
|
+
export declare const PARTICLE_PRESETS: readonly ["fire", "smoke", "sparks", "explosion", "dust", "sparkle", "rain", "snow", "leaves"];
|
|
1655
|
+
/**
|
|
1656
|
+
* The union of {@link PARTICLE_PRESETS}.
|
|
1657
|
+
*
|
|
1658
|
+
* @public
|
|
1659
|
+
*/
|
|
1660
|
+
type ParticlePreset = (typeof PARTICLE_PRESETS)[number];
|
|
1661
|
+
/**
|
|
1662
|
+
* A recursively optional view of a type: what an override of a preset looks like.
|
|
1663
|
+
*
|
|
1664
|
+
* @typeParam T - The type being made optional.
|
|
1665
|
+
*
|
|
1666
|
+
* @public
|
|
1667
|
+
*/
|
|
1668
|
+
type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? { readonly [K in keyof T]?: DeepPartial<T[K]>; } : T;
|
|
1669
|
+
/**
|
|
1670
|
+
* The document a preset starts from, before any override.
|
|
1671
|
+
*
|
|
1672
|
+
* @param name - The preset.
|
|
1673
|
+
* @returns A fresh copy of the authored document.
|
|
1674
|
+
* @throws IgnifxError with code `IGX-1704` for a name that is not a preset.
|
|
1675
|
+
*
|
|
1676
|
+
* @public
|
|
1677
|
+
*/
|
|
1678
|
+
export declare function particlePresetInput(name: ParticlePreset): ParticleDefinitionInput;
|
|
1679
|
+
/**
|
|
1680
|
+
* A preset, with any part of it overridden, as a complete definition. An object override merges key
|
|
1681
|
+
* by key; an array or a primitive replaces the whole value.
|
|
1682
|
+
*
|
|
1683
|
+
* @param name - The preset.
|
|
1684
|
+
* @param overrides - What to change.
|
|
1685
|
+
* @returns The definition, validated and baked.
|
|
1686
|
+
* @throws IgnifxError with code `IGX-1704` for an unknown preset, or `IGX-1701` when the overrides
|
|
1687
|
+
* make the document invalid.
|
|
1688
|
+
*
|
|
1689
|
+
* @example
|
|
1690
|
+
* ```ts
|
|
1691
|
+
* const bigFire = particleDefinition("fire", { start: { size: { min: 0.8, max: 1.2 } } });
|
|
1692
|
+
* ```
|
|
1693
|
+
*
|
|
1694
|
+
* @public
|
|
1695
|
+
*/
|
|
1696
|
+
export declare function particleDefinition(name: ParticlePreset, overrides?: DeepPartial<ParticleDefinitionInput>): ParticleDefinition;
|
|
1697
|
+
//#endregion
|
|
1698
|
+
//#region src/definition/values.d.ts
|
|
1699
|
+
/**
|
|
1700
|
+
* Evaluates a cubic Hermite curve at `t`, clamping to the end keys outside the key range
|
|
1701
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §3: keys are
|
|
1702
|
+
* `[time, value, inTangent, outTangent]`).
|
|
1703
|
+
*
|
|
1704
|
+
* @param curve - The curve; its keys must be sorted by time and non-empty.
|
|
1705
|
+
* @param t - Where to evaluate.
|
|
1706
|
+
* @returns The value; `0` for a curve with no keys.
|
|
1707
|
+
*
|
|
1708
|
+
* @public
|
|
1709
|
+
*/
|
|
1710
|
+
export declare function evaluateCurve(curve: CurveValue, t: number): number;
|
|
1711
|
+
/**
|
|
1712
|
+
* Bakes a curve into {@link LOOKUP_SAMPLES} samples over `[0, 1]`.
|
|
1713
|
+
*
|
|
1714
|
+
* @param curve - The curve.
|
|
1715
|
+
* @returns The samples; sample `i` is the curve at `i / 63`.
|
|
1716
|
+
*
|
|
1717
|
+
* @public
|
|
1718
|
+
*/
|
|
1719
|
+
export declare function bakeCurve(curve: CurveValue): Float32Array;
|
|
1720
|
+
/**
|
|
1721
|
+
* Evaluates a gradient at `t` by linear interpolation between stops, clamping outside them.
|
|
1722
|
+
*
|
|
1723
|
+
* @param stops - The stops, sorted by time and non-empty.
|
|
1724
|
+
* @param t - Where to evaluate.
|
|
1725
|
+
* @param out - Receives the sRGB colour.
|
|
1726
|
+
* @returns `out`.
|
|
1727
|
+
*
|
|
1728
|
+
* @public
|
|
1729
|
+
*/
|
|
1730
|
+
export declare function evaluateGradient(stops: readonly GradientStop[], t: number, out: Float32Array): Float32Array;
|
|
1731
|
+
/**
|
|
1732
|
+
* Bakes a gradient into {@link LOOKUP_SAMPLES} RGBA samples.
|
|
1733
|
+
*
|
|
1734
|
+
* @param stops - The stops.
|
|
1735
|
+
* @returns `LOOKUP_SAMPLES * 4` floats, sRGB.
|
|
1736
|
+
*
|
|
1737
|
+
* @public
|
|
1738
|
+
*/
|
|
1739
|
+
export declare function bakeGradient(stops: readonly GradientStop[]): Float32Array;
|
|
1740
|
+
/**
|
|
1741
|
+
* Samples a baked scalar row with the linear rule both evaluators share: `x = t * 63`, then a lerp
|
|
1742
|
+
* between samples `floor(x)` and `floor(x) + 1`.
|
|
1743
|
+
*
|
|
1744
|
+
* @param samples - A row of {@link LOOKUP_SAMPLES} floats.
|
|
1745
|
+
* @param t - The normalized time, clamped to `[0, 1]`.
|
|
1746
|
+
* @returns The interpolated value.
|
|
1747
|
+
*
|
|
1748
|
+
* @public
|
|
1749
|
+
*/
|
|
1750
|
+
export declare function sampleRow(samples: Float32Array, t: number): number;
|
|
1751
|
+
/**
|
|
1752
|
+
* The smallest value a scalar can produce: the constant, the range's `min`, or the curve's minimum.
|
|
1753
|
+
*
|
|
1754
|
+
* @param value - The scalar.
|
|
1755
|
+
* @returns The minimum.
|
|
1756
|
+
*
|
|
1757
|
+
* @public
|
|
1758
|
+
*/
|
|
1759
|
+
export declare function scalarMin(value: ScalarValue): number;
|
|
1760
|
+
/**
|
|
1761
|
+
* The largest value a scalar can produce.
|
|
1762
|
+
*
|
|
1763
|
+
* @param value - The scalar.
|
|
1764
|
+
* @returns The maximum.
|
|
1765
|
+
*
|
|
1766
|
+
* @public
|
|
1767
|
+
*/
|
|
1768
|
+
export declare function scalarMax(value: ScalarValue): number;
|
|
1769
|
+
/**
|
|
1770
|
+
* Resolves a scalar at spawn: the constant, a pick inside the range by `unit`, or the curve sampled
|
|
1771
|
+
* at `t` (the normalized position in the emission cycle).
|
|
1772
|
+
*
|
|
1773
|
+
* @param value - The scalar.
|
|
1774
|
+
* @param unit - A uniform random number in `[0, 1)`.
|
|
1775
|
+
* @param t - The normalized cycle time, for a curve.
|
|
1776
|
+
* @returns The resolved number.
|
|
1777
|
+
*
|
|
1778
|
+
* @public
|
|
1779
|
+
*/
|
|
1780
|
+
export declare function resolveScalar(value: ScalarValue, unit: number, t: number): number;
|
|
1781
|
+
/**
|
|
1782
|
+
* Whether a scalar is a constant `1`, so a module can skip it entirely.
|
|
1783
|
+
*
|
|
1784
|
+
* @param value - The scalar.
|
|
1785
|
+
* @returns `true` for a constant equal to one.
|
|
1786
|
+
*
|
|
1787
|
+
* @public
|
|
1788
|
+
*/
|
|
1789
|
+
export declare function isUnitScalar(value: ScalarValue): boolean;
|
|
1790
|
+
/**
|
|
1791
|
+
* The colour a random or constant start colour resolves to for one particle, in sRGB, without
|
|
1792
|
+
* allocating. A gradient start colour samples at `t`.
|
|
1793
|
+
*
|
|
1794
|
+
* @param value - The colour value.
|
|
1795
|
+
* @param unit - A uniform random number in `[0, 1)`; picks between `min` and `max`.
|
|
1796
|
+
* @param t - The normalized cycle time, for a gradient.
|
|
1797
|
+
* @param out - Receives `r, g, b, a`.
|
|
1798
|
+
* @returns `out`.
|
|
1799
|
+
*
|
|
1800
|
+
* @public
|
|
1801
|
+
*/
|
|
1802
|
+
export declare function resolveColor(value: ColorValue, unit: number, t: number, out: Float32Array): Float32Array;
|
|
1803
|
+
/**
|
|
1804
|
+
* Decodes an sRGB channel to linear — the exact formula the generated WGSL uses, so the CPU
|
|
1805
|
+
* evaluator and the shader agree (`Color.srgbToLinear` in core is the same function; it is
|
|
1806
|
+
* restated here so the two hosts can be read side by side).
|
|
1807
|
+
*
|
|
1808
|
+
* @param value - The sRGB channel in `0`–`1`.
|
|
1809
|
+
* @returns The linear channel.
|
|
1810
|
+
*
|
|
1811
|
+
* @public
|
|
1812
|
+
*/
|
|
1813
|
+
export declare function srgbToLinear(value: number): number;
|
|
1814
|
+
//#endregion
|
|
1815
|
+
//#region src/emitter/pcg3d.d.ts
|
|
1816
|
+
/**
|
|
1817
|
+
* Hashes three 32-bit words into three others, bit-identically to the WGSL `pcg3d`.
|
|
1818
|
+
*
|
|
1819
|
+
* @param x - The first lane; any number, wrapped to `u32`.
|
|
1820
|
+
* @param y - The second lane.
|
|
1821
|
+
* @param z - The third lane.
|
|
1822
|
+
* @param out - Receives the three hashed words.
|
|
1823
|
+
* @returns `out`.
|
|
1824
|
+
*
|
|
1825
|
+
* @beta
|
|
1826
|
+
*/
|
|
1827
|
+
export declare function pcg3d(x: number, y: number, z: number, out: Uint32Array): Uint32Array;
|
|
1828
|
+
/**
|
|
1829
|
+
* Turns a hashed word into a unit float in `[0, 1)` — the same `f32(h) * 2^-32` the shader uses.
|
|
1830
|
+
*
|
|
1831
|
+
* @param word - A `u32`.
|
|
1832
|
+
* @returns The unit float.
|
|
1833
|
+
*
|
|
1834
|
+
* @beta
|
|
1835
|
+
*/
|
|
1836
|
+
export declare function hashToUnit(word: number): number;
|
|
1837
|
+
/**
|
|
1838
|
+
* The three unit floats every per-particle derivation reads from a record's `seed`: the start
|
|
1839
|
+
* colour pick, the angular speed pick, and the sheet's random frame.
|
|
1840
|
+
*
|
|
1841
|
+
* @param seed - The record's `seed` word.
|
|
1842
|
+
* @param out - Receives three floats in `[0, 1)`.
|
|
1843
|
+
* @param scratch - Three words of scratch space.
|
|
1844
|
+
* @returns `out`.
|
|
1845
|
+
*
|
|
1846
|
+
* @beta
|
|
1847
|
+
*/
|
|
1848
|
+
export declare function particleUnits(seed: number, out: Float32Array, scratch: Uint32Array): Float32Array;
|
|
1849
|
+
/**
|
|
1850
|
+
* The `seed` word a record gets from the system seed and its index.
|
|
1851
|
+
*
|
|
1852
|
+
* @param systemSeed - The system's seed.
|
|
1853
|
+
* @param index - The record's index since `play()`.
|
|
1854
|
+
* @param scratch - Three words of scratch space.
|
|
1855
|
+
* @returns The record seed.
|
|
1856
|
+
*
|
|
1857
|
+
* @beta
|
|
1858
|
+
*/
|
|
1859
|
+
export declare function recordSeed(systemSeed: number, index: number, scratch: Uint32Array): number;
|
|
1860
|
+
/**
|
|
1861
|
+
* A deterministic stream of unit floats for the emission scheduler, drawn from `pcg3d` over a
|
|
1862
|
+
* counter so two systems with the same seed and the same frame deltas roll the same numbers.
|
|
1863
|
+
*
|
|
1864
|
+
* @beta
|
|
1865
|
+
*/
|
|
1866
|
+
export declare class EmitterRandom {
|
|
1867
|
+
#private;
|
|
1868
|
+
/**
|
|
1869
|
+
* Creates a stream.
|
|
1870
|
+
*
|
|
1871
|
+
* @param seed - The seed to start from.
|
|
1872
|
+
*/
|
|
1873
|
+
constructor(seed: number);
|
|
1874
|
+
/**
|
|
1875
|
+
* The seed the stream runs on.
|
|
1876
|
+
*
|
|
1877
|
+
* @returns The seed.
|
|
1878
|
+
*/
|
|
1879
|
+
get seed(): number;
|
|
1880
|
+
/**
|
|
1881
|
+
* Restarts the stream from a seed.
|
|
1882
|
+
*
|
|
1883
|
+
* @param seed - The new seed.
|
|
1884
|
+
*/
|
|
1885
|
+
reseed(seed: number): void;
|
|
1886
|
+
/**
|
|
1887
|
+
* The next unit float in `[0, 1)`.
|
|
1888
|
+
*
|
|
1889
|
+
* @returns The number.
|
|
1890
|
+
*/
|
|
1891
|
+
next(): number;
|
|
1892
|
+
}
|
|
1893
|
+
//#endregion
|
|
1894
|
+
//#region src/emitter/shapes.d.ts
|
|
1895
|
+
/**
|
|
1896
|
+
* Precomputed data a `"mesh"` shape samples from: the cumulative area of its triangles.
|
|
1897
|
+
*
|
|
1898
|
+
* @beta
|
|
1899
|
+
*/
|
|
1900
|
+
export declare class MeshShapeTable {
|
|
1901
|
+
/** Cumulative areas, one per triangle, ending at the total. */
|
|
1902
|
+
readonly cumulative: Float32Array;
|
|
1903
|
+
/** The triangle soup, nine floats per triangle. */
|
|
1904
|
+
readonly vertices: Float32Array;
|
|
1905
|
+
/**
|
|
1906
|
+
* Builds the table.
|
|
1907
|
+
*
|
|
1908
|
+
* @param vertices - Nine floats per triangle.
|
|
1909
|
+
*/
|
|
1910
|
+
constructor(vertices: Float32Array);
|
|
1911
|
+
/**
|
|
1912
|
+
* The total surface area.
|
|
1913
|
+
*
|
|
1914
|
+
* @returns The area.
|
|
1915
|
+
*/
|
|
1916
|
+
get area(): number;
|
|
1917
|
+
}
|
|
1918
|
+
/**
|
|
1919
|
+
* Samples a start position and direction from a shape.
|
|
1920
|
+
*
|
|
1921
|
+
* @param shape - The shape module.
|
|
1922
|
+
* @param rng - The emitter's random stream.
|
|
1923
|
+
* @param mesh - The triangle table, for a `"mesh"` shape; ignored otherwise.
|
|
1924
|
+
* @param position - Receives the local position.
|
|
1925
|
+
* @param direction - Receives the unit direction.
|
|
1926
|
+
*
|
|
1927
|
+
* @beta
|
|
1928
|
+
*/
|
|
1929
|
+
export declare function sampleShape(shape: ParticleShape, rng: EmitterRandom, mesh: MeshShapeTable | null, position: Float32Array, direction: Float32Array): void;
|
|
1930
|
+
//#endregion
|
|
1931
|
+
//#region src/errors.d.ts
|
|
1932
|
+
/**
|
|
1933
|
+
* Every diagnostic code `@ignifx/particles` can throw or log, keyed by an intention-revealing name
|
|
1934
|
+
* so call sites read as prose and the compiler catches typos (coding standards §5.2).
|
|
1935
|
+
*
|
|
1936
|
+
* @example
|
|
1937
|
+
* ```ts
|
|
1938
|
+
* throw particlesError(ParticlesErrorCode.invalidParticlesFile, "fire.particles.json declares no main.", {
|
|
1939
|
+
* context: { file: "fire.particles.json", reason: "main is missing" },
|
|
1940
|
+
* });
|
|
1941
|
+
* ```
|
|
1942
|
+
*
|
|
1943
|
+
* @public
|
|
1944
|
+
*/
|
|
1945
|
+
export declare const ParticlesErrorCode: {
|
|
1946
|
+
/** A `.particles.json` document, or a `defineParticles` input, is not an `ignifx.particles` document this build can read. */
|
|
1947
|
+
readonly invalidParticlesFile: "IGX-1701";
|
|
1948
|
+
/** A `ParticleSystem` asked for more capacity than the `app.particles.maxParticles` budget has left; it was clamped. */
|
|
1949
|
+
readonly budgetExceeded: "IGX-1702";
|
|
1950
|
+
/** A second `particles()` extension was registered on one app. */
|
|
1951
|
+
readonly duplicateExtension: "IGX-1703";
|
|
1952
|
+
/** `particleDefinition` named a preset that does not exist. */
|
|
1953
|
+
readonly unknownPreset: "IGX-1704";
|
|
1954
|
+
/** A `ParticleSystem` method that needs a definition ran without one. */
|
|
1955
|
+
readonly noDefinition: "IGX-1705";
|
|
1956
|
+
/** The generated particle shader failed to load or to build a material. */
|
|
1957
|
+
readonly shaderFailed: "IGX-1706";
|
|
1958
|
+
/** `emit`, `simulate`, or a value argument was not a finite number in range. */
|
|
1959
|
+
readonly invalidArgument: "IGX-1707";
|
|
1960
|
+
};
|
|
1961
|
+
/**
|
|
1962
|
+
* The union of the codes the `ParticlesErrorCode` table declares.
|
|
1963
|
+
*
|
|
1964
|
+
* @public
|
|
1965
|
+
*/
|
|
1966
|
+
export type ParticlesErrorCode = (typeof ParticlesErrorCode)[keyof typeof ParticlesErrorCode];
|
|
1967
|
+
/**
|
|
1968
|
+
* The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
|
|
1969
|
+
* Context keys appear in braces, matching the core table's convention.
|
|
1970
|
+
*
|
|
1971
|
+
* @public
|
|
1972
|
+
*/
|
|
1973
|
+
export declare const PARTICLES_ERROR_MESSAGES: Readonly<Record<string, string>>;
|
|
1974
|
+
/**
|
|
1975
|
+
* Options accepted by {@link particlesError}: the same subset of `IgnifxErrorOptions` this package
|
|
1976
|
+
* uses.
|
|
1977
|
+
*
|
|
1978
|
+
* @public
|
|
1979
|
+
*/
|
|
1980
|
+
interface ParticlesErrorOptions {
|
|
1981
|
+
/** Identifiers that locate the failure. */
|
|
1982
|
+
readonly context?: ErrorContext;
|
|
1983
|
+
/** One sentence telling the developer what to do about it. */
|
|
1984
|
+
readonly hint?: string;
|
|
1985
|
+
/** The failure being wrapped, when there is one. */
|
|
1986
|
+
readonly cause?: unknown;
|
|
1987
|
+
}
|
|
1988
|
+
/**
|
|
1989
|
+
* Builds an `IgnifxError` carrying one of this package's codes.
|
|
1990
|
+
*
|
|
1991
|
+
* @param code - The code from the `ParticlesErrorCode` table.
|
|
1992
|
+
* @param message - The actionable development sentence.
|
|
1993
|
+
* @param options - Context identifiers, a remedy hint, and the wrapped cause.
|
|
1994
|
+
* @returns The error to throw or to reject with.
|
|
1995
|
+
*
|
|
1996
|
+
* @example
|
|
1997
|
+
* ```ts
|
|
1998
|
+
* throw particlesError(ParticlesErrorCode.unknownPreset, "lava is not a particle preset.", {
|
|
1999
|
+
* context: { preset: "lava" },
|
|
2000
|
+
* });
|
|
2001
|
+
* ```
|
|
2002
|
+
*
|
|
2003
|
+
* @public
|
|
2004
|
+
*/
|
|
2005
|
+
export declare function particlesError(code: ParticlesErrorCode, message: string, options?: ParticlesErrorOptions): IgnifxError;
|
|
2006
|
+
//#endregion
|
|
2007
|
+
//#region src/evaluate/noise.d.ts
|
|
2008
|
+
/**
|
|
2009
|
+
* One scalar of lattice gradient noise at a point.
|
|
2010
|
+
*
|
|
2011
|
+
* @param x - The sample position.
|
|
2012
|
+
* @param y - The sample position.
|
|
2013
|
+
* @param z - The sample position.
|
|
2014
|
+
* @param scratch - Three words of scratch space.
|
|
2015
|
+
* @returns The noise value, in roughly `[-1, 1]`.
|
|
2016
|
+
*
|
|
2017
|
+
* @beta
|
|
2018
|
+
*/
|
|
2019
|
+
export declare function gradientNoise(x: number, y: number, z: number, scratch: Uint32Array): number;
|
|
2020
|
+
/**
|
|
2021
|
+
* Three decorrelated noise channels at a point, summed over one or two octaves.
|
|
2022
|
+
*
|
|
2023
|
+
* @param x - The sample position.
|
|
2024
|
+
* @param y - The sample position.
|
|
2025
|
+
* @param z - The sample position.
|
|
2026
|
+
* @param octaves - `1` or `2`.
|
|
2027
|
+
* @param scratch - Three words of scratch space.
|
|
2028
|
+
* @param out - Receives the three channels.
|
|
2029
|
+
* @returns `out`.
|
|
2030
|
+
*
|
|
2031
|
+
* @beta
|
|
2032
|
+
*/
|
|
2033
|
+
export declare function noise3(x: number, y: number, z: number, octaves: number, scratch: Uint32Array, out: Float32Array): Float32Array;
|
|
2034
|
+
//#endregion
|
|
2035
|
+
//#region src/extension.d.ts
|
|
2036
|
+
/**
|
|
2037
|
+
* What `particles()` accepts. Every field overrides the matching `particles` settings section value.
|
|
2038
|
+
*
|
|
2039
|
+
* @public
|
|
2040
|
+
*/
|
|
2041
|
+
interface ParticlesOptions {
|
|
2042
|
+
/** The particle budget every system's capacity is counted against. */
|
|
2043
|
+
readonly maxParticles?: number;
|
|
2044
|
+
/** A `0`–`1` multiplier on every emission rate and burst count. */
|
|
2045
|
+
readonly qualityScale?: number;
|
|
2046
|
+
/** The world gravity a `gravityMultiplier` scales. */
|
|
2047
|
+
readonly gravity?: Vec3Like;
|
|
2048
|
+
}
|
|
2049
|
+
/**
|
|
2050
|
+
* The `@ignifx/particles` extension factory.
|
|
2051
|
+
*
|
|
2052
|
+
* @param options - Overrides for the `particles` settings section.
|
|
2053
|
+
* @returns The extension descriptor to pass to `createApp`.
|
|
2054
|
+
*
|
|
2055
|
+
* @example
|
|
2056
|
+
* ```ts
|
|
2057
|
+
* const app = await createApp({ canvas, extensions: [particles({ maxParticles: 50_000 })] });
|
|
2058
|
+
* ```
|
|
2059
|
+
*
|
|
2060
|
+
* @public
|
|
2061
|
+
*/
|
|
2062
|
+
export declare const particles: (options?: ParticlesOptions) => Extension;
|
|
2063
|
+
//#endregion
|
|
2064
|
+
//#region src/gpu/particle-systems.d.ts
|
|
2065
|
+
/**
|
|
2066
|
+
* Advances every system's emitter core by the frame's scaled delta, or by nothing while the app is
|
|
2067
|
+
* paused. Runs late in `Update` so a script's `emit()` is drawn in the same frame.
|
|
2068
|
+
*
|
|
2069
|
+
* @beta
|
|
2070
|
+
*/
|
|
2071
|
+
export declare class ParticleUpdateSystem implements System {
|
|
2072
|
+
#private;
|
|
2073
|
+
/** The name diagnostics and error reports use. */
|
|
2074
|
+
readonly name: string;
|
|
2075
|
+
/**
|
|
2076
|
+
* Creates the system.
|
|
2077
|
+
*
|
|
2078
|
+
* @param service - The service whose list it walks.
|
|
2079
|
+
*/
|
|
2080
|
+
constructor(service: ParticlesService);
|
|
2081
|
+
/**
|
|
2082
|
+
* Runs emission for one frame.
|
|
2083
|
+
*
|
|
2084
|
+
* @param ctx - The world, the clock, the phase, and the frame delta.
|
|
2085
|
+
*/
|
|
2086
|
+
update(ctx: SystemContext): void;
|
|
2087
|
+
}
|
|
2088
|
+
/**
|
|
2089
|
+
* Uploads every system's new records, writes its uniforms, bounds its draw count, and publishes the
|
|
2090
|
+
* `particles` counters. Runs in `PreRender` before core's render sync.
|
|
2091
|
+
*
|
|
2092
|
+
* @beta
|
|
2093
|
+
*/
|
|
2094
|
+
export declare class ParticleRenderSystem implements System {
|
|
2095
|
+
#private;
|
|
2096
|
+
/** The name diagnostics and error reports use. */
|
|
2097
|
+
readonly name: string;
|
|
2098
|
+
/**
|
|
2099
|
+
* Creates the system.
|
|
2100
|
+
*
|
|
2101
|
+
* @param service - The service whose list it walks.
|
|
2102
|
+
*/
|
|
2103
|
+
constructor(service: ParticlesService);
|
|
2104
|
+
/** Runs the upload for one frame. */
|
|
2105
|
+
update(): void;
|
|
2106
|
+
}
|
|
2107
|
+
//#endregion
|
|
2108
|
+
//#region src/gpu/wgsl.d.ts
|
|
2109
|
+
/**
|
|
2110
|
+
* Generates the WGSL program that draws a definition.
|
|
2111
|
+
*
|
|
2112
|
+
* @param definition - The definition.
|
|
2113
|
+
* @returns The whole `.wgsl` source, pragmas included, ready for the shader loader.
|
|
2114
|
+
*
|
|
2115
|
+
* @example
|
|
2116
|
+
* ```ts
|
|
2117
|
+
* const source = generateParticleWgsl(particleDefinition("fire"));
|
|
2118
|
+
* source.includes("@ignifx blend premultiplied"); // true
|
|
2119
|
+
* ```
|
|
2120
|
+
*
|
|
2121
|
+
* @beta
|
|
2122
|
+
*/
|
|
2123
|
+
export declare function generateParticleWgsl(definition: ParticleDefinition): string;
|
|
2124
|
+
/**
|
|
2125
|
+
* The `data:` address the generated program is published under, so the core shader loader — the
|
|
2126
|
+
* only path that also loads core's shader adapter — reads it with no file and no network. Two
|
|
2127
|
+
* definitions that generate the same program share one address, and so one `ShaderAsset`.
|
|
2128
|
+
*
|
|
2129
|
+
* @param source - The generated WGSL, which is ASCII.
|
|
2130
|
+
* @returns A `data:text/plain;base64,…` URL.
|
|
2131
|
+
*
|
|
2132
|
+
* @beta
|
|
2133
|
+
*/
|
|
2134
|
+
export declare function particleShaderAddress(source: string): string;
|
|
2135
|
+
//#endregion
|
|
2136
|
+
//#region src/file-schemas.d.ts
|
|
2137
|
+
/**
|
|
2138
|
+
* The `ignifx.particles` document schema.
|
|
2139
|
+
*
|
|
2140
|
+
* @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
|
|
2141
|
+
*
|
|
2142
|
+
* @public
|
|
2143
|
+
*/
|
|
2144
|
+
export declare function particlesFileSchema(): Schema;
|
|
2145
|
+
//#endregion
|
|
2146
|
+
//#region src/schemas.d.ts
|
|
2147
|
+
/**
|
|
2148
|
+
* Describes the `ignifx.particles` file format.
|
|
2149
|
+
*
|
|
2150
|
+
* @returns The record `pnpm docs:schemas` renders.
|
|
2151
|
+
*
|
|
2152
|
+
* @public
|
|
2153
|
+
*/
|
|
2154
|
+
export declare function describeParticlesFormat(): SchemaDescription;
|
|
2155
|
+
/**
|
|
2156
|
+
* Describes every component and settings section this package registers.
|
|
2157
|
+
*
|
|
2158
|
+
* @returns The record `pnpm docs:schemas` renders, keyed by schema id.
|
|
2159
|
+
*
|
|
2160
|
+
* @public
|
|
2161
|
+
*/
|
|
2162
|
+
export declare function describeSchemas(): Readonly<Record<string, SchemaDescription>>;
|
|
2163
|
+
//#endregion
|
|
2164
|
+
//#region src/version.d.ts
|
|
2165
|
+
/**
|
|
2166
|
+
* The `@ignifx/particles` version this build was cut from.
|
|
2167
|
+
*
|
|
2168
|
+
* @public
|
|
2169
|
+
*/
|
|
2170
|
+
export declare const VERSION = "0.2.1";
|
|
2171
|
+
//#endregion
|
|
2172
|
+
export type { ColorInput, ColorValue, ColorValueInput, DeepPartial, GradientStop, LookupRow, ParticleBlendMode, ParticleBurst, ParticleBurstInput, ParticleDefinition, ParticleDefinitionInput, ParticleDefinitionResources, ParticleEmission, ParticleEmissionInput, ParticleEmitFrom, ParticleEmitterCoreOptions, ParticleEvaluationInputs, ParticleForces, ParticleForcesInput, ParticleFrameMode, ParticleLookup, ParticleMain, ParticleMainInput, ParticleMeshName, ParticleNoise, ParticleOrbit, ParticleOverLifetime, ParticleOverLifetimeInput, ParticlePreset, ParticleRenderMode, ParticleRenderer, ParticleRendererInput, ParticleShape, ParticleShapeInput, ParticleShapeKind, ParticleSheet, ParticleSheetInput, ParticleSimulationSpace, ParticleStart, ParticleStartInput, ParticleState, ParticleStopOptions, ParticlesErrorOptions, ParticlesOptions, ParticlesSettings, RingCensus, ScalarValue, ScalarValueInput, UploadRange };
|
|
2173
|
+
//# sourceMappingURL=index.d.ts.map
|