@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.
@@ -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