babylon.quarks 0.26.0 → 0.27.0

package/dist/types/index.d.ts

@@ -1,14 +1,15 @@
-import { BaseTexture } from '@babylonjs/core/Materials/Textures/baseTexture';
-import { Texture } from '@babylonjs/core/Materials/Textures/texture';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { Scene } from '@babylonjs/core/scene';
-import { ShaderMaterial } from '@babylonjs/core/Materials/shaderMaterial';
-import { Color3 } from '@babylonjs/core/Maths/math.color';
-import { Vector3 as Vector3$1 } from '@babylonjs/core/Maths/math.vector';
-import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { Node } from '@babylonjs/core/node';
-import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
-import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { BaseTexture } from '@babylonjs/core/Materials/Textures/baseTexture.js';
+import { Texture } from '@babylonjs/core/Materials/Textures/texture.js';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
+import { DepthRenderer } from '@babylonjs/core/Rendering/depthRenderer.js';
+import { Scene } from '@babylonjs/core/scene.js';
+import { Camera } from '@babylonjs/core/Cameras/camera.js';
+import { Vector4 as Vector4$1, Vector3 as Vector3$1 } from '@babylonjs/core/Maths/math.vector.js';
+import { Effect } from '@babylonjs/core/Materials/effect.js';
+import { ShaderMaterial } from '@babylonjs/core/Materials/shaderMaterial.js';
+import { Color3 } from '@babylonjs/core/Maths/math.color.js';
+import { Mesh } from '@babylonjs/core/Meshes/mesh.js';
+import { Node } from '@babylonjs/core/node.js';
 
 declare class Vector2 {
     x: number;
@@ -549,6 +550,7 @@ interface RotationGenerator {
     toJSON(): FunctionJSON;
     clone(): RotationGenerator;
 }
+/** Reads a rotation generator; an unknown or missing type warns and gives a random rotation. */
 declare function RotationGeneratorFromJSON(json: FunctionJSON): RotationGenerator;
 
 /**
@@ -579,6 +581,7 @@ interface FunctionValueGenerator {
     toJSON(): FunctionJSON;
     clone(): FunctionValueGenerator;
 }
+/** Reads a value generator; an unknown or missing type warns and gives 0. */
 declare function ValueGeneratorFromJSON(json: FunctionJSON): FunctionValueGenerator | ValueGenerator;
 
 declare class AxisAngleGenerator implements RotationGenerator {
@@ -644,6 +647,10 @@ declare class ContinuousLinearFunction<T extends ObjectValueType<T> | number> {
     type: 'function';
     subType: 'Number' | 'Vector3' | 'Vector4' | 'Color';
     constructor(keys: Array<[T, number]>, subType: 'Number' | 'Vector3' | 'Vector4' | 'Color');
+    /**
+     * The key whose span holds `t`: -1 before the first key, the last key from its position on
+     * (so a `t` past 1 holds the final value, as the sampled table does).
+     */
     findKey(t: number): number;
     getStartX(index: number): number;
     getEndX(index: number): number;
@@ -738,6 +745,7 @@ declare class ConstantColor implements ColorGenerator {
     static fromJSON(json: FunctionJSON): ConstantColor;
     clone(): ColorGenerator;
 }
+/** Reads a colour generator; an unknown or missing type warns and gives opaque white. */
 declare function ColorGeneratorFromJSON(json: FunctionJSON): ColorRange | Gradient | RandomColor | RandomColorBetweenGradient | ConstantColor;
 
 declare class ConstantValue implements ValueGenerator {
@@ -774,8 +782,10 @@ interface Vector3Generator {
     toJSON(): FunctionJSON;
     clone(): Vector3Generator;
 }
+/** Reads a vector generator; an unknown or missing type warns and gives a zero vector. */
 declare function Vector3GeneratorFromJSON(json: FunctionJSON): Vector3Generator;
 
+/** Reads a value, rotation or vector generator; an unknown or missing type warns and gives 0. */
 declare function GeneratorFromJSON(json: FunctionJSON): FunctionValueGenerator | ValueGenerator | RotationGenerator | Vector3Generator;
 
 declare class IntervalValue implements ValueGenerator {
@@ -1004,7 +1014,7 @@ declare class ParticleStore {
     keepPreviousVelocity(): boolean;
     /**
      * Mirrors a freshly spawned particle's generator memory into the
-     * {@link memory} column, widening the column when this spawn used more
+     * {@link ParticleStore.memory | memory} column, widening the column when this spawn used more
      * slots than any before it.
      */
     recordMemory(row: number, memory: ReadonlyArray<unknown>): void;
@@ -1087,12 +1097,16 @@ interface BillBoardSettings {
 }
 interface TrailSettings {
     /**
-     * Start length of the trail.
+     * How many samples the trail keeps, rolled per particle at emission. The particle records one
+     * sample per simulation step, so in babylon.quarks, which steps at 60 Hz, 30 samples is half a
+     * second of travel. Defaults to 30 in babylon.quarks.
      * @type {ValueGenerator | FunctionValueGenerator}
      */
     startLength: ValueGenerator | FunctionValueGenerator;
     /**
-     * Whether to follow the local origin.
+     * Keep each particle where it was emitted relative to the emitter, carried by the emitter's
+     * transform instead of its own velocity, so the trail draws the emitter's motion (a weapon
+     * tip) rather than the particle's travel. Defaults to false.
      * @type {boolean}
      */
     followLocalOrigin: boolean;
@@ -1133,13 +1147,70 @@ interface TrailSettings {
      * @type {Vector3}
      */
     sideAxis?: Vector3;
-}
-interface MeshSettings {
     /**
-     * Rotation axis.
-     * @type {Vector3}
+     * Draw each segment between two recorded samples as this many more
+     * segments, along a curve through the samples (Niagara's ribbon
+     * tessellation), so a fast or sharply turning trail stays round instead
+     * of showing the corners between frames. A whole number from 0 (the
+     * default: straight segments) to 16. The curve passes through every
+     * sample: it smooths the trail without moving it.
+     * @type {number}
+     */
+    tessellation?: number;
+    /**
+     * How tightly a tessellated trail's curve is drawn between its samples
+     * (Niagara's curve tension): 0 (the default) a Catmull-Rom spline, rising
+     * toward 1 for straight segments.
+     * @type {number}
+     */
+    curveTension?: number;
+    /**
+     * How the texture's U runs along the ribbon (Unity's Texture Mode):
+     * - `'stretch'` (the default): once along the ribbon, by distance, so a fast stretch of the
+     *   trail shows more of the texture than a slow one.
+     * - `'distributePerSegment'`: once along the ribbon, each recorded segment an equal share
+     *   whatever its length (Niagara's Scaled Uniformly).
+     * - `'tile'`: repeated every world unit along the ribbon, scaled by `textureScale`
+     *   (Niagara's Tiling Distance). A sample keeps its U for as long as it lives, so the texture
+     *   stays put on the trail as the trail grows. The unit is the space the trail is recorded
+     *   in, scaled by the emitter for a local-space trail (as the width is).
+     * - `'repeatPerSegment'`: once per recorded segment.
+     *
+     * `uvFromHead` runs any of them from the particle back. The sprite sheet's cell is the
+     * texture's U range, so the repeating modes want a sheet of 1×1 (the default); on a larger
+     * sheet they run into the next cell.
+     * @type {TrailTextureMode}
+     */
+    textureMode?: TrailTextureMode;
+    /**
+     * Repeats of the texture along the ribbon (Unity's Texture Scale, Niagara's UV Scale): per
+     * world unit in `'tile'`, per recorded segment in `'repeatPerSegment'` and over the whole
+     * ribbon in the other modes. Finite and above 0; the default is 1. For repeats across the
+     * ribbon use the texture's own UV layout (`mapUV.tiling`).
+     * @type {number}
+     */
+    textureScale?: number;
+    /**
+     * A new sample is only recorded once the particle has moved this far from the last one, in
+     * the space the trail is recorded in; until then the last sample follows the particle
+     * (Unity's Min Vertex Distance). Keeps a slow or standing particle from filling its history
+     * with points on one spot, so the trail keeps its length in distance rather than in steps.
+     * 0, the default: a sample every simulation step.
+     * @type {number}
+     */
+    minVertexDistance?: number;
+    /**
+     * How long each recorded sample of the trail is kept, in seconds (Unity's Time): the ribbon
+     * reaches that far back in time, however many samples that is, up to `startLength`. Unset or
+     * 0, the default: samples are kept until the history is full, `startLength` samples. The
+     * `WidthOverLength` curve spans the samples kept.
+     * @type {number}
      */
-    rotationAxis?: Vector3;
+    lifetime?: number;
+}
+/** How a trail's texture runs along the ribbon, see {@link TrailSettings.textureMode}. */
+type TrailTextureMode = 'stretch' | 'tile' | 'distributePerSegment' | 'repeatPerSegment';
+interface MeshSettings {
     /**
      * Initial rotation around the X-axis.
      * @type {ValueGenerator | FunctionValueGenerator}
@@ -1208,6 +1279,12 @@ interface IParticleSystem {
      * @type {boolean}
      */
     onlyUsedByOther?: boolean;
+    /**
+     * Whether the system has been disposed. A disposed system takes no more particles, so a sub
+     * emitter aimed at it emits nothing.
+     * @type {boolean}
+     */
+    readonly isDisposed?: boolean;
     /**
      * Whether the ParticleSystem should be automatically disposed when it finishes emitting particles.
      * @type {string}
@@ -1427,6 +1504,14 @@ interface Particle extends IParticle {
      * @type {Vector3}
      */
     startSize: Vector3;
+    /**
+     * Counts the particles this object has held, when the implementation reuses particle objects:
+     * the system bumps it at every spawn. Something that keeps a reference to a particle, such as
+     * a sub emission following its parent, compares it to tell the particle it saw from a later
+     * one that took over the same object.
+     * @type {number}
+     */
+    serial?: number;
     reset(): void;
 }
 /**
@@ -1502,6 +1587,8 @@ declare class SpriteParticle implements Particle {
      * @type {Matrix4}
      */
     parentMatrix?: Matrix4;
+    /** See {@link Particle.serial}. */
+    serial?: number;
     /**
      * Initial speed of the particle, kept in the store's `startSpeed` column.
      * @type {number}
@@ -1658,6 +1745,8 @@ declare class TrailParticle implements Particle {
      * @type {Matrix4}
      */
     parentMatrix?: Matrix4;
+    /** See {@link Particle.serial}. */
+    serial?: number;
     /**
      * Initial speed of the particle, kept in the store's `startSpeed` column.
      * @type {number}
@@ -1728,7 +1817,8 @@ declare class TrailParticle implements Particle {
     get speedModifier(): number;
     set speedModifier(value: number);
     /**
-     * Length of the trail.
+     * How many samples the trail keeps, the capacity of the history below; `TrailSettings.startLength`
+     * rolls it at emission. 30, babylon.quarks's default, until then.
      * @type {number}
      */
     length: number;
@@ -1778,7 +1868,15 @@ declare class TrailParticle implements Particle {
      * axis (`TrailSettings.sideAxis`); see {@link ensureSideHistory}.
      */
     historySides: Float32Array;
-    /** Number of samples the ring buffers can hold. */
+    /** Ring buffer of the particle's age when each sample was recorded, 1 float per sample. */
+    historyAges: Float32Array;
+    /**
+     * Ring buffer of each sample's distance along the trail, 1 float per sample: the straight
+     * distances between the samples added up from the particle's first sample, in the space the
+     * positions are recorded in. See {@link measureHeadDistance}.
+     */
+    historyDistances: Float32Array;
+    /** Number of samples the ring buffers hold; the buffers themselves may be longer. */
     historyCapacity: number;
     /** Slot the next sample is written to. */
     historyHead: number;
@@ -1798,7 +1896,9 @@ declare class TrailParticle implements Particle {
     /** Re-points the vector views after the store grew its arrays. */
     rebind(): void;
     /**
-     * Allocates the trail ring buffers, reusing them when the capacity is unchanged.
+     * Sets how many samples the history holds and empties it. The ring buffers are only
+     * allocated when they are too short, so a particle re-emitted with a shorter or a random
+     * length keeps the buffers it has.
      * @param {number} capacity - Number of samples to hold.
      */
     ensureHistoryCapacity(capacity: number): void;
@@ -1812,10 +1912,25 @@ declare class TrailParticle implements Particle {
      */
     getHistoryIndex(i: number): number;
     /**
-     * Records the current state into the trail ring buffer, or retires the
-     * oldest sample once the particle is dead. Allocation free.
+     * Records the current state into the trail ring buffer as a new sample, or over the newest
+     * one with `replaceHead` (the head following the particle until it has moved far enough for
+     * a sample of its own, see `TrailSettings.minVertexDistance`). Once the particle is dead
+     * (`age >= life`) it drops the oldest sample instead, so the trail fades from the tail.
+     * Allocation free.
+     * @param replaceHead - Overwrite the newest sample rather than append one; appends when there is none.
+     * @param measureDistance - Set the sample's distance along the trail; a host that moves the sample
+     * after recording it passes false and calls {@link measureHeadDistance} itself.
+     */
+    update(replaceHead?: boolean, measureDistance?: boolean): void;
+    /**
+     * Sets the newest sample's distance along the trail: the sample before it plus the straight
+     * distance between the two, in the space the positions are recorded in; 0 for a trail's
+     * first sample. {@link update} does this; a host that moves the sample after recording it
+     * (babylon.quarks's world-space recording) calls it again.
      */
-    update(): void;
+    measureHeadDistance(): void;
+    /** Drops the oldest sample, the one the tail is drawn from, keeping the rest. */
+    dropOldest(): void;
     /**
      * Indicates if the particle has died.
      * @type {boolean}
@@ -1836,12 +1951,42 @@ type ParameterType = FieldType | 'self';
 type ParameterPair = [string, Array<ParameterType>];
 
 /**
- * Interface for particle behaviors.
- * a behavior is a function that modifies a particle's properties over time.
+ * A behavior changes particles over time; a particle system runs a list of
+ * them every simulation step. Each method is called by the host (the system
+ * that owns the behavior), in this order:
+ *
+ * 1. {@link initialize} once per particle, when it is emitted. The particle is
+ *    already in the system's pool, placed and given its start values by the
+ *    emitter shape, and converted to the simulation space; `particleSystem` is
+ *    the system it belongs to. A behavior that reads a per-particle random
+ *    sample starts its generators on `particle.memory` here.
+ * 2. {@link frameUpdate} once per step, before any particle is updated that
+ *    step, with the step's length. Per-step work (decomposing the emitter's
+ *    transform, advancing a time offset) belongs here.
+ * 3. {@link update} once per live particle, or {@link updateAll} once for the
+ *    whole pool when it is implemented. The particle's `age` is the age at the
+ *    start of the step; the host adds `delta` and integrates the velocity
+ *    after every behavior has run.
+ * 4. {@link reset} when the system restarts, before it emits again: state
+ *    accumulated across steps goes back to how it was before the first one.
+ *
+ * Randomness is drawn through `random()` from `quarks.core`'s `util/random`,
+ * never `Math.random`, so a host that runs its steps inside `setRandomSource`
+ * (or `withRandomSource`) with a seeded generator replays the same effect, as
+ * babylon.quarks does for a system with a `seed`. Any other state a behavior
+ * keeps must be derived from its settings, so a `clone()` or a saved and
+ * reloaded copy behaves the same.
+ *
+ * {@link toJSON} writes the behavior's settings as plain data, the `type` and
+ * every non-default field; `BehaviorTypes[type].loadJSON` reads it back. The
+ * `params` of that entry list the fields an editor shows.
  */
 interface Behavior {
+    /** The name the behavior is registered under in {@link BehaviorTypes}. */
     type: string;
+    /** Called once per particle when it is emitted; see the interface's description for when. */
     initialize(particle: Particle, particleSystem: IParticleSystem): void;
+    /** Called once per live particle per step, with the step's length in seconds. */
     update(particle: Particle, delta: number): void;
     /**
      * Optional bulk form of {@link update}, applied to `particles[0..count)`.
@@ -1850,15 +1995,19 @@ interface Behavior {
      * behavior type, which leaves it megamorphic: V8 can neither inline it nor
      * specialise the generator calls inside. A behavior that implements this
      * instead gets one call per frame and a loop it owns, where those calls are
-     * monomorphic. Implementations must skip dead particles exactly as the
-     * per-particle path does, and must produce identical results.
+     * monomorphic. Implementations must skip dead particles (`age >= life`)
+     * exactly as the per-particle path does, and must produce identical results.
      *
      * Behaviors that do not implement it keep working unchanged.
      */
     updateAll?(particles: Array<Particle>, count: number, delta: number): void;
+    /** Called once per step before the particles are updated, with the step's length in seconds. */
     frameUpdate(delta: number): void;
+    /** The behavior's settings as plain data, with its `type`; see the interface's description. */
     toJSON(): any;
+    /** A copy with the same settings that shares nothing mutable with this one. */
     clone(): Behavior;
+    /** Called when the system restarts: forget state accumulated across steps. */
     reset(): void;
 }
 interface BehaviorPlugin {
@@ -1870,22 +2019,63 @@ interface BehaviorPlugin {
 declare const BehaviorTypes: {
     [key: string]: BehaviorPlugin;
 };
+/**
+ * Reads a behavior. A type no plugin registered warns and gives `null`; the system loads without
+ * that behavior.
+ */
 declare function BehaviorFromJSON(json: any, particleSystem: IParticleSystem): Behavior | null;
 
+/**
+ * What {@link ApplyCollision} asks about the world: whether a particle at
+ * `position` has hit something, and if so which way the surface faces.
+ */
 interface PhysicsResolver {
-    resolve(pos: Vector3, normal: Vector3): boolean;
+    /**
+     * Tests `position`, in the simulation space of the system asking. Returns
+     * true when it is inside or on a collider, with the surface's unit normal
+     * written to `normal`; false otherwise, leaving `normal` alone.
+     */
+    resolve(position: Vector3, normal: Vector3): boolean;
 }
-declare function setPhysicsResolver(resolver: PhysicsResolver): void;
-declare function getPhysicsResolver(): PhysicsResolver;
 /**
- * Apply collision to particles from a physics resolver.
+ * Registers the resolver every {@link ApplyCollision} without one of its own
+ * uses, from the next step on; `undefined` unregisters it. The host owns the
+ * colliders, so quarks.core registers nothing itself.
+ */
+declare function setPhysicsResolver(resolver: PhysicsResolver | undefined): void;
+/** The resolver registered with {@link setPhysicsResolver}, or undefined when there is none. */
+declare function getPhysicsResolver(): PhysicsResolver | undefined;
+/**
+ * Bounce particles off the host's colliders (Unity's Collision module in its
+ * World mode, with a host-provided world).
+ *
+ * Every step each particle's position is handed to a {@link PhysicsResolver}:
+ * the behavior's own when it was given one, otherwise whatever is registered
+ * with {@link setPhysicsResolver} at that moment, so a resolver registered
+ * after the effect loaded still takes effect. A hit reflects the velocity
+ * about the surface normal and scales it by `bounce`. Without any resolver
+ * the behavior does nothing, so a collision-bearing effect loads and plays
+ * anywhere. Only `bounce` is saved; the resolver belongs to the host. Applies
+ * in every render mode.
  */
 declare class ApplyCollision implements Behavior {
-    resolver: PhysicsResolver;
+    /**
+     * The resolver this behavior asks, or undefined to ask the one
+     * registered with {@link setPhysicsResolver} when a particle is tested.
+     */
+    resolver: PhysicsResolver | undefined;
+    /** How much speed a particle keeps after a hit: 1 bounces back at full speed, 0 stops it. */
     bounce: number;
     type: string;
     tempV: Vector3;
-    constructor(resolver: PhysicsResolver, bounce: number);
+    constructor(
+    /**
+     * The resolver this behavior asks, or undefined to ask the one
+     * registered with {@link setPhysicsResolver} when a particle is tested.
+     */
+    resolver: PhysicsResolver | undefined, 
+    /** How much speed a particle keeps after a hit: 1 bounces back at full speed, 0 stops it. */
+    bounce: number);
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
     frameUpdate(delta: number): void;
@@ -1896,19 +2086,98 @@ declare class ApplyCollision implements Behavior {
 }
 
 /**
- * Apply a global force to particles.
+ * The space a behavior's vectors are authored in, as Unity's Space setting on
+ * Velocity over Lifetime and Force over Lifetime:
+ *
+ * - `'local'`: the emitter's own axes and units, so the vector turns and
+ *   scales with the emitter;
+ * - `'world'`: the world's axes, however the emitter is placed.
+ *
+ * The behavior converts the vector into the space the system simulates in
+ * (`IParticleSystem.worldSpace`), so a setting means the same thing in a local
+ * and in a world-space system.
+ */
+type BehaviorSpace = 'local' | 'world';
+/** Reads a space from JSON: `'local'` or `'world'` as written, `fallback` for anything else. */
+declare function readBehaviorSpace(value: unknown, fallback: BehaviorSpace): BehaviorSpace;
+/**
+ * The emitter's world transform, decomposed once per frame, with the
+ * conversions a behavior needs to move a vector or a point between the space
+ * it was authored in and the space the particles simulate in.
+ *
+ * Call {@link refresh} from `frameUpdate`. Before the first refresh the frame
+ * is the identity, so a conversion is a no-op. The transform read is the
+ * emitter's matrix as the host set it for the frame; a host that runs several
+ * simulation steps per frame interpolates the emitter's motion for emission,
+ * but the behaviors see the frame's end position.
+ */
+declare class EmitterFrame {
+    /** The emitter's world position. */
+    readonly position: Vector3;
+    /** The emitter's world rotation. */
+    readonly quaternion: Quaternion;
+    /** The emitter's world scale per axis. */
+    readonly scale: Vector3;
+    /** Inverse of {@link quaternion}. */
+    readonly quaternionInverse: Quaternion;
+    /** Reciprocal of {@link scale} per axis, 0 where the scale is 0. */
+    readonly scaleInverse: Vector3;
+    /** Decomposes the emitter's current world matrix. */
+    refresh(particleSystem: IParticleSystem): void;
+    /**
+     * Converts the direction `vector`, authored in `space`, into the simulation
+     * space of a system that simulates in world space when `worldSpace` is
+     * true. A vector already in the simulation space is left as it is.
+     */
+    toSimulation(vector: Vector3, space: BehaviorSpace, worldSpace: boolean): Vector3;
+    /**
+     * Converts the point `point`, authored in `space`, into the simulation
+     * space, as {@link toSimulation} does for a direction but with the
+     * emitter's position taken into account.
+     */
+    pointToSimulation(point: Vector3, space: BehaviorSpace, worldSpace: boolean): Vector3;
+}
+
+/**
+ * Apply a constant force along one direction to every particle, like gravity or wind.
+ *
+ * `magnitude` is rolled per particle when it is emitted: a {@link ConstantValue} pushes every
+ * particle equally, an {@link IntervalValue} gives each particle its own strength for its whole
+ * life, as Unity's Force over Lifetime does with Random Between Two Constants.
+ *
+ * The direction is authored in {@link space}: world axes by default, so gravity stays down
+ * however the emitter is turned, or the emitter's own axes with `'local'`. In a world-space
+ * system a world force is also multiplied by the system's `motionScale`, as every world-space
+ * force is. Applies in every render mode.
  */
 declare class ApplyForce implements Behavior {
+    /** The direction of the force; its length scales it. */
     direction: Vector3;
+    /** The force's strength, in units per second squared, rolled per particle. */
     magnitude: ValueGenerator;
+    /** The space the direction is authored in; `'world'` by default. */
+    space: BehaviorSpace;
     type: string;
-    magnitudeValue: number;
-    memory: {
-        data: never[];
-        dataCount: number;
-    };
-    constructor(direction: Vector3, magnitude: ValueGenerator);
-    initialize(particle: Particle): void;
+    /** Learned in {@link initialize}, so undefined until this behavior sees a particle. */
+    ps?: IParticleSystem;
+    /** The emitter's transform this frame, refreshed by {@link frameUpdate}. */
+    readonly _frame: EmitterFrame;
+    /** {@link direction} in the simulation space, refreshed by {@link frameUpdate}. */
+    readonly _direction: Vector3;
+    constructor(
+    /** The direction of the force; its length scales it. */
+    direction: Vector3, 
+    /** The force's strength, in units per second squared, rolled per particle. */
+    magnitude: ValueGenerator, 
+    /** The space the direction is authored in; `'world'` by default. */
+    space?: BehaviorSpace);
+    initialize(particle: Particle, particleSystem: IParticleSystem): void;
+    /**
+     * What the magnitude is multiplied by before it reaches the velocity: the
+     * step, and the system's `motionScale` for a world force in a world-space
+     * system. An unknown system (before {@link initialize}) counts as world space.
+     */
+    _step(delta: number): number;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
     frameUpdate(delta: number): void;
@@ -1923,7 +2192,11 @@ interface Sequencer {
     toJSON(): any;
     clone(): Sequencer;
 }
-declare function SequencerFromJSON(json: any): Sequencer;
+/**
+ * Reads a sequencer. A type this version does not know warns and gives `undefined`, so the
+ * caller can skip that sequence and keep the rest of the behavior.
+ */
+declare function SequencerFromJSON(json: any): Sequencer | undefined;
 
 /**
  * Apply sequences to particles.
@@ -1996,17 +2269,17 @@ interface FusionStep {
 declare function planBehaviorFusion(behaviors: Array<Behavior>): Array<FusionStep>;
 
 /**
- * Change the emit direction of particles.
+ * Turns each new particle's velocity away from its emit direction by `angle` (radians), about
+ * a random axis perpendicular to it, keeping its speed. `angle` may be a constant or a
+ * random range; it is rolled once per particle.
  */
 declare class ChangeEmitDirection implements Behavior {
     angle: ValueGenerator;
     type: string;
     _temp: Vector3;
     _q: Quaternion;
-    memory: {
-        data: never[];
-        dataCount: number;
-    };
+    /** Scratch for the angle generator's per-spawn sample; cleared before every spawn. */
+    memory: GeneratorMemory;
     constructor(angle: ValueGenerator);
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
@@ -2018,7 +2291,9 @@ declare class ChangeEmitDirection implements Behavior {
 }
 
 /**
- * Color particles by their speed.
+ * Colors particles by their current speed, like Unity's Color by Speed: the speed (velocity
+ * length times the speed modifier) is placed in `speedRange`, clamped to 0..1, and the gradient is
+ * read there and multiplied by the start colour.
  */
 declare class ColorBySpeed implements Behavior {
     color: FunctionColorGenerator;
@@ -2079,14 +2354,16 @@ declare class EmitSubParticleSystem implements Behavior {
     /**
      * Which of the parent particle's properties the sub particles start
      * from: its current colour and size multiply theirs, its rotation adds
-     * to theirs, and its remaining lifetime fraction scales theirs (so
-     * lifetime suits birth sub emitters, not death ones).
+     * to theirs, and its remaining lifetime fraction scales theirs. A Death
+     * sub emitter ignores lifetime, since the parent has none left; Unity
+     * would give its particles no life at all.
      */
     inherit: SubEmitterInheritance[];
     type: string;
     private q_;
     private v_;
     private v2_;
+    private v3_;
     private subEmissions;
     /** Finished emission states, kept for reuse: a burst of deaths would otherwise allocate one plus a matrix each. */
     private spareEmissions;
@@ -2094,8 +2371,9 @@ declare class EmitSubParticleSystem implements Behavior {
     /**
      * Which of the parent particle's properties the sub particles start
      * from: its current colour and size multiply theirs, its rotation adds
-     * to theirs, and its remaining lifetime fraction scales theirs (so
-     * lifetime suits birth sub emitters, not death ones).
+     * to theirs, and its remaining lifetime fraction scales theirs. A Death
+     * sub emitter ignores lifetime, since the parent has none left; Unity
+     * would give its particles no life at all.
      */
     inherit?: SubEmitterInheritance[]);
     initialize(particle: Particle): void;
@@ -2103,8 +2381,8 @@ declare class EmitSubParticleSystem implements Behavior {
     /**
      * The system to emit into, or undefined when `subParticleSystem` does not
      * hold a resolved emitter — unset, or a uuid string a loader could not
-     * link. Every use goes through here, so a bad value is skipped rather
-     * than thrown on.
+     * link — or when that system was disposed. Every use goes through here,
+     * so a bad value is skipped rather than thrown on.
      */
     private get target();
     private emit;
@@ -2113,29 +2391,62 @@ declare class EmitSubParticleSystem implements Behavior {
     static fromJSON(json: any, particleSystem: IParticleSystem): Behavior;
     clone(): Behavior;
     reset(): void;
+    /**
+     * Drops the emissions still running, as when the parent system restarts or stops: a Death
+     * emission would otherwise keep emitting where a particle of the last play died.
+     */
+    clearEmissions(): void;
+    /** Copies what a sub emission reads from its parent: where it is, how it moves and what it inherits. */
+    private static copyInto;
     private static validInherit;
     private setMatrixFromParticle;
 }
 
 /**
- * Apply a force to particles over their life.
+ * Accelerate particles by a force that changes over their life, one curve per
+ * axis (Unity's Force over Lifetime).
+ *
+ * The force is in units per second squared, authored in {@link space}: world
+ * axes by default, or the emitter's own axes with `'local'`, in which case it
+ * turns and scales with the emitter. In a world-space system a world force is
+ * also multiplied by the system's `motionScale`, as every world-space force is.
+ * Applies in every render mode.
  */
 declare class ForceOverLife implements Behavior {
+    /** Force along X over the particle's life, in units per second squared. */
     x: FunctionValueGenerator | ValueGenerator;
+    /** Force along Y over the particle's life, in units per second squared. */
     y: FunctionValueGenerator | ValueGenerator;
+    /** Force along Z over the particle's life, in units per second squared. */
     z: FunctionValueGenerator | ValueGenerator;
+    /** The space the force is authored in; `'world'` by default. */
+    space: BehaviorSpace;
     type: string;
     _temp: Vector3;
     /** Learned in {@link initialize}, so undefined until this behavior sees a particle. */
     ps?: IParticleSystem;
+    /** The emitter's transform this frame, refreshed by {@link frameUpdate}. */
+    readonly _frame: EmitterFrame;
     initialize(particle: Particle, particleSystem: IParticleSystem): void;
-    constructor(x: FunctionValueGenerator | ValueGenerator, y: FunctionValueGenerator | ValueGenerator, z: FunctionValueGenerator | ValueGenerator);
+    constructor(
+    /** Force along X over the particle's life, in units per second squared. */
+    x: FunctionValueGenerator | ValueGenerator, 
+    /** Force along Y over the particle's life, in units per second squared. */
+    y: FunctionValueGenerator | ValueGenerator, 
+    /** Force along Z over the particle's life, in units per second squared. */
+    z: FunctionValueGenerator | ValueGenerator, 
+    /** The space the force is authored in; `'world'` by default. */
+    space?: BehaviorSpace);
+    /**
+     * What the force is multiplied by before it reaches the velocity: the
+     * step, and the system's `motionScale` for a world force in a world-space
+     * system. An unknown system (before {@link initialize}) counts as world space.
+     */
+    _step(delta: number): number;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
     toJSON(): any;
     static fromJSON(json: any): Behavior;
-    _tempScale: Vector3;
-    _tempQ: Quaternion;
     frameUpdate(delta: number): void;
     clone(): Behavior;
     reset(): void;
@@ -2227,16 +2538,26 @@ declare class FrameOverLife implements Behavior {
 }
 
 /**
- * Apply a gravity force to particles.
- * the gravity force is calculated as:
- * F = G * m1 * m2 / r^2
+ * Pull particles toward a point with an inverse-square force, F = magnitude / r²
+ * (Niagara's Point Attraction Force).
+ *
+ * `center` is a point in the space the system simulates in: the emitter's own
+ * space for a local-space system, the world for a world-space one. A particle
+ * exactly on the centre is left alone rather than given an infinite pull.
+ * Applies in every render mode.
  */
 declare class GravityForce implements Behavior {
+    /** The point pulled toward, in the simulation space. */
     center: Vector3;
+    /** Strength of the pull at distance 1, in units per second squared. */
     magnitude: number;
     type: string;
     temp: Vector3;
-    constructor(center: Vector3, magnitude: number);
+    constructor(
+    /** The point pulled toward, in the simulation space. */
+    center: Vector3, 
+    /** Strength of the pull at distance 1, in units per second squared. */
+    magnitude: number);
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
@@ -2275,10 +2596,18 @@ declare class InheritVelocity implements Behavior {
 }
 
 /**
- * Limit the speed of particles over their life.
+ * Limits the speed of particles over their life, like Unity's Limit Velocity over Lifetime: a
+ * particle faster than `speed` loses part of the excess each step.
  */
 declare class LimitSpeedOverLife implements Behavior {
+    /** The speed limit over the particle's life. */
     speed: FunctionValueGenerator;
+    /**
+     * How much of the excess speed goes, from 0 (none) to 1, clamped. At 60 steps a second each
+     * step removes `dampen / 3` of it; other step lengths remove the share that compounds to the
+     * same loss per second, so the result does not depend on the frame rate. Even at 1 the
+     * limit is approached over a few steps rather than held exactly.
+     */
     dampen: number;
     type: string;
     /** Learned in {@link initialize}; its motion scale multiplies the limit of a world-space system. */
@@ -2286,7 +2615,18 @@ declare class LimitSpeedOverLife implements Behavior {
     initialize(particle: Particle, particleSystem?: IParticleSystem): void;
     /** What the limit is multiplied by: the system's motion scale in world space, else 1. */
     motionScale(): number;
-    constructor(speed: FunctionValueGenerator, dampen: number);
+    constructor(
+    /** The speed limit over the particle's life. */
+    speed: FunctionValueGenerator, 
+    /**
+     * How much of the excess speed goes, from 0 (none) to 1, clamped. At 60 steps a second each
+     * step removes `dampen / 3` of it; other step lengths remove the share that compounds to the
+     * same loss per second, so the result does not depend on the frame rate. Even at 1 the
+     * limit is approached over a few steps rather than held exactly.
+     */
+    dampen: number);
+    /** The share of the excess speed one step of `delta` seconds removes; see {@link dampen}. */
+    dampenStep(delta: number): number;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
     toJSON(): any;
@@ -2297,7 +2637,18 @@ declare class LimitSpeedOverLife implements Behavior {
 }
 
 /**
- * Apply noise to particles.
+ * Jitter particles with smooth noise over their life (Unity's Noise module).
+ *
+ * Each particle reads its own one-dimensional simplex curves at its age times
+ * `frequency`; `power` scales what they return, `positionAmount` and
+ * `rotationAmount` say how much of it goes into the position and the
+ * rotation. The offset applied last step is removed before this step's is
+ * added, so the noise rides on top of the other behaviors instead of
+ * accumulating. A billboard's angle turns by W noise × π × amount; a mesh
+ * particle turns by the same angle around an axis the X, Y and Z noise choose.
+ * The generators are picked per particle from the random source, so a seeded
+ * system (see the `Behavior` contract) replays the same noise. Applies in
+ * every render mode.
  */
 declare class Noise implements Behavior {
     frequency: FunctionValueGenerator | ValueGenerator;
@@ -2346,6 +2697,13 @@ declare class Noise implements Behavior {
     private _positionAmount;
     private _rotationAmount;
     private static constantOf;
+    /**
+     * Replaces the noise turn applied last step with this step's: an axis-angle
+     * turn whose axis comes from the X, Y and Z generators and whose angle, as
+     * for a billboard's angle, is the W generator's value times π times
+     * `amount`, so `rotationAmount` sets how far a mesh particle wobbles.
+     */
+    private rotateByNoise;
     update(particle: Particle, _: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
     toJSON(): any;
@@ -2356,16 +2714,52 @@ declare class Noise implements Behavior {
 }
 
 /**
- * Orbit particles around an axis over their life.
+ * Turn particles around an axis over their life, like Unity's Orbital
+ * velocity: each particle keeps its distance from the axis and sweeps around
+ * it at `orbitSpeed` radians per second.
+ *
+ * The axis and the pivot are authored in {@link space}. `'local'`, the default,
+ * is the emitter's: the axis is in the emitter's axes and the pivot is the
+ * emitter's origin, so in a world-space system the orbit follows the emitter
+ * and the effect looks the same whichever space the system simulates in.
+ * `'world'` orbits the world origin about a world axis wherever the emitter
+ * goes (Niagara's Vortex Force with a fixed origin). The axis need not be a
+ * unit vector; only its direction matters, and a zero axis orbits nothing.
+ * Applies in every render mode.
+ *
+ * For an orbit around three axes at once, with a radial speed or an offset
+ * pivot, see `VelocityOverLife`.
  */
 declare class OrbitOverLife implements Behavior {
+    /** Angular speed around the axis over the particle's life, in radians per second. */
     orbitSpeed: FunctionValueGenerator | ValueGenerator;
+    /** The axis orbited, in {@link OrbitOverLife.space | space}; its length is ignored. */
     axis: Vector3;
+    /** The space the axis and the pivot are authored in; `'local'` (the emitter's) by default. */
+    space: BehaviorSpace;
     type: string;
     rotation: Quaternion;
     temp: Vector3;
-    constructor(orbitSpeed: FunctionValueGenerator | ValueGenerator, axis?: Vector3);
-    initialize(particle: Particle): void;
+    /** Learned in {@link initialize}, so undefined until this behavior sees a particle. */
+    ps?: IParticleSystem;
+    /** The emitter's transform this frame, refreshed by {@link frameUpdate}. */
+    readonly _frame: EmitterFrame;
+    /** Unit {@link axis} in the simulation space, or zero for a zero axis; refreshed by {@link frameUpdate}. */
+    readonly _axis: Vector3;
+    /** The pivot in the simulation space; refreshed by {@link frameUpdate}. */
+    readonly _center: Vector3;
+    constructor(
+    /** Angular speed around the axis over the particle's life, in radians per second. */
+    orbitSpeed: FunctionValueGenerator | ValueGenerator, 
+    /** The axis orbited, in {@link OrbitOverLife.space | space}; its length is ignored. */
+    axis?: Vector3, 
+    /** The space the axis and the pivot are authored in; `'local'` (the emitter's) by default. */
+    space?: BehaviorSpace);
+    initialize(particle: Particle, particleSystem: IParticleSystem): void;
+    /** Recomputes the unit axis and pivot in the simulation space from {@link axis} and the emitter's frame. */
+    private refreshAxis;
+    /** Whether the frame is read: only when the authored space differs from the simulation space. */
+    private converts;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
     frameUpdate(delta: number): void;
@@ -2394,7 +2788,9 @@ declare class Rotation3DOverLife implements Behavior {
 }
 
 /**
- * Apply rotation to particles based on their speed.
+ * Turns particles at a rate read off their current speed, like Unity's Rotation by Speed: the
+ * speed (velocity length times the speed modifier) is placed in `speedRange`, clamped to 0..1.
+ * Billboards only; particles rotating by quaternion are left alone.
  */
 declare class RotationBySpeed implements Behavior {
     angularVelocity: ValueGenerator | FunctionValueGenerator;
@@ -2442,7 +2838,9 @@ declare class RotationOverLife implements Behavior {
 }
 
 /**
- * Apply size to particles based on their speed.
+ * Sizes particles by their current speed, like Unity's Size by Speed: the speed (velocity length
+ * times the speed modifier) is placed in `speedRange`, clamped to 0..1, and the curve read there
+ * scales the start size.
  */
 declare class SizeBySpeed implements Behavior {
     size: FunctionValueGenerator | Vector3Generator;
@@ -2478,6 +2876,13 @@ declare class SizeOverLife implements Behavior {
     reset(): void;
 }
 
+/**
+ * Where a particle's current speed (its velocity's length times its speed modifier) falls in
+ * `range`, clamped to 0..1. An empty range is a step at `a`. Unlike Unity, motion that
+ * `VelocityOverLife` adds moves the particle without changing its velocity, so it does not count.
+ */
+declare function speedFraction(particle: Particle, range: IntervalValue): number;
+
 /**
  * Apply speed to particles based on their life.
  */
@@ -2537,19 +2942,51 @@ declare class SimplexNoise {
 }
 
 /**
- * Apply turbulence to particles.
+ * Push particles around with a turbulent vector field sampled at their
+ * position (Unity's Noise module in its Position mode, Niagara's Curl Noise
+ * Force): nearby particles are pushed alike, so the system swirls instead of
+ * jittering.
+ *
+ * The field is three channels of four-dimensional simplex noise, `octaves`
+ * layers deep, each layer twice as fine and half as strong as the one before.
+ * `scale` is the size of one noise cell per axis in the simulation space (a
+ * zero component gives no variation along that axis), `velocityMultiplier` the
+ * push per axis in units per second squared, and `timeScale` how fast the
+ * field drifts per axis. The field is built from `seed`, so the same settings
+ * give the same field on every run and a clone or a saved copy swirls
+ * identically; give each system its own seed for different fields. Applies in
+ * every render mode.
  */
 declare class TurbulenceField implements Behavior {
+    /** Size of one noise cell per axis, in the simulation space. */
     scale: Vector3;
+    /** How many layers of noise are summed; more is finer and dearer. */
     octaves: number;
+    /** Push per axis, in units per second squared. */
     velocityMultiplier: Vector3;
+    /** How fast the field drifts per axis, in noise time per second. */
     timeScale: Vector3;
+    /** The seed the field is built from; 0 by default. */
+    seed: number;
     type: string;
     generator: SimplexNoise;
+    /** Where in time the field is sampled now; starts at {@link initialOffset} and drifts by `timeScale`. */
     timeOffset: Vector3;
+    /** The time offset the field starts from, derived from {@link seed}; restored by {@link reset}. */
+    readonly initialOffset: Vector3;
     temp: Vector3;
     temp2: Vector3;
-    constructor(scale: Vector3, octaves: number, velocityMultiplier: Vector3, timeScale: Vector3);
+    constructor(
+    /** Size of one noise cell per axis, in the simulation space. */
+    scale: Vector3, 
+    /** How many layers of noise are summed; more is finer and dearer. */
+    octaves: number, 
+    /** Push per axis, in units per second squared. */
+    velocityMultiplier: Vector3, 
+    /** How fast the field drifts per axis, in noise time per second. */
+    timeScale: Vector3, 
+    /** The seed the field is built from; 0 by default. */
+    seed?: number);
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
@@ -2557,10 +2994,12 @@ declare class TurbulenceField implements Behavior {
     frameUpdate(delta: number): void;
     static fromJSON(json: any): Behavior;
     clone(): Behavior;
+    /** Rewinds the field's drift to where it started, so a restarted system swirls the same way. */
     reset(): void;
 }
 
-type VelocityOverLifeSpace = 'local' | 'world';
+/** The space a `VelocityOverLife` is authored in; the same choice as {@link BehaviorSpace}. */
+type VelocityOverLifeSpace = BehaviorSpace;
 /**
  * Move particles with a direct velocity over their life (Unity's "Velocity over Lifetime").
  * Applied as a positional displacement, so it is not affected by speed modifiers,
@@ -2617,7 +3056,7 @@ declare class VelocityOverLife implements Behavior {
 /**
  * Shapes a trail's width along its length — Unity's Width over Trail.
  *
- * The curve runs from the head (0) to the tail (1) and, by default, is a
+ * The curve runs from the head (0) to the tail (1), the trail's oldest sample, and, by default, is a
  * multiplier on the width each sample was recorded with (the particle's
  * `size.x` at that moment): a curve from 1 to 0 tapers the trail from the
  * particle's size at the head down to nothing at the tail, whatever that size
@@ -2729,23 +3168,24 @@ interface ShapeJSON {
  * Enum representing the emitter modes for particles.
  */
 declare enum EmitterMode {
-    /**
-     * Emit particles randomly over the specified duration.
-     */
+    /** Each particle starts at a random point of the arc. */
     Random = 0,
-    /**
-     * Emit particles in a continuous loop.
-     */
+    /** The start point sweeps the arc at the shape's `speed` (arcs per second) and wraps around. */
     Loop = 1,
-    /**
-     * Emit particles back and forth in a ping-pong manner.
-     */
+    /** The start point sweeps the arc back and forth, starting at the arc's start. */
     PingPong = 2,
-    /**
-     * Emit particles in bursts.
-     */
+    /** A burst's particles are spread evenly over the arc; particles emitted by rate start at random. */
     Burst = 3
 }
+/**
+ * Where along the shape's arc (0…1) the next particle starts, from the shape's
+ * {@link EmitterMode} (Unity's Arc Mode): random; `Loop` sweeps the arc and wraps
+ * (`currentValue` is the sweep position in arcs, any sign); `PingPong` sweeps back
+ * and forth, starting at the arc's start; `Burst` spreads a burst's particles evenly
+ * over the arc and places rate-emitted particles at random. A `spread` above 0 then
+ * snaps the result to multiples of it (Unity's Spread), so 0.25 emits from four
+ * points. The result is always within 0…1.
+ */
 declare function getValueFromEmitterMode(mode: EmitterMode, currentValue: number, spread: number, emissionState: EmissionState): number;
 interface EmitterShape {
     type: string;
@@ -2758,6 +3198,12 @@ interface EmitterShape {
      * by the shape itself at the end of {@link initialize}.
      */
     transform?: ShapeTransform;
+    /**
+     * Forgets the state the shape built up while emitting (the arc sweep position of
+     * `Loop`/`PingPong` shapes, generator memory), so a restarted system emits from the
+     * start of the arc again. Called by the particle system's `restart()`.
+     */
+    reset?(): void;
 }
 
 /**
@@ -2788,6 +3234,11 @@ interface BoxEmitterParameters {
      * box size: 0 keeps them on the surface, 0.5 reaches the center.
      */
     boxThickness?: [number, number, number];
+    /**
+     * Offset, rotation and scale of the shape within the particle system.
+     * {@link ShapeTransform}
+     */
+    transform?: ShapeTransform;
 }
 /**
  * A particle emitter that emits particles from a box centered on the emitter, all moving along +Z
@@ -2800,6 +3251,7 @@ declare class BoxEmitter implements EmitterShape {
     depth: number;
     emitFrom: BoxEmitFrom;
     boxThickness: [number, number, number];
+    transform?: ShapeTransform;
     private readonly _point;
     constructor(parameters?: BoxEmitterParameters);
     update(_system: IParticleSystem, _delta: number): void;
@@ -2867,6 +3319,7 @@ declare class CircleEmitter implements EmitterShape {
     memory: GeneratorMemory;
     transform?: ShapeTransform;
     private currentValue;
+    reset(): void;
     constructor(parameters?: CircleEmitterParameters);
     update(system: IParticleSystem, delta: number): void;
     initialize(p: Particle, emissionState: EmissionState): void;
@@ -2928,6 +3381,7 @@ declare class ConeEmitter implements EmitterShape {
     memory: GeneratorMemory;
     transform?: ShapeTransform;
     private currentValue;
+    reset(): void;
     constructor(parameters?: ConeEmitterParameters);
     update(system: IParticleSystem, delta: number): void;
     initialize(p: Particle, emissionState: EmissionState): void;
@@ -2991,6 +3445,7 @@ declare class DonutEmitter implements EmitterShape {
     _m1: Matrix4;
     constructor(parameters?: DonutEmitterParameters);
     private currentValue;
+    reset(): void;
     update(system: IParticleSystem, delta: number): void;
     initialize(p: Particle, emissionState: EmissionState): void;
     toJSON(): ShapeJSON;
@@ -3019,6 +3474,11 @@ interface EdgeEmitterParameters {
      * {@link EmitterMode}
      */
     speed?: ValueGenerator | FunctionValueGenerator;
+    /**
+     * Offset, rotation and scale of the shape within the particle system.
+     * {@link ShapeTransform}
+     */
+    transform?: ShapeTransform;
 }
 /**
  * A particle emitter that emits particles from a line along X, all moving along +Y like Unity's
@@ -3031,7 +3491,9 @@ declare class EdgeEmitter implements EmitterShape {
     spread: number;
     speed: ValueGenerator | FunctionValueGenerator;
     memory: GeneratorMemory;
+    transform?: ShapeTransform;
     private currentValue;
+    reset(): void;
     constructor(parameters?: EdgeEmitterParameters);
     update(system: IParticleSystem, delta: number): void;
     initialize(p: Particle, emissionState: EmissionState): void;
@@ -3049,6 +3511,10 @@ interface EmitterShapePlugin {
 declare const EmitterShapes: {
     [key: string]: EmitterShapePlugin;
 };
+/**
+ * Reads an emitter shape. A type no plugin registered (a custom shape whose plugin is not
+ * loaded, or a typo) warns and gives a point emitter, so the rest of the effect still loads.
+ */
 declare function EmitterFromJSON(json: ShapeJSON, meta: JsonMetaData): EmitterShape;
 
 /**
@@ -3142,6 +3608,7 @@ declare class HemisphereEmitter implements EmitterShape {
     _m1: Matrix4;
     constructor(parameters?: HemisphereEmitterParameters);
     private currentValue;
+    reset(): void;
     update(system: IParticleSystem, delta: number): void;
     initialize(p: Particle, emissionState: EmissionState): void;
     toJSON(): ShapeJSON;
@@ -3220,6 +3687,7 @@ declare class RectangleEmitter implements EmitterShape {
     memory: GeneratorMemory;
     transform?: ShapeTransform;
     private currentValue;
+    reset(): void;
     private _m1;
     constructor(parameters?: RectangleEmitterParameters);
     update(system: IParticleSystem, delta: number): void;
@@ -3279,6 +3747,7 @@ declare class SphereEmitter implements EmitterShape {
     _m1: Matrix4;
     constructor(parameters?: SphereEmitterParameters);
     private currentValue;
+    reset(): void;
     update(system: IParticleSystem, delta: number): void;
     initialize(p: Particle, emissionState: EmissionState): void;
     toJSON(): ShapeJSON;
@@ -3293,7 +3762,12 @@ interface Plugin {
     behaviors: Array<BehaviorPlugin>;
 }
 declare const Plugins: Array<Plugin>;
+/**
+ * Registers a plugin's emitter shapes and behaviors, so effect files can name them. Loading the
+ * same plugin id again does nothing. A type another plugin registered first keeps that plugin's.
+ */
 declare function loadPlugin(plugin: Plugin): void;
+/** Removes a plugin and the types it registered; types another plugin registered stay. */
 declare function unloadPlugin(pluginId: string): void;
 
 declare class TextureSequencer implements Sequencer {
@@ -3341,6 +3815,58 @@ declare function createSeededRandom(seed: number): RandomSource;
 /** Runs `fn` with `generator` as the random source, restoring the previous one after. */
 declare function withRandomSource<T>(generator: RandomSource, fn: () => T): T;
 
+/**
+ * What a soft-particle depth texture stores per pixel, so the shaders can turn it back into the
+ * distance from the camera. These are the three outputs of Babylon's `DepthRenderer`:
+ *
+ * - `'linear'`: Babylon's default depth metric, `scene.enableDepthRenderer()`. Linear in view
+ *   depth between the camera's near and far planes.
+ * - `'nonLinear'`: the depth buffer value, `enableDepthRenderer(camera, true)`. This is what
+ *   Unity's `_CameraDepthTexture` holds and what `LinearEyeDepth` undoes.
+ * - `'viewZ'`: the view-space Z itself, `enableDepthRenderer(camera, false, true, sampling, true)`.
+ *   Exact at any range and with an infinite far plane (`camera.maxZ = 0`), which the other two
+ *   cannot represent; this is the closest match to Unreal's SceneDepth.
+ *
+ * Perspective and orthographic cameras, both NDC depth ranges (WebGL, WebGPU) and a reverse
+ * depth buffer are all handled, from the camera drawing the particles. With a reverse depth buffer
+ * and `'nonLinear'`, clear the depth renderer to 0 (`depthRenderer.clearColor.r = 0`): it clears
+ * to 1 by default, which a reverse buffer reads as the near plane, so empty sky would fade every
+ * particle in front of it. A packed `'viewZ'` cannot be decoded.
+ */
+type SoftDepthEncoding = 'linear' | 'nonLinear' | 'viewZ';
+/** How a depth texture given to {@link BatchedRenderer.setDepthTexture} is read. */
+interface DepthTextureOptions {
+    /** What the texture stores. Defaults to the encoding of the `DepthRenderer` given, else `'linear'`. */
+    encoding?: SoftDepthEncoding;
+    /**
+     * The depth is packed into the four 8-bit channels, as a `DepthRenderer` of type
+     * `UNSIGNED_BYTE` writes it. Defaults to the `DepthRenderer`'s `isPacked`, else false.
+     */
+    packed?: boolean;
+}
+/** The depth texture a batch's soft particles read, and how. */
+interface DepthBinding {
+    texture: BaseTexture;
+    encoding: SoftDepthEncoding;
+    packed: boolean;
+}
+/**
+ * Writes the four coefficients the soft-particle shaders decode a depth sample `d` with:
+ * view depth = |(x·d + y) / (z·d + w)|. Each encoding is a ratio of linear terms in `d` for
+ * every projection Babylon builds, so one formula covers them all.
+ *
+ * @param camera - The camera the particles are drawn for, normally the one the depth was drawn for.
+ * @param encoding - What the depth texture stores.
+ * @param out - Receives the coefficients.
+ */
+declare function softDepthParams(camera: Camera, encoding: SoftDepthEncoding, out: Vector4$1): Vector4$1;
+/**
+ * The view depth the shaders read off a depth sample, for the coefficients of
+ * {@link softDepthParams}. Nothing there (a `'viewZ'` sample of 0, or a sample at an infinite far
+ * plane) reads as infinitely far, so the particle does not fade.
+ */
+declare function decodeSoftDepth(sample: number, params: Vector4$1): number;
+
 /**
  * The order the particles of a batch are drawn in (Unity's Sort Mode). Alpha
  * blended particles cover what was drawn before them, so the order shows.
@@ -3353,12 +3879,25 @@ declare function withRandomSource<T>(generator: RandomSource, fn: () => T): T;
  * Sorting runs over the whole batch after each fill. Trails are not sorted.
  */
 type SortMode = 'none' | 'distance' | 'oldestInFront' | 'youngestInFront';
+/** How a system draws its particles (Unity's Render Mode), see {@link ParticleSystem.renderMode}. */
 declare enum RenderMode {
+    /** A quad facing the camera (Unity's Billboard). The default. */
     BillBoard = 0,
+    /**
+     * A quad facing the camera and stretched along the particle's velocity (Unity's Stretched
+     * Billboard), by `speedFactor` and `lengthFactor` in the system's `rendererEmitterSettings`.
+     */
     StretchedBillBoard = 1,
+    /** The system's mesh, one instance per particle (Unity's Mesh), see {@link ParticleSystem.instancingGeometry}. */
     Mesh = 2,
+    /**
+     * A ribbon drawn through the particle's past positions (Unity's Trails module, Niagara's
+     * ribbon), facing the camera; its settings are `TrailSettings` in `rendererEmitterSettings`.
+     */
     Trail = 3,
+    /** A quad lying flat in the world's XZ plane, facing up (Unity's Horizontal Billboard). */
     HorizontalBillBoard = 4,
+    /** A quad standing upright and turning only about the world's Y axis to face the camera (Unity's Vertical Billboard). */
     VerticalBillBoard = 5,
     /**
      * A quad laid from each particle to the system's {@link ParticleSystem.beamEnd}
@@ -3472,8 +4011,9 @@ declare function textureUVToJSON(uv: TextureUV, defaults?: Partial<TextureUV>):
 type GradientMapChannel = 'r' | 'g' | 'b' | 'a' | 'luminance';
 /**
  * A gradient map (colour ramp): the map is recoloured by looking its
- * {@link channel} up along U of {@link ramp}. See
- * {@link VFXBatchSettings.gradientMap}.
+ * {@link channel} up along U of {@link ramp}. Without a map the lookup reads
+ * white, so the ramp's right-hand end tints every particle, in every render
+ * mode alike. See {@link VFXBatchSettings.gradientMap}.
  */
 interface ParticleGradientMap {
     /**
@@ -3522,8 +4062,11 @@ interface ParticleErosion {
 }
 /** {@link ParticleErosion} as given: any field may be left out, the mask's layout too. */
 type ParticleErosionOptions = Partial<Omit<ParticleErosion, 'maskUV'>> & {
+    /** See {@link ParticleErosion.maskUV}; fields left out take their defaults. */
     maskUV?: Partial<TextureUV>;
 };
+/** The width of the soft band an erosion cut fades over when `softness` is left out, in mask units. */
+declare const EROSION_DEFAULT_SOFTNESS = 0.05;
 /** A complete erosion from a partial one, every field defaulted, or undefined when `erosion` is unset. */
 declare function normalizeErosion(erosion: ParticleErosionOptions | null | undefined): ParticleErosion | undefined;
 /** True when both describe the same erosion (or both none). */
@@ -3551,8 +4094,11 @@ interface ParticleUVDistortion {
 }
 /** {@link ParticleUVDistortion} as given: any field may be left out, the noise's layout too. */
 type ParticleUVDistortionOptions = Partial<Omit<ParticleUVDistortion, 'mapUV'>> & {
+    /** See {@link ParticleUVDistortion.mapUV}; fields left out take their defaults. */
     mapUV?: Partial<TextureUV>;
 };
+/** How far a distortion pushes the map's UV at most when `strength` is left out, in UV units. */
+declare const UV_DISTORTION_DEFAULT_STRENGTH = 0.05;
 /** A complete distortion from a partial one, or undefined when unset or without a map. */
 declare function normalizeUVDistortion(distortion: ParticleUVDistortionOptions | null | undefined): ParticleUVDistortion | undefined;
 /** True when both describe the same distortion (or both none). */
@@ -3574,31 +4120,58 @@ declare function readsUV1(settings: {
     uvDistortion?: ParticleUVDistortion;
     erosion?: ParticleErosion;
 }): boolean;
+/**
+ * A batch's copy of the {@link VFXBatchSettings} its systems share: every optional field
+ * defaulted, and every field the batch's render mode ignores at its default (an opaque batch's
+ * `materialBlendMode` reads `ALPHA_DISABLE`, a billboard batch's `rim` is unset). The renderer
+ * adds a system to the batch whose settings match its own.
+ */
 interface StoredBatchSettings {
+    /** See {@link VFXBatchSettings.instancingGeometry}. */
     instancingGeometry: Float32Array;
+    /** See {@link VFXBatchSettings.instancingIndices}. */
     instancingIndices: Uint32Array | Uint16Array;
+    /** See {@link VFXBatchSettings.instancingUVs}. */
     instancingUVs?: Float32Array;
     /** The mesh's second UV set, see {@link UVChannel}. */
     instancingUVs2?: Float32Array;
+    /** See {@link VFXBatchSettings.instancingNormals}. */
     instancingNormals?: Float32Array;
+    /** See {@link VFXBatchSettings.renderMode}. */
     renderMode: RenderMode;
+    /** See {@link VFXBatchSettings.renderOrder}. */
     renderOrder: number;
+    /** See {@link VFXBatchSettings.uTileCount}. */
     uTileCount: number;
+    /** See {@link VFXBatchSettings.vTileCount}. */
     vTileCount: number;
+    /** See {@link VFXBatchSettings.blendTiles}. */
     blendTiles: boolean;
+    /** See {@link VFXBatchSettings.softParticles}. */
     softParticles: boolean;
+    /** See {@link VFXBatchSettings.softNearFade}. */
     softNearFade: number;
+    /** See {@link VFXBatchSettings.softFarFade}. */
     softFarFade: number;
+    /** See {@link VFXBatchSettings.materialBlendMode}. */
     materialBlendMode: number;
+    /** See {@link VFXBatchSettings.materialTransparent}. */
     materialTransparent: boolean;
+    /** See {@link VFXBatchSettings.materialDepthTest}. */
     materialDepthTest: boolean;
+    /** See {@link VFXBatchSettings.materialDepthWrite}. */
     materialDepthWrite: boolean;
+    /** See {@link VFXBatchSettings.materialAlphaTest}. */
     materialAlphaTest: number;
-    texture: any;
+    /** See {@link VFXBatchSettings.texture}. */
+    texture: BaseTexture | null;
+    /** See {@link VFXBatchSettings.reflectionTexture}. */
     reflectionTexture: BaseTexture | null;
+    /** See {@link VFXBatchSettings.reflectionLevel}. */
     reflectionLevel: number;
-    reflectionFaces: BaseTexture[] | null;
+    /** See {@link VFXBatchSettings.reflectionAtlas}. */
     reflectionAtlas: BaseTexture | null;
+    /** See {@link VFXBatchSettings.layerMask}. */
     layerMask: number;
     /** Babylon rendering group the batch mesh draws in, see {@link VFXBatchSettings.renderingGroupId}. */
     renderingGroupId: number;
@@ -3625,14 +4198,32 @@ interface StoredBatchSettings {
     /** Alpha erosion, see {@link VFXBatchSettings.erosion}. */
     erosion?: ParticleErosion;
 }
+/**
+ * One draw call of a {@link BatchedRenderer}: the systems that share a material, texture and
+ * geometry, drawn together from one instanced mesh. The renderer makes and frees batches as
+ * systems are added and their settings change; read them through `renderer.batches` to inspect
+ * what is drawn, not to change it.
+ */
 declare abstract class VFXBatch {
+    /** The Babylon mesh the batch draws with. */
     mesh: Mesh;
+    /** The systems drawn by this batch. */
     systems: Set<IParticleSystem>;
+    /** The settings every system in the batch shares, with what the render mode ignores at its default. */
     settings: StoredBatchSettings;
+    /** @internal */
     protected maxParticles: number;
+    /** @internal */
     protected scene: Scene;
+    /** @internal */
     protected readonly visibleSystems: IParticleSystem[];
-    protected constructor(settings: VFXBatchSettings, scene: Scene);
+    /**
+     * The depth texture soft particles read, from {@link BatchedRenderer.setDepthTexture}.
+     * @internal
+     */
+    protected depth: DepthBinding | null;
+    /** @internal */
+    protected constructor(settings: VFXBatchSettings, scene: Scene, depth?: DepthBinding | null);
     /**
      * Applies the batch-level scene settings to {@link mesh}. Called on every
      * mesh the batch creates, since the buffers rebuild it.
@@ -3654,12 +4245,17 @@ declare abstract class VFXBatch {
      */
     protected refreshBoundingInfo(): void;
     /**
-     * Fog defines and uniforms for a material of this batch, and the per-bind
-     * upload of the scene's current fog. Mode 0 (none) when the scene has fog
+     * Writes a uniform that changes per bind, such as one read off the active camera, to the
+     * material for the next bind and to its bound effect for this one: ShaderMaterial uploads its
+     * stored values before the bind observers run, so a value written only to the material would
+     * reach the GPU one draw late, and with two cameras it would always be the other camera's.
+     */
+    protected static writeBound(material: ShaderMaterial, write: (target: ShaderMaterial | Effect) => void): void;
+    /**
+     * The per-bind upload of the scene's current fog. Mode 0 (none) when the scene has fog
      * disabled, so toggling fog at runtime needs no recompile.
+     * @internal
      */
-    protected static readonly FOG_UNIFORMS: string[];
-    protected fogDefines(): string[];
     protected bindFog(material: ShaderMaterial): void;
     /**
      * Seconds of renderer time, set by the renderer before each fill; what UV
@@ -3668,13 +4264,26 @@ declare abstract class VFXBatch {
     time: number;
     /** True when a texture effect of this batch samples UV channel 1, see {@link UVChannel}. */
     protected usesUV1(): boolean;
-    /** Defines of the texture effects (see `shaders/chunks/surface.ts`) this batch uses. */
-    protected surfaceDefines(): string[];
-    /** Adds the uniforms and samplers of the texture effects this batch uses. */
-    protected surfaceUniforms(uniforms: string[], samplers: string[]): void;
     /** Sets the texture effects' textures and constants, and advances their scrolling on every bind. */
     protected bindSurface(material: ShaderMaterial): void;
+    /** Writes the texture effects' constants (the uniforms their live parameters set). */
+    private writeSurfaceParams;
+    /**
+     * Takes new live parameters (see {@link BatchedRenderer.updateSystem}): settings with the same
+     * shader key as the batch's, whose uniform values differ. They are copied into the batch's
+     * settings and written to its material, which is kept.
+     * @internal
+     */
+    applyLiveSettings(settings: StoredBatchSettings): void;
+    /**
+     * Writes every uniform a live parameter sets, from the batch's settings. The base writes the
+     * ones every render mode has; a mode adds its own.
+     * @internal
+     */
+    protected writeLiveUniforms(material: ShaderMaterial): void;
+    /** @internal */
     addSystem(system: IParticleSystem): void;
+    /** @internal */
     removeSystem(system: IParticleSystem): void;
     /**
      * Visible systems of this batch, written into a buffer owned by the batch.
@@ -3682,56 +4291,115 @@ declare abstract class VFXBatch {
      * reallocated; treat it as valid only until the next call.
      */
     getVisibleSystems(): IParticleSystem[];
-    applyDepthTexture(depthTexture: BaseTexture | null): void;
-    /** Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it. */
+    /**
+     * Sets the depth texture soft particles read. Soft particles are compiled in only while there
+     * is one, as Unity turns them off for a camera without a depth texture, so attaching or
+     * removing it, or changing how it is packed, rebuilds a soft batch's material.
+     *
+     * @param depth - The binding, or a bare texture, read as `'linear'` and unpacked.
+     * @internal Use {@link BatchedRenderer.setDepthTexture}.
+     */
+    applyDepthTexture(depth: DepthBinding | BaseTexture | null): void;
+    /**
+     * Sets the soft-particle and alpha-test values on a material, and decodes the depth for the
+     * camera of each draw.
+     */
+    protected bindSoft(material: ShaderMaterial): void;
+    /** Writes the soft-particle fade and the alpha cutoff, the live parameters every mode shares. */
+    private writeSoftParams;
+    /** True when this batch draws soft particles: they are on and a depth texture is attached. */
+    protected drawsSoft(): boolean;
+    /**
+     * Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it.
+     * @internal Use {@link BatchedRenderer.setMeshLighting}.
+     */
     applyMeshLighting(_lighting: MeshLightingSettings): void;
+    /** @internal */
     abstract setupBuffers(): void;
+    /** @internal */
     abstract expandBuffers(target: number): void;
+    /** @internal */
     abstract rebuildMaterial(): void;
+    /** @internal */
     abstract update(): void;
+    /** @internal */
     dispose(): void;
 }
 
+/**
+ * Everything about a system that decides how it is drawn: {@link ParticleSystem.getRendererSettings}
+ * returns it, and the renderer draws systems whose settings match from one batch. Only the
+ * settings a render mode reads count: two billboards that differ in a mesh-only setting, such as
+ * `rim`, share a batch.
+ *
+ * A batch is one draw with one material, so its settings fall into two groups, as a Unity
+ * material's keywords and texture slots against its MaterialPropertyBlock values, or an Unreal
+ * material against a dynamic material instance's parameters. The shader key (render mode,
+ * geometry, textures, blend and depth state, and which effects are on) decides the material.
+ * The live parameters (the fade distances, alpha cutoff, pivot, size limits, reflection level,
+ * rim colour, each effect's numbers, and each texture's tiling, offset and scroll) are uniforms:
+ * changing one on a system that is alone in its batch writes the material in place, with no new
+ * batch or material. A texture's UV channel is part of the shader key, so changing it rebuilds.
+ *
+ * Prefer the system's own setters, which also move it to a matching batch; after changing a
+ * field directly, set {@link ParticleSystem.neededToUpdateRender}.
+ */
 interface VFXBatchSettings {
+    /** Mesh particles' vertex positions, see {@link ParticleSystem.instancingGeometry}. A quad for other modes. */
     instancingGeometry: Float32Array;
+    /** Triangle indices into {@link instancingGeometry}. */
     instancingIndices: Uint32Array | Uint16Array;
+    /** The mesh's first UV set, two values per vertex. */
     instancingUVs?: Float32Array;
     /** The mesh's second UV set, see {@link UVChannel}. */
     instancingUVs2?: Float32Array;
+    /** The mesh's vertex normals; mesh particles fall back to +Z. */
     instancingNormals?: Float32Array;
+    /** See {@link ParticleSystem.renderMode}. */
     renderMode: RenderMode;
+    /** See {@link ParticleSystem.renderOrder}. */
     renderOrder: number;
+    /** See {@link ParticleSystem.uTileCount}. */
     uTileCount: number;
+    /** See {@link ParticleSystem.vTileCount}. */
     vTileCount: number;
+    /** See {@link ParticleSystem.blendTiles}; read with a sheet, and not by trails. */
     blendTiles: boolean;
+    /** See {@link ParticleSystem.softParticles}. */
     softParticles: boolean;
+    /** See {@link ParticleSystem.softNearFade}. */
     softNearFade: number;
+    /** See {@link ParticleSystem.softFarFade}. */
     softFarFade: number;
+    /** Babylon alpha mode, see {@link ParticleSystem.blending}. */
     materialBlendMode: number;
+    /** Whether the batch draws in the transparent pass. */
     materialTransparent: boolean;
+    /** Whether particles are hidden behind nearer geometry. */
     materialDepthTest: boolean;
+    /** Whether particles write depth. */
     materialDepthWrite: boolean;
+    /** Alpha below which a fragment is discarded; 0 discards nothing. */
     materialAlphaTest: number;
+    /** See {@link ParticleSystem.texture}. */
     texture: Texture | null;
     /**
-     * Cubemap (or other reflection texture) harvested from a Babylon material's
-     * `reflectionTexture`. Mesh batches sample it like StandardMaterial cubic
-     * reflection; other render modes ignore it.
+     * The reflection a mesh particle's material carries (a Babylon material's `reflectionTexture`
+     * or `environmentTexture`). It is not sampled itself: a cube texture is unfolded into
+     * {@link reflectionAtlas} once it has loaded and sampled from there; anything else is kept
+     * only to tell materials apart. Other render modes ignore it.
      */
     reflectionTexture: BaseTexture | null;
     /** Multiplier for the reflection sample — mirrors `texture.level`. */
     reflectionLevel: number;
     /**
-     * Optional six cube-face 2D textures (px,py,pz,nx,ny,nz). Prefer
-     * `reflectionAtlas` on iOS — many simultaneous face samplers still trip
-     * GL_INVALID_OPERATION on WebKit.
-     */
-    reflectionFaces: BaseTexture[] | null;
-    /**
-     * Single 3×2 atlas of cube faces (px py pz / nx ny nz). One sampler2D —
-     * the path that stays valid on iOS WebKit ShaderMaterial draws.
+     * A 3×2 atlas of cube faces (+X +Y +Z over -X -Y -Z) that mesh particles reflect, through one
+     * `sampler2D`: the path that stays valid on iOS WebKit ShaderMaterial draws, where a
+     * `samplerCube` or six face samplers raise GL_INVALID_OPERATION. Built from
+     * {@link reflectionTexture} when that is a cube texture. Other render modes ignore it.
      */
     reflectionAtlas: BaseTexture | null;
+    /** Camera layer mask of the batch mesh, see {@link ParticleSystem.layers}. */
     layerMask: number;
     /**
      * Babylon rendering group (`mesh.renderingGroupId`) the batch draws in,
@@ -3740,8 +4408,11 @@ interface VFXBatchSettings {
     renderingGroupId: number;
     /**
      * Whether the scene's fog applies to the particles, as it does to any other
-     * mesh; true by default. Additive particles fade toward black rather than
-     * the fog colour. Systems that differ are batched apart.
+     * mesh; true by default. Particles that add to the frame (`ALPHA_ADD`,
+     * `ALPHA_ONEONE`) fade toward black rather than the fog colour, which would
+     * fog the whole screen; every other blend mode mixes toward the fog colour,
+     * which is right for alpha blending and only approximate for a multiply or
+     * subtract. Systems that differ are batched apart.
      */
     applyFog: boolean;
     /**
@@ -3782,24 +4453,61 @@ interface VFXBatchSettings {
     /** Alpha erosion (dissolve / wipe), see {@link ParticleErosion}. Unset: none. Systems that differ are batched apart. */
     erosion?: ParticleErosion;
 }
+/**
+ * How {@link BatchedRenderer.configureAdaptivePerformance} trades particles for frame time: each
+ * update that runs over `targetFrameMs` lowers every system's quality factor (see
+ * {@link ParticleSystem.setQualityFactor}) by `decreaseStep`, each one under it raises the factor
+ * by `increaseStep`, within `minQuality` and `maxQuality`.
+ */
 interface AdaptivePerformanceOptions {
+    /** CPU time in milliseconds the renderer's update may take before quality drops. Default 16.7. */
     targetFrameMs: number;
+    /** Lowest quality factor, 0.1 to 1 ({@link ParticleSystem.setQualityFactor} clamps lower values). Default 0.35. */
     minQuality: number;
+    /** Highest quality factor, `minQuality` to 1. Default 1. */
     maxQuality: number;
+    /** Quality lost per update over budget. Default 0.08. */
     decreaseStep: number;
+    /** Quality regained per update within budget. Default 0.02. */
     increaseStep: number;
 }
+/** A snapshot of the renderer's adaptive performance, from {@link BatchedRenderer.getAdaptivePerformanceState}. */
 interface AdaptivePerformanceState extends AdaptivePerformanceOptions {
+    /** Whether adaptive performance is on. */
     enabled: boolean;
+    /** The quality factor the systems run at now. */
     currentQuality: number;
+    /** CPU time the last measured update took, in milliseconds; kept from the last update while off. */
     lastFrameCpuMs: number;
 }
+/**
+ * Draws particle systems, batching the ones that draw alike into one instanced mesh each, and
+ * advances them every frame. It is a node in the scene; make one per scene, add each system with
+ * {@link addSystem}, and call {@link update} once per frame:
+ *
+ * ```ts
+ * const renderer = new BatchedRenderer('particles', scene);
+ * renderer.addSystem(system);
+ * scene.onBeforeRenderObservable.add(() => renderer.update(scene.getEngine().getDeltaTime() / 1000));
+ * ```
+ *
+ * Systems step on a fixed 60 Hz clock, so an effect plays out the same at any frame rate.
+ *
+ * The renderer is a node so the batches have a parent to live under; leave it at the origin,
+ * unturned and unscaled. Particles are placed in the world by their emitters, and a transform on
+ * the renderer would move every one of them again (it warns once when it finds one). A system
+ * belongs to one renderer at a time: adding it to another takes it out of the first.
+ */
 declare class BatchedRenderer extends TransformNode {
+    /** Whether the renderer has warned about its own transform; see the class description. */
+    private warnedAboutTransform;
+    /** The batches, one draw each. Read to inspect what is drawn; the renderer owns them. */
     batches: Array<VFXBatch>;
     /** Seconds this renderer has been updated for; the clock UV and erosion scrolling run on. */
     private elapsed;
+    /** Index into {@link batches} of each system's batch. The renderer owns it. */
     systemToBatchIndex: Map<IParticleSystem, number>;
-    depthTexture: BaseTexture | null;
+    private depth;
     /** Systems in insertion order — iterated every frame, unlike the map. */
     private systems;
     /**
@@ -3864,19 +4572,47 @@ declare class BatchedRenderer extends TransformNode {
      */
     private isSystemInView;
     private static clamp;
-    private static equals;
+    /**
+     * Starts drawing and updating `system`, in the batch whose settings match its own (a new one if
+     * none does). Add each system of an effect, or use `QuarksUtil.addToBatchRenderer` on its root.
+     */
     addSystem(system: IParticleSystem): void;
     /** Places a system into a compatible batch, creating one when none matches. */
     private assignToBatch;
+    /**
+     * Stops drawing and updating `system`; disposing the system calls it. Its particles are left as they are.
+     * @returns Whether the system was in one of this renderer's batches.
+     */
     deleteSystem(system: IParticleSystem): boolean;
     /** Detaches a system from its batch, leaving the renderer's system list alone. */
     private removeFromBatch;
     /**
-     * Re-buckets a system whose render settings changed. The system keeps its
-     * place in the update order, so this is safe to call mid-frame.
+     * Takes a system's changed render settings. When only live parameters changed (see
+     * {@link VFXBatchSettings}) and the system is alone in its batch, the batch's material is
+     * written in place. Otherwise the system moves to the batch its settings now match. The
+     * system keeps its place in the update order, so this is safe to call mid-frame.
      */
     updateSystem(system: IParticleSystem): void;
-    setDepthTexture(depthTexture: BaseTexture | null): void;
+    /**
+     * Sets the scene depth that soft particles fade against. Without one, soft particles are not
+     * compiled in and draw hard, as Unity does for a camera with no depth texture.
+     *
+     * Pass the `DepthRenderer` itself to have its encoding read off it, for example
+     * `renderer.setDepthTexture(scene.enableDepthRenderer(camera))`. A bare texture is read as
+     * Babylon's default `'linear'` metric unless `options.encoding` says otherwise; see
+     * {@link SoftDepthEncoding}. The depth should be drawn by the camera that draws the particles.
+     * The texture is held, not the renderer: set it again if the `DepthRenderer` is disposed or
+     * replaced.
+     *
+     * @param depth - A depth texture, a Babylon `DepthRenderer`, or null to turn soft particles off.
+     * @param options - What the texture stores, when it cannot be read off a `DepthRenderer`.
+     */
+    setDepthTexture(depth: BaseTexture | DepthRenderer | null, options?: DepthTextureOptions): void;
+    /** The depth texture soft particles fade against, see {@link setDepthTexture}. */
+    get depthTexture(): BaseTexture | null;
+    set depthTexture(texture: BaseTexture | null);
+    /** What the depth texture stores, see {@link setDepthTexture}. */
+    get depthEncoding(): SoftDepthEncoding | null;
     /**
      * Sets the light mesh particles with `lighting: 'fixed'` (the default) are
      * lit by, for every mesh batch of this renderer, including ones created
@@ -3891,8 +4627,15 @@ declare class BatchedRenderer extends TransformNode {
     setMeshLighting(lighting: Partial<MeshLightingSettings>): void;
     /** A copy of the light set with {@link setMeshLighting}. */
     getMeshLighting(): MeshLightingSettings;
+    /**
+     * Turns on adaptive performance: the renderer measures its own update and thins every system's
+     * emission while it runs over budget, see {@link AdaptivePerformanceOptions}. Options left out
+     * keep their current values.
+     */
     configureAdaptivePerformance(options?: Partial<AdaptivePerformanceOptions>): void;
+    /** Turns adaptive performance off, and by default puts every system back at `maxQuality`. */
     disableAdaptivePerformance(resetQuality?: boolean): void;
+    /** A copy of the adaptive performance settings and the current quality. */
     getAdaptivePerformanceState(): AdaptivePerformanceState;
     private applyAdaptiveQuality;
     /** @internal Called when a system's behaviors change, which can add a sub emitter. */
@@ -3906,6 +4649,11 @@ declare class BatchedRenderer extends TransformNode {
      * cannot be satisfied by any order; it is left as found rather than dropped.
      */
     private orderSystems;
+    /**
+     * Advances every visible system by `delta` seconds and refills the batches. Call it once per
+     * frame. A system whose emitter is disabled is frozen; one no camera sees pauses if its
+     * {@link ParticleSystem.cullingMode} says so.
+     */
     update(delta: number): void;
     /** Rebuild instance buffers from current particle state without advancing simulation. */
     refreshBatches(): void;
@@ -3913,17 +4661,25 @@ declare class BatchedRenderer extends TransformNode {
     private removeBatch;
     /** Per-batch particle vs GPU instance counts — for diagnosing stale render state. */
     getBatchRenderStats(): Array<{
+        /** Index into {@link batches}. */
         batchIndex: number;
+        /** The batch's render mode. */
         renderMode: RenderMode;
+        /** Instances the batch mesh draws. */
         instanceCount: number;
+        /** Live particles of the batch's systems. */
         particleCount: number;
+        /** The emitter names of the batch's systems. */
         systemNames: string[];
     }>;
+    /**
+     * Disposes the batches and their meshes and materials, and lets the systems go: they keep
+     * their particles and can be added to another renderer. The renderer cannot be used again.
+     */
     dispose(): void;
 }
 
-declare const BatchedParticleRenderer: typeof BatchedRenderer;
-
+/** Options for a new {@link EffectPool}. */
 interface EffectPoolOptions {
     /** The renderer every copy the pool makes is added to. */
     renderer: BatchedRenderer;
@@ -3983,33 +4739,53 @@ declare class EffectPool {
 
 /** Reads the six face URLs from a Babylon CubeTexture (px py pz nx ny nz). */
 declare function cubeFaceUrls(reflection: BaseTexture | null | undefined): string[] | null;
-/** Returns a previously built atlas for this cube, if any. */
-declare function getCachedEnvAtlas(cube: BaseTexture): Texture | null;
-/** Stores an atlas for a cube source (tests / prebuilt atlases). */
+/**
+ * Returns the atlas already built or cached for this cube in `scene`, if any.
+ *
+ * @param cube - The cube texture the atlas was made from.
+ * @param scene - The scene the atlas must belong to. Defaults to the cube's own scene.
+ */
+declare function getCachedEnvAtlas(cube: BaseTexture, scene?: Scene | null): Texture | null;
+/**
+ * Stores a prebuilt atlas for a cube in the atlas's scene, so systems that use the cube in that
+ * scene take it instead of building one. The atlas stays the caller's: quarks never disposes it,
+ * and drops it from the cache when it, or the cube, is disposed.
+ *
+ * @param cube - The cube texture the atlas stands in for.
+ * @param atlas - A 3×2 atlas in the layout of {@link createEnvAtlasFromFaceUrls}.
+ */
 declare function cacheEnvAtlas(cube: BaseTexture, atlas: Texture): void;
+/**
+ * Drops the atlases made for `cube` from the cache and disposes the ones quarks built. Runs by
+ * itself when the cube is disposed; call it when an environment is swapped out but the cube is
+ * kept. Systems that use the cube build a new atlas the next time their material is resolved.
+ *
+ * @param cube - The cube texture whose atlases to drop.
+ * @param scene - Only the atlas for this scene. Defaults to every scene.
+ */
+declare function disposeEnvAtlas(cube: BaseTexture, scene?: Scene): void;
 /**
  * Packs six cube-face images into one 3×2 atlas Texture (px py pz / nx ny nz).
  * Uses invertY:false so UV cellY=0 maps to the +faces row matching the shader.
  */
 declare function createEnvAtlasFromFaceUrls(urls: string[], scene: Scene): Promise<Texture>;
 /**
- * Ensures a 3×2 env atlas exists for a CubeTexture. Returns a cached atlas
- * synchronously when available; otherwise starts (or joins) an async build and
- * invokes onReady when the atlas is usable.
+ * Ensures a 3×2 env atlas exists for a CubeTexture in `scene`. Returns a cached atlas
+ * synchronously when available; otherwise starts (or joins) an async build and invokes onReady
+ * when the atlas is usable. A cube disposed before its build finishes gets no atlas.
  */
 declare function ensureEnvAtlasFromCube(cube: BaseTexture, scene: Scene, onReady: (atlas: Texture) => void): Texture | null;
 
-type BabylonParticleMaterialParameters = Record<string, any>;
-declare class ParticleMeshStandardMaterial extends StandardMaterial {
-    readonly isParticleMeshStandardMaterial = true;
-    constructor(name: string, scene?: Scene, parameters?: BabylonParticleMaterialParameters);
-}
-declare class ParticleMeshPhysicsMaterial extends PBRMaterial {
-    readonly isParticleMeshPhysicsMaterial = true;
-    constructor(name: string, scene?: Scene, parameters?: BabylonParticleMaterialParameters);
-}
-
+/**
+ * Emits from the surface of a Babylon mesh (Unity's Shape: Mesh, Unreal's Skeletal/Static Mesh
+ * Location): a point picked at random over the triangles, weighted by their area, moving along the
+ * triangle's normal at the particle's start speed. The mesh's vertices are read once, when it is
+ * set, in the mesh's own space, and laid in the emitter's space as they are, moved by
+ * {@link transform}; moving the mesh node afterwards does not move the shape. A shape without a
+ * mesh emits from the origin along +Z.
+ */
 declare class MeshSurfaceEmitter implements EmitterShape {
+    /** The shape's type in effect files. */
     type: string;
     private _triangleIndexToArea;
     private _mesh?;
@@ -4018,18 +4794,45 @@ declare class MeshSurfaceEmitter implements EmitterShape {
     private _meshReferenceId?;
     /** Offset, rotation and scale of the mesh within the particle system. */
     transform?: ShapeTransform;
+    /** The mesh emitted from. Setting it reads its positions and indices; a mesh without both emits from the origin. */
     get mesh(): Mesh | undefined;
     set mesh(mesh: Mesh | undefined);
+    /**
+     * @param mesh The mesh to emit from.
+     * @param meshReferenceId The id of a mesh node in the effect file, kept until the loader links it.
+     * @param transform Offset, rotation and scale of the mesh within the system.
+     */
     constructor(mesh?: Mesh, meshReferenceId?: string, transform?: ShapeTransform);
+    /** Places a new particle on the surface and sets its velocity along the triangle's normal. */
     initialize(p: Particle): void;
+    /** The shape in effect-file form; the mesh is written as its node id. */
     toJSON(): ShapeJSON;
+    /** Reads {@link toJSON} output; the mesh stays an id until `QuarksLoader` links it. */
     static fromJSON(json: any): MeshSurfaceEmitter;
+    /** A copy emitting from the same mesh. */
     clone(): EmitterShape;
+    /** Does nothing: the shape keeps no state between steps. */
     update(_system: IParticleSystem, _delta: number): void;
 }
+/** Registers {@link MeshSurfaceEmitter} with quarks.core's shape table; loaded when the package is imported. */
 declare const MeshSurfaceEmitterPlugin: Plugin;
 
+/**
+ * The id an effect file knows a node by: the uuid it was loaded under, or, for a node made in code,
+ * a GUID given to it the first time it is asked for and kept from then on. Every link written into
+ * a file (a sub emitter's target, a mesh surface shape's mesh, a prefab animation's target) and
+ * every node's own `uuid` use this, so an effect loaded, saved and loaded again keeps its links,
+ * and a node made in code never takes the id of one loaded from a file.
+ */
+declare function quarksNodeId(node: object): string;
+
+/**
+ * The Babylon node a particle system lives at: its position, rotation and scale place the system,
+ * parenting it moves the effect with another node, and disabling it freezes and hides the system.
+ * Every {@link ParticleSystem} makes its own, as `system.emitter`.
+ */
 declare class ParticleEmitter extends TransformNode {
+    /** The particle system this node carries. */
     system: IParticleSystem;
     private _matrixWorld;
     private _matrixWorldFlag;
@@ -4039,21 +4842,45 @@ declare class ParticleEmitter extends TransformNode {
      * `updateFlag`), so repeated reads inside a frame are free.
      */
     get matrixWorld(): Matrix4;
+    /** Whether the node and its parents are enabled; setting it is `setEnabled`. */
     get visible(): boolean;
     set visible(value: boolean);
+    /** The id effect files know this emitter by; see {@link quarksNodeId}. */
     get uuid(): string;
     constructor(system: IParticleSystem, scene?: Scene);
-    dispose(): void;
-    extractFromCache(cache: any): any[];
+    /**
+     * Disposes the node and the particle system it carries, so `root.dispose()` on an effect tree
+     * also removes its systems from their renderer. Safe to call more than once. When a system
+     * disposes its own emitter (`ParticleSystem.dispose()`, `autoDestroy`), the systems of child
+     * emitters keep playing until they finish or are disposed themselves.
+     */
+    dispose(doNotRecurse?: boolean, disposeMaterialAndTextures?: boolean): void;
     clone(name?: string): ParticleEmitter;
+    /** The node and its system in effect-file form; `serializeEffect` writes whole effects. @internal */
     toJSON(meta?: any, options?: SerializationOptions): any;
 }
 
+/**
+ * One burst of a system's emission (Unity's Emission Bursts): `count` particles at `time` seconds
+ * into each loop, repeated `cycle` times `interval` seconds apart, each wave with the chance
+ * `probability`. A burst given to the constructor or read from a file is normalised (a missing
+ * `interval` is 0.1 s, `probability` is kept to 0..1, `cycle` to at least 1) and the bursts are
+ * kept in time order.
+ */
 interface BurstParameters {
+    /** Seconds into the system's duration the first wave fires at. */
     time: number;
+    /**
+     * Particles each wave spawns. The generator is rolled when the system plays or restarts, so
+     * a random count is the same for every loop of one play; a curve is read at the wave's time
+     * as a fraction of the duration, 0 to 1, like the start curves.
+     */
     count: ValueGenerator | FunctionValueGenerator;
+    /** How many waves the burst fires, at least 1. */
     cycle: number;
+    /** Seconds between waves; 0 fires them all at once. 0.1 when left out. */
     interval: number;
+    /** Chance from 0 to 1 that a wave spawns at all, rolled per wave. */
     probability: number;
 }
 /**
@@ -4092,38 +4919,69 @@ type ScalingMode = 'shape' | 'hierarchy';
  * every frame.
  */
 type BeamEnd = {
+    /** World x. */
     x: number;
+    /** World y. */
     y: number;
+    /** World z. */
     z: number;
 } | {
+    /** The world position, read every frame. */
     getAbsolutePosition(): {
+        /** World x. */
         x: number;
+        /** World y. */
         y: number;
+        /** World z. */
         z: number;
     };
 };
+/**
+ * Settings for a new {@link ParticleSystem}. Every one is optional: a setting left out takes the
+ * default named on it, the same default `fromJSON` gives a file that leaves it out.
+ */
 interface ParticleSystemParameters {
+    /** See {@link ParticleSystem.autoDestroy}. Default false. */
     autoDestroy?: boolean;
+    /** See {@link ParticleSystem.looping}. Default true. */
     looping?: boolean;
+    /** See {@link ParticleSystem.prewarm}. Default false. */
     prewarm?: boolean;
+    /** See {@link ParticleSystem.prewarmTime}. Default 0: a whole cycle; only with `prewarm` on a looping system. */
+    prewarmTime?: number;
+    /** See {@link ParticleSystem.duration}. Default 1 second. */
     duration?: number;
+    /** See {@link ParticleSystem.startDelay}. Default 0. */
     startDelay?: ValueGenerator | FunctionValueGenerator;
+    /** Where particles are born and which way they start, see {@link ParticleSystem.emitterShape}. Default a `SphereEmitter`. */
     shape?: EmitterShape;
+    /** See {@link ParticleSystem.startLife}. Default 5 seconds. */
     startLife?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.startSpeed}. Default 0. */
     startSpeed?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.startRotation}. Default 0. */
     startRotation?: ValueGenerator | FunctionValueGenerator | RotationGenerator;
+    /** See {@link ParticleSystem.startSize}. Default 1. */
     startSize?: ValueGenerator | FunctionValueGenerator | Vector3Generator;
-    startLength?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.startColor}. Default opaque white. */
     startColor?: ColorGenerator | FunctionColorGenerator;
+    /** See {@link ParticleSystem.emissionOverTime}. Default 10 per second. */
     emissionOverTime?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.emissionOverDistance}. Default 0. */
     emissionOverDistance?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.emissionBursts}. Default none. */
     emissionBursts?: Array<BurstParameters>;
     /** Most particles alive at once; emission past it is dropped. Leave unset for no limit. */
     maxParticles?: number;
+    /** See {@link ParticleSystem.onlyUsedByOther}. Default false. */
     onlyUsedByOther?: boolean;
+    /** See {@link ParticleSystem.behaviors}. Default none. */
     behaviors?: Array<Behavior>;
+    /** Mesh particles' vertex positions, three values per vertex. Default a unit quad in XY. */
     instancingGeometry?: Float32Array;
+    /** Triangle indices into {@link instancingGeometry}. Default the unit quad's two triangles. */
     instancingIndices?: Uint32Array | Uint16Array;
+    /** Mesh particles' first UV set, two values per vertex. Default the quad's UVs, or zeros for another geometry. */
     instancingUVs?: Float32Array;
     /**
      * A second UV set for the mesh (glTF `TEXCOORD_1`, Unity's `uv2`), what
@@ -4131,26 +4989,55 @@ interface ParticleSystemParameters {
      * Default none: channel 1 reads the first set.
      */
     instancingUVs2?: Float32Array;
+    /** Mesh particles' vertex normals, three values per vertex. Default +Z for every vertex. */
     instancingNormals?: Float32Array;
+    /** See {@link ParticleSystem.renderMode}. Default `RenderMode.BillBoard`. */
     renderMode?: RenderMode;
+    /** See {@link ParticleSystem.rendererEmitterSettings}. Default the render mode's own. */
     rendererEmitterSettings?: RendererEmitterSettings;
+    /** @deprecated Set `speedFactor` in {@link rendererEmitterSettings} instead; this one wins when both are set. */
     speedFactor?: number;
-    material?: any;
+    /** See {@link ParticleSystem.material}. Default none. */
+    material?: unknown;
+    /** See {@link ParticleSystem.texture}. Unset takes the material's texture; null draws without one. */
     texture?: Texture | null;
+    /** See {@link ParticleSystem.startTileIndex}. Default 0. */
     startTileIndex?: ValueGenerator;
+    /** See {@link ParticleSystem.uTileCount}. Default 1. */
     uTileCount?: number;
+    /** See {@link ParticleSystem.vTileCount}. Default 1. */
     vTileCount?: number;
+    /** See {@link ParticleSystem.blendTiles}. Default false. */
     blendTiles?: boolean;
+    /**
+     * Fade particles out as they near the scene behind them, like Unity's Soft Particles and
+     * Unreal's Depth Fade, between `softNearFade` and `softFarFade` world units. Needs a depth
+     * texture, see `BatchedRenderer.setDepthTexture`; without one particles draw hard. Applies to
+     * every render mode: billboard, stretched, mesh, beam and trail.
+     */
     softParticles?: boolean;
+    /** See {@link ParticleSystem.softFarFade}. Default 1. */
     softFarFade?: number;
+    /** See {@link ParticleSystem.softNearFade}. Default 0. */
     softNearFade?: number;
+    /** See {@link ParticleSystem.renderOrder}. Default 0. */
     renderOrder?: number;
+    /** See {@link ParticleSystem.worldSpace}. Default false. */
     worldSpace?: boolean;
+    /** Babylon alpha mode the batch blends with, see {@link ParticleSystem.blending}. Default `Constants.ALPHA_ADD`. */
     blendMode?: number;
+    /** Whether the batch draws in the transparent pass. Default true. */
     transparent?: boolean;
+    /**
+     * Whether particles are hidden behind nearer geometry. `false` draws them over everything
+     * (Unity's `ZTest Always`), in every render mode. Default `true`.
+     */
     depthTest?: boolean;
+    /** Whether the particles write depth. Default false. */
     depthWrite?: boolean;
+    /** Alpha below which a fragment is discarded, 0 to 1. Default 0: nothing is. */
     alphaTest?: number;
+    /** Camera layer mask the batch draws for, see {@link ParticleSystem.layers}. Default `0x0fffffff`. */
     layerMask?: number;
     /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
     pivot?: Vector3;
@@ -4188,36 +5075,79 @@ interface ParticleSystemParameters {
     renderingGroupId?: number;
     /** Whether the scene's fog applies, see {@link ParticleSystem.applyFog}. Default true. */
     applyFog?: boolean;
+    /** Scene the emitter node is created in. Default Babylon's last created scene. */
     scene?: Scene;
 }
+/** A {@link BurstParameters} in an effect file. A plain number `count` is read as a constant. */
 interface BurstParametersJSON {
+    /** See {@link BurstParameters.time}. */
     time: number;
+    /** See {@link BurstParameters.count}. */
     count: FunctionJSON | number;
+    /** See {@link BurstParameters.cycle}. */
     cycle: number;
+    /** See {@link BurstParameters.interval}. */
     interval: number;
+    /** See {@link BurstParameters.probability}. */
     probability: number;
 }
+/**
+ * A particle system in an effect file, as {@link ParticleSystem.toJSON} writes it and
+ * {@link ParticleSystem.fromJSON} reads it; `docs/FORMAT.md` describes the document around it.
+ * Each field mirrors the {@link ParticleSystem} member of the same name. Curves and generators
+ * are written as quarks.core's `FunctionJSON`; textures, materials and geometries as uuids into
+ * the document. Most settings are written only when they differ from their default, and a field
+ * that is missing reads as the default, so every field but `version` is optional. The shape, the
+ * start and emission curves except `startDelay`, `startTileIndex`, `instancingGeometry`, `material`
+ * and `behaviors` are always written, because older loaders and three.quarks need them.
+ */
 interface ParticleSystemJSONParameters {
+    /** The quarks.core version line the system was written with. */
     version: string;
-    autoDestroy: boolean;
-    looping: boolean;
-    prewarm: boolean;
-    duration: number;
+    /** See {@link ParticleSystem.autoDestroy}. */
+    autoDestroy?: boolean;
+    /** See {@link ParticleSystem.looping}. */
+    looping?: boolean;
+    /** See {@link ParticleSystem.prewarm}. */
+    prewarm?: boolean;
+    /** See {@link ParticleSystem.prewarmTime}. */
+    prewarmTime?: number;
+    /** See {@link ParticleSystem.duration}. */
+    duration?: number;
+    /** See {@link ParticleSystem.startDelay}. */
     startDelay?: FunctionJSON;
-    shape: any;
-    startLife: FunctionJSON;
-    startSpeed: FunctionJSON;
-    startRotation: FunctionJSON;
-    startSize: FunctionJSON;
-    startColor: FunctionJSON;
-    emissionOverTime: FunctionJSON;
-    emissionOverDistance: FunctionJSON;
+    /** The emitter shape, as its `toJSON` writes it. */
+    shape?: any;
+    /** See {@link ParticleSystem.startLife}. */
+    startLife?: FunctionJSON;
+    /** See {@link ParticleSystem.startSpeed}. */
+    startSpeed?: FunctionJSON;
+    /** See {@link ParticleSystem.startRotation}. */
+    startRotation?: FunctionJSON;
+    /** See {@link ParticleSystem.startSize}. */
+    startSize?: FunctionJSON;
+    /** See {@link ParticleSystem.startColor}. */
+    startColor?: FunctionJSON;
+    /** See {@link ParticleSystem.emissionOverTime}. */
+    emissionOverTime?: FunctionJSON;
+    /** See {@link ParticleSystem.emissionOverDistance}. */
+    emissionOverDistance?: FunctionJSON;
+    /** See {@link ParticleSystem.emissionBursts}. */
     emissionBursts?: Array<BurstParametersJSON>;
+    /** See {@link ParticleSystem.maxParticles}. */
     maxParticles?: number;
-    onlyUsedByOther: boolean;
-    rendererEmitterSettings: RendererEmitterSettings;
+    /** See {@link ParticleSystem.onlyUsedByOther}. */
+    onlyUsedByOther?: boolean;
+    /**
+     * Trail, stretched or mesh settings; a trail's `startLength` as `FunctionJSON`. Left out when
+     * the render mode has none.
+     */
+    rendererEmitterSettings?: RendererEmitterSettings;
+    /** Uuid of the mesh particles' geometry entry. */
     instancingGeometry?: any;
-    renderMode: number;
+    /** A {@link RenderMode} value. */
+    renderMode?: number;
+    /** See {@link ParticleSystem.renderOrder}. */
     renderOrder?: number;
     /** Written only when not 0. */
     renderingGroupId?: number;
@@ -4239,68 +5169,154 @@ interface ParticleSystemJSONParameters {
     minParticleSize?: number;
     /** Written only when limited. */
     maxParticleSize?: number;
+    /** A stretched billboard's speed factor, as older files wrote it outside `rendererEmitterSettings`. */
     speedFactor?: number;
+    /** Uuid of the texture entry. */
     texture?: string;
+    /** Uuid of the material entry. */
     material?: string;
+    /** The camera layer mask. */
     layers?: number;
-    startTileIndex: FunctionJSON | number;
-    uTileCount: number;
-    vTileCount: number;
+    /** See {@link ParticleSystem.startTileIndex}. */
+    startTileIndex?: FunctionJSON | number;
+    /** See {@link ParticleSystem.uTileCount}. */
+    uTileCount?: number;
+    /** See {@link ParticleSystem.vTileCount}. */
+    vTileCount?: number;
+    /** See {@link ParticleSystem.blendTiles}. */
     blendTiles?: boolean;
+    /** See {@link ParticleSystem.softParticles}. */
     softParticles?: boolean;
+    /** See {@link ParticleSystem.softFarFade}. */
     softFarFade?: number;
+    /** See {@link ParticleSystem.softNearFade}. */
     softNearFade?: number;
+    /** See {@link ParticleSystem.blending}. */
     blending?: number;
+    /** See {@link ParticleSystemParameters.transparent}. */
     transparent?: boolean;
+    /** See {@link ParticleSystemParameters.depthTest}. */
     depthTest?: boolean;
+    /** See {@link ParticleSystemParameters.depthWrite}. */
     depthWrite?: boolean;
+    /** See {@link ParticleSystemParameters.alphaTest}. */
     alphaTest?: number;
-    behaviors: Array<any>;
-    worldSpace: boolean;
+    /** Each behavior as its `toJSON` writes it. */
+    behaviors?: Array<any>;
+    /** See {@link ParticleSystem.worldSpace}. */
+    worldSpace?: boolean;
     /** `[x, y, z]`; written only when non-zero. */
     pivot?: number[];
     /** `[u, v]`; written only when non-zero. */
     flip?: number[];
 }
+/**
+ * The resources of one effect document, by uuid: what {@link ParticleSystem.toJSON} writes a
+ * system's geometry, material and texture into, and what {@link ParticleSystem.fromJSON} resolves
+ * them from. While writing, entries hold live Babylon objects; `serializeEffect` turns them into
+ * plain data.
+ */
 interface BabylonMetaData {
+    /** Textures by uuid; null for one that could not be made. */
     textures: {
         [uuid: string]: Texture | null;
     };
+    /** Material entries by uuid. */
     materials: {
         [uuid: string]: any;
     };
+    /** Geometry entries by uuid. */
     geometries: {
         [uuid: string]: any;
     };
+    /** Image entries by uuid. */
     images?: {
         [uuid: string]: any;
     };
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
     shapes?: {
         [uuid: string]: any;
     };
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
     skeletons?: {
         [uuid: string]: any;
     };
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
     animations?: {
         [uuid: string]: any;
     };
+    /** Nodes by uuid, which a mesh surface shape links to. */
     nodes?: {
         [uuid: string]: any;
     };
 }
+
+/**
+ * A particle system, the counterpart of a Unity Shuriken system or a Niagara emitter: it spawns
+ * particles from an {@link emitterShape}, gives them start values, runs its {@link behaviors} on
+ * them every step and hands them to a {@link BatchedRenderer} to draw.
+ *
+ * The system lives at its {@link emitter}, a Babylon node: move, parent or disable that to place
+ * the effect. Add the system to a renderer with `renderer.addSystem(system)`; the renderer
+ * advances it every frame on a fixed 60 Hz step and batches it with systems that draw alike.
+ *
+ * Curves and random values are quarks.core generators (`ConstantValue`, `IntervalValue`,
+ * `PiecewiseBezier`, `Gradient`, ...); a curve's x is the system's time over its duration for
+ * start values and emission, and the particle's age over its life inside behaviors.
+ */
 declare class ParticleSystem implements IParticleSystem {
-    private static serializationCounter;
+    /** Dispose the system, its emitter and its batch slot when it finishes. Default false. */
     autoDestroy: boolean;
+    /**
+     * Start a looping system as if it had already run one full cycle (Unity's Prewarm), so a fire
+     * or a mist is full from its first frame. Default false.
+     */
     prewarm: boolean;
+    /**
+     * How much of the cycle {@link prewarm} simulates before the first frame, in seconds
+     * (Niagara's Warmup Time), on a looping system like `prewarm` itself. 0, the default, warms up a whole cycle, as Unity's Prewarm does; a
+     * shorter time warms up the cycle's last part only, with the bursts before it counted as
+     * fired, which is enough for an effect whose particles live shorter than its cycle and keeps
+     * a long cycle's first frame cheap. Longer than the cycle or than
+     * {@link maxPrewarmSeconds}, it is cut to them. Kept at 0 or above.
+     */
+    get prewarmTime(): number;
+    set prewarmTime(seconds: number);
+    private prewarmTimeValue;
+    /** Start the cycle again when {@link duration} ends instead of stopping emission. Default true. */
     looping: boolean;
-    duration: number;
+    /**
+     * Length of one emission cycle in seconds; curves over the system's time run over it. Default
+     * 1, and never shorter than one simulation step: a zero, negative or NaN duration is read as
+     * one step, so bursts at time 0 fire and the cycle ends.
+     */
+    get duration(): number;
+    set duration(seconds: number);
+    private durationValue;
+    /** Seconds before the system first emits, rolled on each restart. Default 0. */
     startDelay: ValueGenerator | FunctionValueGenerator;
+    /** Seconds each particle lives, rolled at birth. Default 5. */
     startLife: ValueGenerator | FunctionValueGenerator;
+    /** Speed each particle starts with along the direction its shape gives it, in units per second. Default 0. */
     startSpeed: ValueGenerator | FunctionValueGenerator;
+    /**
+     * Rotation each particle starts with: an angle in radians around the view axis for billboards,
+     * or a rotation generator (`AxisAngleGenerator`, `EulerGenerator`, `RandomQuatGenerator`) for
+     * mesh particles. Default 0.
+     */
     startRotation: ValueGenerator | FunctionValueGenerator | RotationGenerator;
+    /** Size each particle starts with in world units; a `Vector3Generator` sizes each axis (Unity's 3D Start Size). Default 1. */
     startSize: ValueGenerator | FunctionValueGenerator | Vector3Generator;
+    /** Colour and alpha each particle starts with, multiplied with the texture. Default opaque white. */
     startColor: ColorGenerator | FunctionColorGenerator;
+    /** Flipbook cell each particle starts on, counted across rows, see {@link uTileCount}. Default 0. */
     startTileIndex: ValueGenerator;
+    /**
+     * The render mode's own settings: `TrailSettings` for a trail (`startLength` and the trail
+     * flags), `StretchedBillBoardSettings` for a stretched billboard (`speedFactor`,
+     * `lengthFactor`), `MeshSettings` or nothing otherwise. Setting {@link renderMode} replaces it
+     * with that mode's defaults.
+     */
     rendererEmitterSettings: RendererEmitterSettings;
     /**
      * Fraction of billboard particles mirrored along U (x) and V (y), each
@@ -4308,57 +5324,95 @@ declare class ParticleSystem implements IParticleSystem {
      * Undefined: nothing is mirrored. Meshes ignore it.
      */
     flip?: Vector2;
+    /** Particles emitted per second, read over the system's time. Default 10. */
     emissionOverTime: ValueGenerator | FunctionValueGenerator;
+    /** Particles emitted per world unit the emitter moves (Unity's Rate over Distance). Default 0. */
     emissionOverDistance: ValueGenerator | FunctionValueGenerator;
+    /** Bursts of particles at set times in each cycle. Default none. */
     emissionBursts: Array<BurstParameters>;
-    /** Most particles alive at once (Unity's Max Particles); emission past it is dropped. Undefined means no limit. */
+    /**
+     * Most particles alive at once (Unity's Max Particles); emission past it is dropped. Undefined
+     * means no limit, as does a negative or NaN count given to the constructor; a fraction is
+     * rounded down.
+     */
     maxParticles?: number;
+    /**
+     * The system emits nothing of its own and only spawns what an `EmitSubParticleSystem` on
+     * another system sends it (a Unity sub emitter). Default false.
+     */
     onlyUsedByOther: boolean;
+    /**
+     * Simulate in world space (Unity's Simulation Space: World): particles stay where they were
+     * born when the emitter moves. False keeps them in the emitter's space, so they move with it.
+     * Default false.
+     */
     worldSpace: boolean;
+    /** How many of {@link particles} are alive. Read only. */
     particleNum: number;
+    /** Set by {@link pause}: the renderer skips the system's simulation while true. */
     paused: boolean;
+    /** The particle pool; the first {@link particleNum} are alive. Read only. */
     particles: Array<Particle>;
-    /** Column storage shared by this system's particles. */
+    /** Column storage shared by this system's particles; behaviors read and write it. */
     readonly store: ParticleStore;
+    /** Where particles are born and which way they start (Unity's Shape module). Default a `SphereEmitter`. */
     emitterShape: EmitterShape;
+    /** The node the system lives at; move, parent or disable it to place or hide the effect. */
     emitter: ParticleEmitter;
+    /** What the renderer batches on; read it with {@link getRendererSettings}. @internal */
     rendererSettings: VFXBatchSettings;
+    /**
+     * Set when a render setting changed, so the renderer moves the system to a matching batch.
+     * The system's setters set it; set it yourself after changing {@link getRendererSettings} directly.
+     */
     neededToUpdateRender: boolean;
+    /** Modules run on every particle each step, in order (`ColorOverLife`, `SizeOverLife`, forces, ...). */
     behaviors: Array<Behavior>;
+    /** Emission progress: time in the cycle, burst and distance counters. */
     emissionState: EmissionState;
+    /** The emitter's velocity over the last step, which `InheritVelocity` reads. */
     emitterVelocity: Vector3;
     private prewarmed;
     private emitEnded;
-    private markForDestroy;
-    private finishedEventFired;
-    private startDelayTimeLeft;
+    /**
+     * Whether `finished` fired for this play; the spawner clears it when a sub emission refills an
+     * empty target.
+     * @internal
+     */
+    finishedEventFired: boolean;
+    /** The fixed-step clock: whole steps per frame, start delay and catch-up time. */
+    private readonly clock;
     private previousEmitterPos?;
     private tempEmitterPos;
-    private temp;
-    /** Emitter matrix moved along the step's path, see spawnAlongPath. */
-    private pathMatrix;
-    private normalMatrix;
-    private memory;
-    private listeners;
+    /** The emitter matrix the last simulated step used, to interpolate from; see {@link update}. */
+    private previousEmitterMatrix?;
+    /** The emitter matrix handed to each step of a frame, moved along the emitter's path. */
+    private readonly stepMatrix;
+    /** Makes the newborn particles, see {@link ParticleSpawner}. */
+    private readonly spawner;
+    /** Decides how many particles each step owes, see {@link EmissionController}. */
+    private readonly emission;
+    private readonly events;
     private readonly layerMaskProxy;
     private materialRef;
     private sceneRef;
     private qualityFactor;
-    private simulationAccumulator;
     private destroyed;
-    /** Behaviors the cached plan was built from, compared by identity. */
-    private fusionPlan?;
-    private fusionSteps;
-    /**
-     * Whether any behavior in the plan can change a particle's size or colour
-     * after birth. Only then does a step have to snapshot them for the renderer.
-     */
-    private planChangesSize;
-    private planChangesColor;
+    /** How the behaviors run each step, rebuilt when the list changes. */
+    private readonly behaviorPlan;
     /** @internal **/
     _renderer?: BatchedRenderer;
+    /**
+     * Seconds into the current emission cycle. Setting it jumps emission to that point, as Unity's
+     * `Simulate(t)` does for the emission clock: the bursts before it count as fired, the ones
+     * after are due again; particles alive stay, and behaviors are not reset. A value that is not
+     * a finite, non-negative number is 0; one past the duration wraps on a looping system and is
+     * the duration otherwise. A system whose emission has ended stays ended: {@link restart} plays
+     * it again.
+     */
     set time(time: number);
     get time(): number;
+    /** Whether {@link endEmit} ran, or a non-looping system reached the end of its duration. */
     get isEmitEnded(): boolean;
     /** Whether continuous or queued emission can still spawn particles before the system is done. */
     hasPendingEmission(): boolean;
@@ -4368,26 +5422,58 @@ declare class ParticleSystem implements IParticleSystem {
      * {@link endEmit} and whose last particle has died.
      */
     isFinished(): boolean;
+    /**
+     * The camera layer mask the particles draw for (Babylon's `mesh.layerMask`), as
+     * `system.layers.mask`. Default `0x0fffffff`, every camera's default mask. Systems that differ
+     * are batched apart.
+     */
     get layers(): {
+        /** The mask; setting it moves the system to a matching batch. */
         mask: number;
     };
+    /**
+     * The particles' main texture, multiplied with their colour; a flipbook when
+     * {@link uTileCount} or {@link vTileCount} is above 1. Null draws the colour alone. Systems
+     * with different textures are batched apart.
+     */
     get texture(): Texture | null;
     set texture(texture: Texture | null);
+    /**
+     * A Babylon material the system takes its draw settings from (on a loaded system, the material
+     * record of its file): its texture (`albedoTexture`,
+     * `diffuseTexture`, `emissiveTexture` or `opacityTexture`), alpha mode, depth flags, alpha test
+     * and reflection texture. The material itself
+     * is not drawn with; particles always use quarks' own shaders. Null leaves the settings as they
+     * are.
+     */
     get material(): any;
     set material(material: any);
+    /**
+     * Columns of the flipbook in {@link texture} (Unity's Texture Sheet Animation tiles). With
+     * {@link vTileCount}, a particle draws one cell, picked by {@link startTileIndex} and
+     * `FrameOverLife`. A whole number of at least 1; anything else is 1. Default 1. Trails take
+     * their cell on the CPU, so a trail's texture is cut the same way.
+     */
     get uTileCount(): number;
     set uTileCount(u: number);
+    /** Rows of the flipbook in {@link texture}, see {@link uTileCount}. Default 1. */
     get vTileCount(): number;
     set vTileCount(v: number);
+    /**
+     * Cross-fade between a flipbook's cells instead of cutting from one to the next (Unity's
+     * Flip-Book Blending); the last cell fades into the first. Default false. Needs a sheet
+     * (`uTileCount` or `vTileCount` above 1); trails cut their cell on the CPU and do not blend.
+     */
     get blendTiles(): boolean;
     set blendTiles(v: boolean);
-    get softParticles(): boolean;
-    set softParticles(v: boolean);
     /**
-     * Billboard pivot in particle-size units (Unity's renderer Pivot), see
-     * {@link VFXBatchSettings.pivot}. Assign a new vector to change it: editing
-     * the returned one in place does not reach the renderer.
+     * Fade particles out as they near the scene behind them (Unity's Soft Particles, Unreal's
+     * Depth Fade), between {@link softNearFade} and {@link softFarFade}. Needs a depth texture on
+     * the renderer, see `BatchedRenderer.setDepthTexture`; without one particles draw hard.
+     * Default false.
      */
+    get softParticles(): boolean;
+    set softParticles(v: boolean);
     /**
      * The order this system's batch draws its particles in (Unity's Sort
      * Mode), `'none'` by default. Alpha blended smoke wants `'distance'`;
@@ -4411,6 +5497,11 @@ declare class ParticleSystem implements IParticleSystem {
      */
     get maxParticleSize(): number;
     set maxParticleSize(size: number);
+    /**
+     * Billboard pivot in particle-size units (Unity's renderer Pivot), see
+     * {@link VFXBatchSettings.pivot}. Assign a new vector to change it: editing
+     * the returned one in place does not reach the renderer.
+     */
     get pivot(): Vector3 | undefined;
     set pivot(v: Vector3 | undefined);
     /**
@@ -4480,38 +5571,108 @@ declare class ParticleSystem implements IParticleSystem {
      * before every step; what `'hierarchy'` multiplies start speeds by. Taken
      * from the system's own emitter rather than the emission matrix, whose
      * columns carry a parent particle's velocity for a sub emitter.
+     * @internal
      */
-    private readonly hierarchyScale;
+    readonly hierarchyScale: Vector3;
     /** The mean world scale of the emitter for a world-space `'hierarchy'` system, else 1. */
     private measureMotionScale;
-    /** `lighting` if it is one of the modes, else the default. */
-    private static validLighting;
-    private static validSortMode;
-    private static validCullingMode;
-    private static nonZeroPivot;
-    private static nonZeroFlip;
+    /**
+     * Distance in world units in front of the scene at which a soft particle is fully faded out,
+     * at least 0. Default 0. A live parameter: changing it on a system alone in its batch keeps
+     * the batch and its material (see {@link VFXBatchSettings}).
+     */
     get softNearFade(): number;
     set softNearFade(v: number);
+    /**
+     * Distance in world units in front of the scene at which a soft particle is fully opaque, at
+     * least 0. Default 1 (Unreal's Depth Fade distance): the particle fades over the last unit
+     * before the scene. A value at or below {@link softNearFade} cuts the particle off at that
+     * distance instead of fading it. A live parameter, like `softNearFade`.
+     */
     get softFarFade(): number;
     set softFarFade(v: number);
-    get instancingGeometry(): Float32Array;
     /**
-     * The mesh particles' positions. A new geometry with a different vertex
-     * count drops UV sets and normals that no longer fit it: the first UV set
-     * falls back to zeros, the second to none, the normals to +Z. Assign {@link instancingUVs} and
-     * {@link instancingUVs2} after it.
+     * The mesh particles' positions, three values per vertex.
+     * Setting it restarts the system. A new geometry with a different vertex
+     * count drops UV sets, normals and indices that no longer fit it: the first UV set
+     * falls back to zeros, the second to none, the normals to +Z, the indices to the vertex
+     * sequence. Assign {@link instancingUVs}, {@link instancingUVs2} and {@link instancingIndices}
+     * after it.
      */
+    get instancingGeometry(): Float32Array;
     set instancingGeometry(geometry: Float32Array);
+    /**
+     * Gives a mesh system normals when it has none, +Z per vertex, so the mesh shader always has
+     * the attribute it reads. Called on construction and when the render mode or geometry changes.
+     */
+    private ensureMeshNormals;
+    /**
+     * {@link restart} for a setting that rebuilds the particles: the system is cleared and rewound,
+     * but a paused system stays paused, and a stopped one stays stopped.
+     */
+    private restartKeepingPause;
+    /**
+     * The mesh particles' triangle indices into {@link instancingGeometry}. Mesh systems that share
+     * positions but not indices (sub-meshes of one vertex buffer) are batched apart.
+     */
+    get instancingIndices(): Uint32Array | Uint16Array;
+    set instancingIndices(indices: Uint32Array | Uint16Array);
     /** The mesh particles' first UV set, two values per vertex. */
     get instancingUVs(): Float32Array;
     set instancingUVs(uvs: Float32Array);
     /** The mesh particles' second UV set, read by textures on UV channel 1; see `UVChannel`. */
     get instancingUVs2(): Float32Array | undefined;
     set instancingUVs2(uvs: Float32Array | undefined);
+    /**
+     * Babylon alpha mode the particles blend with: `Constants.ALPHA_ADD` (the default) for glows,
+     * `Constants.ALPHA_COMBINE` for smoke and anything alpha blended. Systems that differ are
+     * batched apart.
+     */
     get blending(): number;
     set blending(blending: number);
+    /**
+     * Whether the particles draw in the transparent pass, blended by {@link blending}; false
+     * draws them opaque, with blending off. Default true, or the material's `needAlphaBlending`.
+     * Systems that differ are batched apart.
+     */
+    get transparent(): boolean;
+    set transparent(transparent: boolean);
+    /**
+     * Whether particles are hidden behind nearer geometry; false draws them over everything
+     * (Unity's `ZTest Always`), for overlays and effects seen through walls. Default true, or the
+     * material's `disableDepthTest` inverted. Systems that differ are batched apart.
+     */
+    get depthTest(): boolean;
+    set depthTest(depthTest: boolean);
+    /**
+     * Whether particles write depth, so later draws are hidden behind them. Default false, or the
+     * material's `disableDepthWrite` inverted. Systems that differ are batched apart.
+     */
+    get depthWrite(): boolean;
+    set depthWrite(depthWrite: boolean);
+    /**
+     * Alpha below which a fragment is discarded (Unity's Alpha Clip Threshold), 0…1; 0 (the
+     * default, or the material's `alphaCutOff`) discards nothing but fragments under 0.01, which no
+     * blend mode can show except additive ones with a bright colour. Switching it on or off
+     * rebuilds the batch's material; a change between non-zero cutoffs on a system alone in its
+     * batch is written to the material in place.
+     */
+    get alphaTest(): number;
+    set alphaTest(cutoff: number);
+    /**
+     * How each particle is drawn (Unity's Render Mode): a camera-facing billboard, a stretched
+     * billboard, a horizontal or vertical billboard, a mesh, a trail or a beam, see
+     * {@link RenderMode}. Changing it gives {@link rendererEmitterSettings} the new mode's
+     * defaults, and switching to or from a trail restarts the system. Switching to a mesh makes
+     * {@link startRotation} an `AxisAngleGenerator` about Y, and switching away from one sets it to 0.
+     */
     get renderMode(): RenderMode;
     set renderMode(renderMode: RenderMode);
+    /**
+     * The batch mesh's `alphaIndex`: among the transparent meshes of one rendering group, lower
+     * draws first, whatever the distance (Unity's Order in Layer). Default 0. Systems that differ
+     * are batched apart.
+     */
     get renderOrder(): number;
     set renderOrder(renderOrder: number);
     /**
@@ -4531,17 +5692,23 @@ declare class ParticleSystem implements IParticleSystem {
     /**
      * Multiplier on the time this system is advanced by (Unity's Simulation
      * Speed): 2 runs the effect twice as fast, 0 freezes it without pausing the
-     * renderer. 1 by default; saved in the effect JSON only when it differs.
+     * renderer. 1 by default; saved in the effect JSON only when it differs. A
+     * negative or NaN speed is read as 0, and the clock does not run backwards.
      */
-    playbackSpeed: number;
+    get playbackSpeed(): number;
+    set playbackSpeed(speed: number);
+    private playbackSpeedValue;
     /**
      * Runtime multiplier on how many particles the system emits: bursts,
      * emission over time and over distance alike. Unlike
      * {@link setQualityFactor}, which only ever thins an effect, it may go
      * above 1 to make a stronger version of the same effect. The two multiply.
-     * 1 by default; not saved in the effect JSON.
+     * 1 by default; a negative or NaN value counts as 0. Not saved in the effect JSON; copied by
+     * {@link clone}.
      */
-    emissionMultiplier: number;
+    get emissionMultiplier(): number;
+    set emissionMultiplier(multiplier: number);
+    private emissionMultiplierValue;
     /** What this system does while off screen, see {@link CullingMode}. `'always'` by default. */
     cullingMode: CullingMode;
     /** What the emitter's world scale does to a world-space system, see {@link ScalingMode}. `'shape'` by default. */
@@ -4572,9 +5739,9 @@ declare class ParticleSystem implements IParticleSystem {
      * multiplayer and reproducible tests. Systems this one emits into roll on
      * its generator too. Unset (the default), rolls come from the global source
      * (`setRandomSource` in quarks.core). Saved in the effect JSON when set.
-     *
-     * Not covered: randomness outside the step, such as a `TurbulenceField`'s
-     * offsets, which are rolled when the behavior is created.
+     * The behaviors roll on the same generator, and the ones with their own
+     * randomness (a `TurbulenceField`'s noise) are built from their own seed,
+     * so the whole effect is covered.
      */
     get seed(): number | undefined;
     set seed(seed: number | undefined);
@@ -4584,12 +5751,6 @@ declare class ParticleSystem implements IParticleSystem {
      * @internal
      */
     culled: boolean;
-    /**
-     * Time a `'pauseAndCatchUp'` system has spent off screen and not yet
-     * simulated, in seconds. Capped, so an effect hidden for a minute does not
-     * replay the minute.
-     */
-    private pendingCatchUp;
     /**
      * Time per frame a system coming back into view may spend on the steps it
      * missed, in milliseconds, when it is advanced without a renderer. The
@@ -4597,44 +5758,84 @@ declare class ParticleSystem implements IParticleSystem {
      * instead. Steps that do not fit are dropped, not deferred.
      */
     static catchUpBudgetMs: number;
-    /** Axis-aligned bounds of the live particles, in simulation space. See {@link getWorldBounds}. */
-    private readonly boundsMin;
-    private readonly boundsMax;
-    /** How far a particle's quad, mesh or stretch can reach past its position, in simulation units. */
-    private boundsPadding;
-    private boundsValid;
-    /** Steps since the last full measurement; between them the bounds are carried and padded. */
-    private stepsSinceBounds;
-    private boundsMaxSize;
-    private boundsMaxSpeedSq;
-    /** True when the bounds are already in world space (a world-space system, or bounds the renderer measured). */
-    private boundsInWorld;
-    private geometryRadiusFor?;
-    private geometryRadius;
+    /**
+     * A performance guard on {@link prewarm}, for every system: the most of a cycle it simulates
+     * before the first frame, in seconds. A longer cycle is warmed up over its last
+     * `maxPrewarmSeconds` only, with the burst waves before that counted as fired, so a long
+     * looping effect does not stall its first frame. 10 by default; raise it in an app whose
+     * effects have longer cycles and particles that live longer than that. It is not an effect's
+     * own warm-up time, which is {@link prewarmTime}, and is not saved with one.
+     */
+    static maxPrewarmSeconds: number;
+    /** What the system draws covers, for culling. See {@link getWorldBounds}. */
+    private readonly bounds;
     constructor(parameters: ParticleSystemParameters);
+    /**
+     * When the env atlas this system draws with is disposed (its cube was, or `disposeEnvAtlas`
+     * ran) while the system still uses it, drops it and builds a new one if the cube is still alive,
+     * so the batch never samples a disposed texture.
+     */
+    private watchEnvAtlas;
     private applyMaterialSettings;
+    /** Freezes the system where it is: particles stay and nothing is simulated until {@link play}. */
     pause(): void;
+    /**
+     * Resumes a paused system. It only resumes: a system that has finished ({@link isFinished})
+     * stays finished, since nothing is left to emit; {@link restart} plays it again from the start.
+     */
     play(): void;
+    /** Clears every particle, rewinds to the start ({@link restart}) and pauses until {@link play}. */
     stop(): void;
+    /**
+     * Removes every particle alive and nothing else (Unity's `Clear`): emission goes on from where
+     * it is, paused stays paused, and the bursts and the random generator are not rewound. The
+     * sub emissions the removed particles were driving end with them; the child systems' own
+     * particles stay, and `particleDied` is not fired.
+     */
+    clear(): void;
+    /**
+     * Drops every trail's recorded samples and keeps the particles (Unity's `TrailRenderer.Clear`):
+     * each ribbon starts over from where its particle is now. For a teleport: {@link pause}, move
+     * the emitter, {@link play} (so the move is not spread over the next frame's steps as motion)
+     * and call this, and no ribbon is drawn across the jump. Does nothing on the other render modes.
+     */
+    clearTrails(): void;
+    /**
+     * Scales how many particles the system emits, from 0.1 to 1 (values outside are clamped), for
+     * lower quality settings or a crowded frame; the renderer's adaptive performance sets it. It
+     * multiplies with {@link emissionMultiplier}. Default 1.
+     */
     setQualityFactor(qualityFactor: number): void;
-    /** Quality factor times {@link emissionMultiplier}: what emission counts are scaled by. */
-    private emissionFactor;
     /**
-     * Appends one particle to the pool, giving it the next row of the store.
-     *
-     * Growing the store replaces its arrays, so every particle already bound to
-     * it has to be re-pointed at the new ones.
-     */
-    /** Points every particle at the store's columns again, after any were replaced. */
-    private rebindParticles;
-    private growParticlePool;
-    private spawn;
-    /** Turns a newborn so that it faces the way its shape sent it; see {@link alignToDirection}. */
-    private alignParticleToDirection;
-    /** Applies the parent particle's inherited properties to a sub emitted newborn; see `EmitSubParticleSystem.inherit`. */
-    private inheritFromParent;
+     * Quality factor times {@link emissionMultiplier}: what emission counts are scaled by.
+     * @internal
+     */
+    emissionFactor(): number;
+    /**
+     * Stops emission and lets the particles alive die out (Unity's `Stop` with
+     * `StopEmitting`). The system fires `emitEnd`, then `finished` when the last particle has
+     * died, and is disposed then if {@link autoDestroy} is set. {@link restart} starts it again.
+     */
     endEmit(): void;
+    /** Whether {@link dispose} has run. A disposed system emits nothing and cannot be restarted. */
+    get isDisposed(): boolean;
+    /**
+     * Removes the system from its renderer, disposes its emitter node (and the nodes under it) and
+     * fires `destroy`. A disposed system cannot be played again. Calling it twice is harmless.
+     */
     dispose(): void;
+    /**
+     * Rolls the system-level generators into the system's memory. Called on construction and on
+     * every restart, which empties the memory: a generator that keeps a slot index into it, such
+     * as `IntervalValue`, would otherwise read past the end and return NaN. A seeded system rolls
+     * them on its own generator, so a restart replays the same rates, counts and delay.
+     */
+    private initSystemGenerators;
+    /**
+     * Clears every particle and starts the system from the beginning: emission time 0, bursts and
+     * the start delay rolled again, behaviors reset, and a seeded system's generator restarted, so
+     * it replays the same effect. Also unpauses it.
+     */
     restart(): void;
     private firstTimeUpdate;
     /**
@@ -4653,13 +5854,18 @@ declare class ParticleSystem implements IParticleSystem {
     /** Runs the steps a system missed while culled, as many as fit before `deadline`. */
     private catchUp;
     /**
-     * Records the bounds the sprite step measured over the live particles.
-     * Trails are measured by their renderer instead, since their ribbons live
-     * outside the store.
+     * Counts the bursts, and the waves of the one in progress, due before `time` seconds into the
+     * cycle as fired, so a jump of the emission clock does not fire them late. The waves are
+     * counted with the arithmetic the emission uses, so none is lost to rounding.
      */
-    private storeBounds;
-    /** Distance of the farthest vertex of the mesh particles' geometry from its origin. */
-    private meshGeometryRadius;
+    private markBurstsBefore;
+    /**
+     * Simulates the end of a cycle before the first frame, on the fixed step directly: no frame
+     * clamp, culling or emitter velocity in the way. The cycle's last {@link prewarmTime} seconds
+     * (the whole cycle when that is 0), and at most {@link maxPrewarmSeconds}, with the bursts
+     * before that counted as fired.
+     */
+    private runPrewarm;
     /**
      * World-space axis-aligned bounds of everything this system draws, padded
      * for particle size, into `min` and `max`. False when the system has no
@@ -4672,7 +5878,8 @@ declare class ParticleSystem implements IParticleSystem {
     /**
      * Where a {@link RenderMode.Beam} system's quads end, see {@link BeamEnd}.
      * Unset (the default), a beam has no length and draws nothing. Not saved
-     * in the effect JSON: it is where this instance is aimed at runtime.
+     * in the effect JSON: it is where this instance is aimed at runtime. Copied by
+     * {@link clone}: a point as a copy, a node as the same node.
      */
     beamEnd?: BeamEnd;
     /**
@@ -4690,115 +5897,88 @@ declare class ParticleSystem implements IParticleSystem {
     private readonly beamEndScratch;
     /** The world position of {@link beamEnd} into `out`; false when it is unset. */
     getBeamEnd(out: Vector3): boolean;
-    /** The largest axis of the emitter's world scale. */
-    private emitterMaxScale;
-    private measureWorldBounds;
     /**
      * Records bounds a renderer measured in world space, for systems whose
      * drawn extent the store does not hold (trail ribbons).
      * @internal
      */
     setWorldBounds(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, padding: number): void;
+    /** Length of one simulation step, in seconds. See {@link simulationResidual}. */
+    get simulationStep(): number;
     /**
      * Time the display is ahead of (positive) or still ahead of the simulation
-     * (negative — the simulation ran a hair early), in seconds. Magnitude never
-     * exceeds one step.
+     * (negative: the simulation ran a hair early), in seconds; 0 while paused.
+     * Its magnitude never exceeds one step.
      *
      * The simulation runs on a fixed 1/60 step so that emission and lifetimes
-     * stay in phase — without it a slow emitter flickers when the frame rate
+     * stay in phase; without it a slow emitter flickers when the frame rate
      * wobbles. But frames do not arrive on that grid: a display running at
-     * anything other than exactly 60Hz leaves some frames with no step at all
-     * (half of them at 120Hz, three in five at 144Hz) and others with two, so
-     * the particles are drawn stuttering even while the frame rate is perfect.
-     *
-     * The steps-per-frame count below is chosen by *rounding* the accumulated
-     * time to the nearest step, not flooring it. Flooring always leaves the
-     * accumulator positive, and when the real frame rate sits very close to
-     * 60Hz (as most displays do) that leftover creeps toward a full step for
-     * many consecutive frames before tipping over into a frame that runs two
-     * steps at once and resets it to near zero — a visible lurch, every particle
-     * in the system at once, with a perfectly steady frame rate the whole time.
-     * Rounding lets the leftover go negative instead, which keeps it centered
-     * near zero and stops it from ever building up toward that reset.
-     *
-     * Renderers close the gap by advancing what they draw along each particle's
-     * velocity by this much. That reproduces the straight-line part of the
-     * motion exactly — it is the same term the next step would integrate — so
+     * anything other than exactly 60 Hz leaves some frames with no step at all
+     * (half of them at 120 Hz, three in five at 144 Hz) and others with two, so
+     * the particles would be drawn stuttering even while the frame rate is
+     * perfect. Renderers close the gap by advancing what they draw along each
+     * particle's velocity by this much. That reproduces the straight-line part
+     * of the motion exactly, the same term the next step would integrate, so
      * the simulation stays fixed-step while the picture moves continuously.
      */
-    /** Length of one simulation step, in seconds. See {@link simulationResidual}. */
-    get simulationStep(): number;
     get simulationResidual(): number;
     /**
-     * Execution plan for this system's behaviors, rebuilt when the list changes.
-     *
-     * Consecutive behaviors that can be compiled into one loop are merged, so
-     * the particles are walked once instead of once per behavior. The plan is
-     * keyed on the behavior instances, not their types: swapping one out has to
-     * change the generated code's indices.
-     */
-    private behaviorSteps;
-    /**
-     * Advances emission, behaviors, motion and culling by one fixed timestep,
-     * on the system's own random generator when it has a {@link seed}.
+     * Advances emission, behaviors, motion and culling by one fixed timestep, on the system's own
+     * random generator when it has a {@link seed}, with the emitter at `emitterMatrix`: the
+     * current one, unless a frame interpolates (see {@link update}).
      */
     private simulateStep;
     private stepOnce;
+    /** Re-points every particle at the store, for {@link snapshotPreviousState}. */
+    private readonly rebindParticles;
+    /** Fires `particleDied` for a particle the step retired. */
+    private readonly fireParticleDied;
     private notifyFinished;
-    /** Waves a burst fires per loop: its `cycle`, and never fewer than one. */
-    private static burstWaveCount;
-    /** Seconds between a burst's waves; a missing or negative interval fires them all at once. */
-    private static burstInterval;
     /**
-     * Fires the burst waves that are due by `emissionState.time`.
-     *
-     * Wave `w` of a burst is due at `burst.time + w * burst.interval`, and the
-     * burst fires `cycle` of them, each rolling `probability` on its own — the
-     * way Unity repeats a burst. Bursts start in time order, as they always
-     * have; their repeats are tracked per burst so a burst that is still
-     * repeating never holds back a later one. Repeats falling past the
-     * system's duration are dropped (a looping system starts them over on its
-     * next loop), matching Unity, which never emits a burst cycle beyond the
-     * end of the duration.
-     */
-    private emitBursts;
-    /** Spawns one wave of `burst`, if its probability roll passes. */
-    private fireBurstWave;
-    /** True while a burst that has started still has a wave due within the duration. */
-    private hasPendingBurstWaves;
-    /**
-     * Spawns `count` particles owed to emission over distance, each where the
-     * emitter crossed its metre mark on the way from `from` to where
-     * `emitterMatrix` has it now, rather than all of them at the end of the
-     * path: a fast emitter then leaves a continuous trail instead of one clump
-     * per step.
-     *
-     * `carried` is how far the emitter had already gone past its last mark
-     * before this step, so the marks keep their spacing across steps. Only the
-     * position is interpolated; the emitter's current rotation and scale are
-     * used for every particle.
+     * Spawns what this step's emission calls for. Called by the simulation step, and by
+     * `EmitSubParticleSystem` on a sub emitter target with the parent particle's state and matrix.
      */
-    private spawnAlongPath;
     emit(delta: number, emissionState: EmissionState, emitterMatrix: Matrix4): void;
+    /**
+     * Writes this system's settings. Its geometry, material and textures go into `metaData` as
+     * entries the result names by uuid; give the same `metaData` to every system of a document so
+     * shared ones are written once. The material entry holds live Babylon objects, so to write a
+     * file use `serializeEffect`, which turns them into plain data. Runtime-only state
+     * (`tint`, `beamEnd`, the playing time) is not written.
+     */
     toJSON(metaData?: BabylonMetaData | string, _options?: SerializationOptions): ParticleSystemJSONParameters;
+    /**
+     * Builds a system from {@link toJSON} output, resolving its geometry, material and texture
+     * uuids through `meta`. A setting the file leaves out takes the constructor's default; an
+     * unknown shape, behavior or curve type warns and takes its default. Sub emitter targets stay
+     * uuids until `QuarksLoader` links them.
+     */
     static fromJSON(json: ParticleSystemJSONParameters, meta: BabylonMetaData, dependencies?: {
         [uuid: string]: Behavior;
     }, scene?: Scene): ParticleSystem;
-    private static nextSerializationId;
-    /** Normals facing +Z, one array per geometry so systems sharing it still batch together. */
-    private static createFallbackNormals;
-    private toRendererSettingsJSON;
-    private ensureGeometryMeta;
-    private ensureMaterialMeta;
-    private static resolveGeometryData;
+    /** Appends a behavior to {@link behaviors}; it runs on existing particles from the next step. */
     addBehavior(behavior: Behavior): void;
+    /**
+     * The settings the renderer batches this system on. Prefer the system's setters, which move it
+     * to a matching batch; after changing a field here directly, set {@link neededToUpdateRender}.
+     */
     getRendererSettings(): VFXBatchSettings;
+    /**
+     * Calls `callback` on each `event`: `'emitEnd'` when emission ends, `'finished'` when the last
+     * particle of an ended system dies, `'particleDied'` per particle (with `event.particle`), and
+     * `'destroy'` on dispose.
+     */
     addEventListener(event: ParticleSystemEventType, callback: (event: ParticleSystemEvent) => void): void;
+    /** Removes every callback registered for `event`. */
     removeAllEventListeners(event: ParticleSystemEventType): void;
+    /** Removes one callback added with {@link addEventListener}. */
     removeEventListener(event: ParticleSystemEventType, callback: (event: ParticleSystemEvent) => void): void;
-    /** True when at least one callback is registered for the event type. */
-    private hasListeners;
-    private fire;
+    /**
+     * A new system with the same settings, behaviors and generators (copied, so the two roll
+     * independently), on a new emitter node with no parent. It shares the texture, material and
+     * geometry. It is not added to a renderer: call `renderer.addSystem` on it, or use
+     * `QuarksUtil.instantiate` to copy a whole effect tree.
+     */
     clone(): ParticleSystem;
 }
 
@@ -4811,10 +5991,21 @@ type QuarksResourceKind = 'effect' | 'geometry' | 'image';
 interface QuarksResourceResolver {
     /** Resolve a relative url to an absolute / blob / data url. Default: {@link QuarksLoader.joinUrl}. */
     resolve?(url: string, kind: QuarksResourceKind, baseUrl: string): string | Promise<string>;
-    /** Load a JSON asset (geometry files). Default: `fetch(resolvedUrl).json()`. */
-    fetchJson?(resolvedUrl: string): Promise<unknown>;
+    /**
+     * Load a JSON asset (effect and geometry files). Default: `fetch(resolvedUrl).json()`.
+     * `options.signal` is passed for an effect document, whose fetch belongs to one load; geometry
+     * fetches are shared between loads and get none.
+     */
+    fetchJson?(resolvedUrl: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
 }
+/** Options for a {@link QuarksLoader}, shared by every load it does. */
 interface QuarksLoaderOptions {
+    /**
+     * Prefix joined to relative geometry and image urls (see {@link QuarksLoader.joinUrl}).
+     * Unset, {@link QuarksLoader.load} uses the effect file's own folder and the other loads `''`.
+     */
     baseUrl?: string;
     /**
      * Reuse one Texture per scene for every effect that references the same image with the same
@@ -4827,9 +6018,32 @@ interface QuarksLoaderOptions {
     shareResources?: boolean;
     /** Custom url / fetch backend (File picker, CDN, IndexedDB). */
     resolver?: QuarksResourceResolver;
+    /**
+     * Makes `load`, `loadFromJSON`, `loadAll` and `loadFromJSONAll` resolve only once every texture
+     * the effect uses has loaded or failed, so it does not draw its first frames without them.
+     * A texture a scene with `useDelayedTextureLoading` would load only once drawn is loaded at
+     * once. `parse` never waits. Default false: they resolve when the nodes are built.
+     */
+    waitForTextures?: boolean;
+    /**
+     * Called for a geometry file or image that fails to load. The effect still loads: a geometry
+     * keeps its link unresolved, and a texture draws nothing. Default: a console warning.
+     */
+    onResourceError?: (kind: QuarksResourceKind, url: string, error: unknown) => void;
+}
+/** Options for one {@link QuarksLoader.load} or {@link QuarksLoader.loadFromJSON}. */
+interface QuarksLoadOptions {
+    /**
+     * Cancels the load, e.g. on a level change. The promise rejects with the signal's reason as
+     * soon as it is aborted, and no node of the effect is left in the scene. The effect document's
+     * own fetch is cancelled; a geometry fetch shared with other loads runs on, and its result is
+     * dropped. A scene disposed during the load rejects it the same way.
+     */
+    signal?: AbortSignal;
 }
 /** One in-memory effect for {@link QuarksLoader.loadFromJSONAll}. */
 interface QuarksJSONLoadEntry {
+    /** The effect document, as {@link serializeEffect} or the editor writes it. Left unchanged. */
     json: unknown;
     /** Overrides loader `baseUrl` for relative texture / geometry links in this effect. */
     baseUrl?: string;
@@ -4839,7 +6053,7 @@ interface QuarksJSONLoadEntry {
  * Batch loads share the per-scene fetch cache and `shareResources`, so N effects that point at
  * the same `assets/geometries/*.json` or texture only pay for that asset once.
  */
-interface QuarksBatchLoadOptions {
+interface QuarksBatchLoadOptions extends QuarksLoadOptions {
     /**
      * Max concurrent effect-document fetches (phase 1). Linked geometry/image resolve still runs
      * across the whole pack in parallel so shared urls coalesce. Default: all at once.
@@ -4856,17 +6070,60 @@ interface QuarksBatchLoadOptions {
      */
     continueOnError?: boolean;
 }
+/**
+ * Thrown for a document the loader cannot read at all, such as one with no `object`. A part it
+ * cannot read (an unknown behavior, shape or curve type, a missing setting) only warns, and that
+ * part takes its default.
+ */
+declare class QuarksFormatError extends Error {
+    constructor(message: string);
+}
+/**
+ * Loads effects saved as JSON into a scene: fetches the document and the geometry and image files
+ * it links, builds the nodes, particle systems, textures and materials, and returns the root.
+ * Add the systems to a {@link BatchedRenderer} with {@link QuarksUtil.addToBatchRenderer} to draw
+ * them, and free the effect with {@link QuarksLoader.disposeEffect}.
+ *
+ * @example
+ * ```ts
+ * const loader = new QuarksLoader(scene, {waitForTextures: true});
+ * const effect = await loader.load('effects/fireball.json');
+ * QuarksUtil.addToBatchRenderer(effect, renderer);
+ * QuarksUtil.play(effect);
+ * ```
+ */
 declare class QuarksLoader {
     private scene;
     private options;
     constructor(scene: Scene, options?: QuarksLoaderOptions);
-    /** Fetches an effect JSON from `url`, resolves linked sources, and parses it. */
-    load(url: string): Promise<TransformNode>;
     /**
-     * Resolves linked geometry / image urls on `json` (via {@link resolveResources}) then parses.
-     * Use when the effect JSON is already in hand (File, CDN payload, editor import).
+     * Fetches an effect JSON from `url`, resolves linked sources, and parses it. Free the effect
+     * with {@link disposeEffect}.
+     */
+    load(url: string, options?: QuarksLoadOptions): Promise<TransformNode>;
+    /**
+     * Resolves linked geometry / image urls (via {@link resolveResources}) then parses. Use when
+     * the effect JSON is already in hand (File, CDN payload, editor import). `json` itself is
+     * left as it was, so the same document can be loaded again, into another scene or with
+     * another base url.
+     */
+    loadFromJSON(json: any, baseUrl?: string, options?: QuarksLoadOptions): Promise<TransformNode>;
+    /**
+     * Disposes an effect a loader built: its nodes and systems, the materials made for it, and
+     * each texture it uses once no other loaded effect uses it (textures are shared per scene,
+     * see {@link QuarksLoaderOptions.shareResources}). Copies made with
+     * `QuarksUtil.instantiate` hold the textures too, so disposing the source effect leaves them
+     * drawing. The same happens when the root is disposed any other way (`root.dispose()`, its
+     * parent's dispose, the scene's). The materials and textures are freed even when other code
+     * was handed them; give that code its own. For a root the loader did not build, this is
+     * `root.dispose()`.
+     */
+    static disposeEffect(root: TransformNode): void;
+    /**
+     * Waits for the effect's textures when the loader is asked to, and frees the effect when the
+     * load is stopped meanwhile.
      */
-    loadFromJSON(json: any, baseUrl?: string): Promise<TransformNode>;
+    private finishLoad;
     /**
      * Loads many effects in parallel for battle / level preload. Phase 1 fetches every effect
      * JSON (optionally concurrency-limited); phase 2 resolves all linked geometries/images across
@@ -4897,18 +6154,23 @@ declare class QuarksLoader {
     }): Promise<(TransformNode | null)[]>;
     /**
      * Inlines external geometry files and rewrites relative image urls through the loader's
-     * {@link QuarksResourceResolver}. Idempotent for already-inlined geometries. Failures warn
-     * and leave the entry as is.
+     * {@link QuarksResourceResolver}, in place on `json`. Each document is resolved once:
+     * geometries already inlined and image urls this method already rewrote are left alone, so
+     * loading the same document again does not join its base url twice. Failures warn and leave
+     * the entry as is.
      */
     resolveResources(json: any, baseUrl?: string): Promise<void>;
     /**
      * Same as instance {@link resolveResources}, but usable without constructing a loader (e.g.
      * editor import that only prepares JSON). Pass `scene` to share the per-scene fetch cache.
+     * Like it, resolves each document once. A geometry file that fails to load goes to
+     * `onResourceError` (default: a console warning) and keeps its link.
      */
     static resolveLinkedResources(json: any, options?: {
         baseUrl?: string;
         resolver?: QuarksResourceResolver;
         scene?: Scene;
+        onResourceError?: QuarksLoaderOptions['onResourceError'];
     }): Promise<void>;
     /**
      * Inlines geometries that an export wrote to their own file (`{uuid, type: 'QuarksGeometry',
@@ -4917,7 +6179,15 @@ declare class QuarksLoader {
      * `loadGeometry` and no `QuarksLoader` instance.
      */
     static resolveExternalGeometries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void>;
+    /**
+     * Builds the node tree of an effect document whose linked files are already inline (see
+     * {@link loadFromJSON}). `baseUrl` is joined to relative image urls. Parts the loader cannot
+     * read warn and take their defaults; a document with no `object` throws
+     * {@link QuarksFormatError}. Free the effect with {@link disposeEffect}.
+     */
     parse(json: any, baseUrl?: string): TransformNode;
+    /** {@link parse}, and the textures the effect uses. */
+    private parseDocument;
     private parseGeometries;
     /** The scene's copy of an identical geometry when resources are shared, else `geometry` itself. */
     private share;
@@ -4941,12 +6211,15 @@ declare class QuarksLoader {
      * scene fetch cache), then parse. Each index settles exactly once for `onProgress`.
      */
     private loadDocuments;
+    private loadResolvedDocuments;
     /** Runs `fn` over `items` with at most `concurrency` in flight (or all if unset/≤0). */
     private static mapPool;
     private static resolveWith;
     /** One in-flight fetch per scene + resolved url when `scene` is set; otherwise uncached. */
     private static fetchJsonWith;
     private static inlineGeometryEntries;
+    private static warnResourceError;
+    private reportResourceError;
     private parseImages;
     /**
      * Flags an image entry that is plainly not an image, which otherwise only
@@ -4970,57 +6243,278 @@ declare class QuarksLoader {
     private linkReferences;
 }
 
+/**
+ * A clip a {@link QuarksPrefab} timeline can drive, such as a Babylon `AnimationGroup`. Every
+ * member is optional; the prefab calls only what is there.
+ */
 interface QuarksTimelineClip {
+    /** Names the clip in a saved prefab, so it can be found again on load. */
     uuid?: string;
+    /** Length in seconds, used when the track gives none. */
     duration?: number;
+    /** Called when the timeline enters the track. */
     play?: () => void;
+    /** Called when the prefab pauses. */
     pause?: () => void;
+    /** Called when the timeline leaves the track or the prefab stops. */
     stop?: () => void;
+    /** Called while scrubbing with {@link QuarksPrefab.setTime}, with the time into the track in seconds. */
     setTime?: (time: number) => void;
 }
+/** One track on a {@link QuarksPrefab} timeline. */
 interface AnimationData extends IAnimationData {
+    /**
+     * `'ps'` plays a particle system, `'three'` plays a {@link QuarksTimelineClip}. The names are
+     * the effect format's, shared with three.quarks, where a `'three'` track plays a three.js
+     * `AnimationClip`; here the clip is whatever the host registered on the target node.
+     */
     type: 'three' | 'ps';
+    /** The node the track drives: a {@link ParticleEmitter} for `'ps'`, any node for `'three'`. */
     target: TransformNode;
+    /** Restart when the track ends instead of letting it finish. */
     loop: boolean;
+    /** The clip a `'three'` track plays. */
     clip?: QuarksTimelineClip;
+    /** The id of the clip on `target`, written to and read from JSON. */
     clipUUID?: string;
 }
+/**
+ * A node with a timeline that starts and stops the particle systems and clips under it, like a
+ * Unity Timeline or a Niagara System's emitter spawn schedule. Each track starts at `startTime`
+ * and lasts `duration` seconds: a particle system restarts when its track begins and stops
+ * emitting when it ends, a clip plays and stops.
+ *
+ * Call {@link QuarksPrefab.update} every frame (or {@link QuarksPrefab.setTime} to scrub).
+ */
 declare class QuarksPrefab extends TransformNode implements IPrefab {
+    /** Always `'QuarksPrefab'`; written to JSON. */
     type: string;
+    /** The tracks, in the order they were added. */
     animationData: Array<AnimationData>;
+    /** Whether {@link QuarksPrefab.update} advances the timeline. */
     isPlaying: boolean;
+    /** Time on the timeline in seconds; just below 0 before the first update, so a track at 0 starts. */
     currentTime: number;
+    /** Playback speed; 1 is real time. */
     timeScale: number;
+    /** End of the last track in seconds; the prefab stops when it passes it. */
     duration: number;
     private _lastUpdateTimeMs;
     private _batchedRenderer?;
     private _tempAnimationJSON;
     constructor(name?: string, scene?: Scene);
+    /** The renderer that a particle system is added to again when its track starts. */
     registerBatchedRenderer(renderer: BatchedRenderer): void;
+    /**
+     * Adds a track that plays `emitter`'s system, and pauses the prefab.
+     * @param startTime - Seconds into the timeline.
+     * @param duration - Seconds; 0 or less uses the system's own duration.
+     * @param loop - Restart the system when the track ends.
+     */
     addParticleSystemAnimation(emitter: ParticleEmitter, startTime?: number, duration?: number, loop?: boolean): AnimationData;
+    /**
+     * Adds a track that plays `clip` on `target`.
+     * @param startTime - Seconds into the timeline.
+     * @param duration - Seconds; 0 or less uses the clip's duration.
+     * @param loop - Play the clip again when the track ends.
+     * @param clipUUID - Saved in JSON to find the clip on load; defaults to `clip.uuid`.
+     */
     addThreeAnimation(target: TransformNode, clip?: QuarksTimelineClip, startTime?: number, duration?: number, loop?: boolean, clipUUID?: string): AnimationData;
+    /** Removes the track at `index` in {@link QuarksPrefab.animationData}. */
     removeAnimation(index: number): void;
+    /**
+     * Starts or resumes the timeline from {@link QuarksPrefab.currentTime}, resuming the systems and
+     * clips of the tracks it is inside, which {@link QuarksPrefab.pause} paused.
+     */
     play(): void;
+    /** Pauses the timeline and every system and clip on it. */
     pause(): void;
+    /** Pauses, rewinds to the start, and stops every system and clip on it. */
     stop(): void;
+    /**
+     * Advances the timeline, starting and ending tracks it crosses. Stops past {@link QuarksPrefab.duration}.
+     * @param forceDelta - Seconds to advance; by default the wall-clock time since the last update.
+     */
     update(forceDelta?: number): void;
+    /** Jumps to `time` seconds, starting and ending tracks it crosses and scrubbing clips to it. */
     setTime(time: number): void;
+    /** Same as {@link QuarksPrefab.duration}. */
     getDuration(): number;
+    /**
+     * Links the tracks read by {@link QuarksPrefab.fromJSON} to the nodes under `root` they name.
+     * {@link QuarksLoader} calls it once the whole effect is built; tracks whose node is missing are dropped.
+     */
     resolveReferences(root: TransformNode): void;
+    /** Writes the prefab's name, time scale (when not 1) and tracks. */
     toJSON(): any;
+    /** Reads a prefab written by {@link QuarksPrefab.toJSON}; call {@link QuarksPrefab.resolveReferences} afterwards. */
     static fromJSON(json: any, scene?: Scene): QuarksPrefab;
     private resolveTimelineClip;
     private updateDuration;
 }
 
+/**
+ * The version of the effect file format this library writes, in `metadata.quarksFormat`. It goes
+ * up when a release writes something an older loader would read wrongly. `QuarksLoader`
+ * reads every earlier version, and files written before the field existed, and warns about a
+ * file from a newer version.
+ */
+declare const QUARKS_FORMAT_VERSION = 1;
+/** An image a texture reads: a url, a root-relative path, or a `data:` URI. */
+interface QuarksImageJSON {
+    /** Unique within the file; other entries refer to it by this. */
+    uuid: string;
+    /** Relative to the file's base url, absolute, or a `data:` url. */
+    url: string;
+}
+/**
+ * A texture and its sampler state. Every field after `image` is written only when it differs from
+ * Babylon's default for a `Texture`. `wrap` uses the three.js codes the format inherited: 1000
+ * repeat, 1001 clamp, 1002 mirror.
+ */
+interface QuarksTextureJSON {
+    /** Unique within the file; other entries refer to it by this. */
+    uuid: string;
+    /** The {@link QuarksImageJSON} uuid; absent when the texture had no url a file can point at. */
+    image?: string;
+    /** Default true. */
+    invertY?: boolean;
+    /** Default false. */
+    noMipmap?: boolean;
+    /** A Babylon sampling mode constant. Default trilinear. */
+    samplingMode?: number;
+    /** `[u, v]`. Default repeat on both. */
+    wrap?: [number, number];
+    /** `[uScale, vScale]`. Default `[1, 1]`. */
+    repeat?: [number, number];
+    /** `[uOffset, vOffset]`. Default `[0, 0]`. */
+    offset?: [number, number];
+    /** `wAng`, in radians. Default 0. */
+    rotation?: number;
+}
+/** Mesh data, inline. */
+interface QuarksGeometryJSON {
+    /** Unique within the file; other entries refer to it by this. */
+    uuid: string;
+    /** Always `'QuarksGeometry'`. */
+    type: 'QuarksGeometry';
+    /** `x, y, z` per vertex. */
+    positions: number[];
+    /** Three per triangle. */
+    indices: number[];
+    /** First UV set, `u, v` per vertex. */
+    uvs?: number[];
+    /** Second UV set, `u, v` per vertex. */
+    uvs2?: number[];
+    /** `x, y, z` per vertex. */
+    normals?: number[];
+}
+/** A node of an effect: a group, an emitter, a mesh or a prefab, with its children. */
+interface QuarksNodeJSON {
+    /** Unique within the file; other entries refer to it by this. */
+    uuid: string;
+    /** What the node is; a type the loader does not know loads as an empty node. */
+    type: 'Group' | 'ParticleEmitter' | 'Mesh' | 'QuarksPrefab' | string;
+    /** The node's name. */
+    name?: string;
+    /** Local transform, column-major, as Babylon's `Matrix.asArray()`. */
+    matrix: number[];
+    /** Written only when the node is disabled; loads it disabled, with everything under it. */
+    visible?: false;
+    /** `Mesh`: written only when the mesh is not drawn (`isVisible`), which leaves its children drawn. */
+    isVisible?: false;
+    /** Child nodes, in order. */
+    children?: QuarksNodeJSON[];
+    /** `ParticleEmitter`: the system. */
+    ps?: ParticleSystemJSONParameters;
+    /** `Mesh`: the {@link QuarksGeometryJSON} uuid. */
+    geometry?: string;
+    /** `Mesh`: the material uuid. */
+    material?: string;
+    [key: string]: unknown;
+}
+/** A whole effect, as {@link serializeEffect} writes it and `QuarksLoader` reads it. */
+interface QuarksEffectJSON {
+    /** What wrote the file, and which format version it follows. */
+    metadata: {
+        /** The three.js object format version the envelope follows. */
+        version: number;
+        /** Always `'Object3D'`. */
+        type: 'Object3D';
+        /** The tool that wrote the file, from {@link SerializeEffectOptions.generator}. */
+        generator: string;
+        /** See {@link QUARKS_FORMAT_VERSION}. */
+        quarksFormat: number;
+    };
+    /** Meshes the nodes and particle systems use. */
+    geometries: QuarksGeometryJSON[];
+    /** Materials the particle systems and `Mesh` nodes use, referred to by uuid. */
+    materials: Array<Record<string, unknown>>;
+    /** Textures the particle systems use. */
+    textures: QuarksTextureJSON[];
+    /** Image files the textures load. */
+    images: QuarksImageJSON[];
+    /** The effect's root node. */
+    object: QuarksNodeJSON;
+}
+/** Options for {@link serializeEffect}. */
+interface SerializeEffectOptions {
+    /** Written to `metadata.generator`. Default `'babylon.quarks'`. */
+    generator?: string;
+    /**
+     * Leaves a node and everything under it out of the file when it returns false, e.g. helpers an
+     * editor parents under an effect.
+     */
+    filter?: (node: TransformNode) => boolean;
+    /**
+     * Called for each part of the effect the file cannot hold as it is, such as a texture with no
+     * url a file can point at. Default: `console.warn`.
+     */
+    onWarning?: (message: string) => void;
+    /** Several roots are written as children of one group; its name. Default `'effect'`. */
+    name?: string;
+    /**
+     * The url written for a texture's image. Default: the url the texture's image had in the file
+     * it was loaded from (see {@link textureSourceUrl}), so a file saved next to its source loads
+     * the same images; for a texture made in code, its `url`. Return a path relative to where the
+     * file will be saved when that differs from the source, or give a texture made in code a url or
+     * a `data:` URI. Return `null` to write the texture without an image.
+     */
+    imageUrl?: (texture: Texture) => string | null | undefined;
+}
+/**
+ * Writes an effect, the node tree under `root` with its emitters, meshes and prefabs, as one JSON
+ * document `QuarksLoader` loads back: the counterpart of `loader.load()`. The result holds
+ * only plain data, so `JSON.stringify` takes it as is. Nodes keep their ids
+ * ({@link quarksNodeId}), so sub emitters, mesh surface shapes and prefab animations still find
+ * their targets, and a loaded effect saved again writes the same file.
+ *
+ * Textures are written by url, with their sampler state. One with no url a file can point at is
+ * written without its image and reported through `onWarning`. Several roots are written as
+ * children of one group.
+ */
+declare function serializeEffect(root: TransformNode | TransformNode[], options?: SerializeEffectOptions): QuarksEffectJSON;
+
+/**
+ * Helpers that act on a whole effect: every particle system under a root node, as a loaded effect
+ * or a hand-built tree has them.
+ */
 declare class QuarksUtil {
+    /** Calls `callback` on `root` and every node under it that is a {@link ParticleEmitter}. */
     static runOnAllParticleEmitters(root: Node, callback: (emitter: ParticleEmitter) => void): void;
+    /** Adds every system under `root` to `batchRenderer`. */
     static addToBatchRenderer(root: Node, batchRenderer: BatchedRenderer): void;
+    /** Resumes every system under `root`, see {@link ParticleSystem.play}. */
     static play(root: Node): void;
+    /** Clears, rewinds and pauses every system under `root`, see {@link ParticleSystem.stop}. */
     static stop(root: Node): void;
+    /** Pauses every system under `root`, see {@link ParticleSystem.pause}. */
     static pause(root: Node): void;
+    /** Restarts every system under `root` from the beginning, see {@link ParticleSystem.restart}. */
     static restart(root: Node): void;
+    /** Sets {@link ParticleSystem.autoDestroy} on every system under `root`. */
     static setAutoDestroy(root: Node, autoDestroy: boolean): void;
+    /** Ends emission on every system under `root` and lets the particles die out, see {@link ParticleSystem.endEmit}. */
     static endEmit(root: Node): void;
     /**
      * True when every system under `root` is finished: non-looping ones that
@@ -5055,258 +6549,135 @@ declare class QuarksUtil {
     private static traverseNode;
 }
 
-declare function registerShaderChunks(): void;
-declare function getShaderChunk(chunkName: string): string | undefined;
-declare function getRegisteredShaderChunks(): Readonly<Record<string, string>>;
-
-declare const _default$7: string;
-
-declare const _default$6: "\n// Per-vertex attributes\nattribute vec3 position;\nattribute vec2 uv;\n\n// Per-instance attributes\nattribute vec3 offset;\nattribute vec4 color;\nattribute vec3 size;\nattribute vec4 rotation;\nattribute float uvTile;\n\n// Uniforms\nuniform mat4 worldViewProjection;\n\n#ifdef UV_TILE\nuniform float tileCountX;\nuniform float tileCountY;\n#endif\n\n// Varyings\nvarying vec2 vUV;\nvarying vec4 vColor;\n\nvec3 applyQuaternion(vec3 v, vec4 q) {\n    vec3 qVec = q.xyz;\n    float qW = q.w;\n    vec3 t = 2.0 * cross(qVec, v);\n    return v + qW * t + cross(qVec, t);\n}\n\nvoid main() {\n    vec3 rotatedPosition = applyQuaternion(position * size, rotation);\n    vec3 worldPos = rotatedPosition + offset;\n\n    gl_Position = worldViewProjection * vec4(worldPos, 1.0);\n\n    #ifdef UV_TILE\n        vec2 tc = vec2(tileCountX, tileCountY);\n        float baseTile = floor(uvTile);\n        float tileU = mod(baseTile, tc.x) / tc.x;\n        float tileV = 1.0 - floor(baseTile / tc.x) / tc.y - 1.0 / tc.y;\n        vUV = uv / tc + vec2(tileU, tileV);\n    #else\n        vUV = uv;\n    #endif\n\n    vColor = color;\n}\n";
-
-declare const _default$5: string;
-
-declare const _default$4: string;
-
-declare const _default$3: string;
-
-declare const _default$2: string;
-
-declare const _default$1: string;
-
-declare const _default: string;
+/**
+ * Picking the shader language a batch compiles in, and putting the source where
+ * the engine will look for it.
+ *
+ * WebGPU speaks WGSL. Handing it GLSL is not an error — Babylon transpiles —
+ * but the transpilers are two WASM modules it downloads from cdn.babylonjs.com
+ * the first time a GLSL shader is compiled. That is a third-party request on
+ * first draw, a hard failure under a Content-Security-Policy that does not list
+ * the CDN or with no network at all, and a GLSL to SPIR-V to WGSL round trip
+ * before the first particle appears. Shipping the WGSL means none of that
+ * happens.
+ *
+ * The two languages live in separate stores keyed by the same name, so a scene
+ * that somehow ran both would not collide.
+ */
+interface ShaderSources {
+    /** GLSL source, used on every WebGL engine. */
+    glsl: string;
+    /** WGSL source, used on WebGPU. */
+    wgsl: string;
+}
 
-declare class SpriteBatch extends VFXBatch {
-    private static whiteTextureByScene;
-    /** 1×1 white map so mesh batches always have a sampler2D (iOS WebKit). */
-    private static whiteTexture;
-    private offsetBuffer;
-    private rotationBuffer;
-    private sizeBuffer;
-    private colorBuffer;
-    private uvTileBuffer;
-    private velocityBuffer?;
-    /** Concretely typed handle on the batch material, see syncStretchedSpeedFactor. */
-    private shaderMaterial;
-    /** The `'fixed'` mesh light, as shader uniforms; see applyMeshLighting. */
-    private readonly fixedLightDirection;
-    private readonly fixedLightColor;
-    private readonly fixedAmbientColor;
-    private offsetVB;
-    private rotationVB;
-    private sizeVB;
-    private colorVB;
-    private uvTileVB;
-    private velocityVB?;
-    constructor(settings: VFXBatchSettings, scene: Scene);
-    setupBuffers(): void;
-    /**
-     * True when a mesh batch reads UV channel 1 and has a second UV set to
-     * read it from, two values per vertex. A set of any other length is left
-     * out with a warning, and channel 1 then reads the first set.
-     */
-    private warnedUV2;
-    private meshUV2;
-    /** Releases the instance vertex buffers so a resize does not leak GPU memory. */
-    private disposeExpandableBuffers;
-    private buildExpandableBuffers;
-    expandBuffers(target: number): void;
-    /** The screen-size limits as a uniform value, or null when the batch has none that apply. */
-    private sizeLimits;
-    private sortScratch?;
-    /** One spare array per attribute buffer, gathered into and swapped in; indexed by buffer slot. */
-    private readonly gatherScratch;
-    /**
-     * Reorders the `count` filled instances by the batch's sort mode, so that
-     * the later (covering) draws are the nearer or the chosen-age particles.
-     * The order is computed once as a permutation and every attribute buffer
-     * is gathered through it into a spare array that then takes its place.
-     */
-    private sortInstances;
-    /** Gathers `source` in `order` into the spare array of `slot` and returns it; the source becomes the spare. */
-    private gatherInto;
-    rebuildMaterial(): void;
-    applyMeshLighting(lighting: MeshLightingSettings): void;
-    private storeFixedLighting;
-    private writeFixedLighting;
-    /**
-     * Reads the scene's key light for `'scene'` mesh lighting: the first
-     * enabled directional or hemispheric light, its diffuse colour times its
-     * intensity, plus the scene's ambient colour. A hemispheric light lights
-     * from its `direction` (which points at the sky) and adds its ground colour
-     * to the ambient, which approximates its sky-to-ground blend with the one
-     * directional term the shader has. False when there is no such light.
-     */
-    static readSceneLight(scene: Scene, direction: Vector3$1, color: Vector3$1, ambient: Vector3$1): boolean;
-    private vector_;
-    private vector2_;
-    private vector3_;
-    private quaternion_;
-    private quaternion2_;
-    private quaternion3_;
-    private quaternion4_;
-    private quaternion5_;
-    private rotationMat_;
-    private rotationMat2_;
-    private lastStretchedSpeedFactor;
-    /** Slot 0 holds the zero-alpha instance since the batch last went empty. */
-    private clearedInstanceUploaded;
-    update(): void;
-    /**
-     * Pushes the stretched-billboard speed factor to the shader when it changed.
-     *
-     * Deliberately kept out of `update`: touching the loosely typed
-     * `mesh.material` from inside that function gives V8 a generic property
-     * access it has no feedback for, which knocks the whole particle loop out of
-     * optimised code on every frame.
-     */
-    private syncStretchedSpeedFactor;
-    /** Stretched billboards and beams: drawn along a per-instance vector, by the stretched shader. */
-    private static drawsAlongVelocity;
-    private readonly beamEnd_;
-    /**
-     * Writes, for the `count` instances from `first`, the world vector from
-     * each one's drawn position to the system's beam end into the velocity
-     * buffer, which the stretched shader under `BEAM` lays the quad along. A
-     * beam without an end gets no length.
-     */
-    private writeBeams;
-    /** The quads that take a pivot and flip: every billboard kind, stretched included, but not meshes or beams. */
-    private static takesPivotAndFlip;
-    /** Multiplies `count` RGBA colours starting at `base` by a system's {@link ParticleSystem.tint}. */
-    private static applyTint;
-    /**
-     * Negates the size of each flipped particle along the axes it flips on,
-     * starting at `base` in `sizes`. The billboard shader scales the quad by
-     * the size, so a negative one mirrors it — and with it the texture, the
-     * quad being centred — the way Unity's renderer Flip mirrors U and V. The
-     * stretched shader reads the sign and mirrors the texture coordinates.
-     */
-    private static applyFlip;
-    /** The same for a system without a store, read off the particles. */
-    private static applyFlipFromParticles;
-    /**
-     * Writes the mesh rotations for rows `[0, count)` of a store: each
-     * particle's quaternion, carried on by `fraction` of its last turn (see
-     * {@link partialTurn}) and, for a local-space system, turned by the
-     * emitter's rotation `parent`.
-     */
-    private static writeQuaternions;
-    /**
-     * Writes the stretched billboards' velocity attribute for rows `[0, count)`
-     * of a store: the velocity carried on by `fraction` of the last step (see
-     * {@link extrapolate}), turned into world space by `rotation` when the
-     * system simulates locally, scaled by the speed factor, with the length
-     * factor in `w`.
-     */
-    private static writeVelocities;
-    /**
-     * The fraction `f` of a turn, as a normalised lerp from no rotation toward
-     * `step`, written into `out`.
-     *
-     * A true slerp would be exact, but `step` is one simulation step of turning
-     * and `f` is below 1, so the arc being split is small enough that the lerp
-     * is within a rounding error of it and costs a fraction as much.
-     */
-    private static partialTurn;
-    /**
-     * Continues a three-component column by `fraction` of the step it just took,
-     * never below zero.
-     *
-     * Size fades to nothing at the end of a life, so the last step before death
-     * can point past zero; a negative size turns a sprite inside out.
-     */
-    private static continueVector3;
-    /** The same for colour, whose alpha runs out at the end of a life too. */
-    private static continueColor;
+/**
+ * The part of a batch's settings that decides its shader: the render mode, which textures and
+ * effects are compiled in, and the blend state the fog and the fade read. Everything else a
+ * batch holds (geometry, draw order, the effects' parameters) is a buffer or a uniform value.
+ */
+type ShaderSettings = Pick<StoredBatchSettings, 'renderMode' | 'texture' | 'reflectionAtlas' | 'uTileCount' | 'vTileCount' | 'blendTiles' | 'softParticles' | 'materialAlphaTest' | 'materialTransparent' | 'materialBlendMode' | 'applyFog' | 'pivot' | 'minParticleSize' | 'maxParticleSize' | 'lighting' | 'rim' | 'mapUV' | 'uvDistortion' | 'gradientMap' | 'erosion'>;
+/** What the material needs to know about the depth texture soft particles read. */
+interface ShaderDepth {
+    /** Whether the depth is packed into four 8-bit channels, as a `DepthRenderer` of type `UNSIGNED_BYTE` writes it. */
+    packed: boolean;
+}
+/**
+ * What a batch knows at compile time that its settings do not say: whether the textures it
+ * depends on are there to be sampled.
+ */
+interface ShaderContext {
     /**
-     * Writes rows `[0, count)` of the store's positions into `target` at `base`,
-     * each carried on by `fraction` of the step it just took.
-     *
-     * Continuing the measured last step covers every way a particle can move —
-     * velocity integration, an orbit, noise, a plugin's own behavior — because
-     * it reads what happened rather than predicting from one term of it. Over
-     * less than a step it is a straight line through a path that may curve,
-     * which for a sixtieth of a second is well under a pixel.
-     *
-     * A particle born during the step has the same position on both sides and
-     * so does not move at all, which is what puts it at the emitter rather than
-     * a step's travel away from it.
+     * The depth texture soft particles read, when one is attached to the renderer. Soft particles
+     * compile only with a depth texture.
      */
-    private static extrapolate;
-    /** Pushes a zero-alpha instance so stale instancing data cannot linger on screen. */
-    private uploadClearedInstance;
-    dispose(): void;
+    depth: ShaderDepth | null;
+    /** Whether the mesh batch's reflection atlas has finished loading; it is sampled only then. */
+    envAtlasReady: boolean;
+    /** Whether the mesh batch has a second UV set to read for {@link UVChannel} 1. */
+    meshUV2: boolean;
 }
+/**
+ * One compiled shader of the library: the sources in both languages and the defines, attributes,
+ * uniforms and samplers the material is built with. Built by {@link shaderProgram} from a
+ * batch's settings, so a batch and a shader validator describe the same material.
+ */
+interface ShaderProgram {
+    /** The name the sources are registered under in Babylon's shader store, one per render mode. */
+    name: string;
+    /** The vertex shader in both languages. */
+    vertex: ShaderSources;
+    /** The fragment shader in both languages. */
+    fragment: ShaderSources;
+    /** The preprocessor defines, without the `#define`. */
+    defines: string[];
+    /** The vertex attributes the material binds. */
+    attributes: string[];
+    /** The uniforms the material declares. */
+    uniforms: string[];
+    /** The texture samplers the material declares. */
+    samplers: string[];
+}
+/** The shader program a batch with `settings` compiles, given what it knows about its textures. */
+declare function shaderProgram(settings: ShaderSettings, context: ShaderContext): ShaderProgram;
 
-declare class TrailBatch extends VFXBatch {
-    private positionBuffer;
-    private previousBuffer;
-    private nextBuffer;
-    private uvBuffer;
-    /** UV channel 1: along the trail and across it, without the sheet's cell; only when a texture reads it. */
-    private uv1Buffer;
-    private sideBuffer;
-    private widthBuffer;
-    private colorBuffer;
-    private indexBuffer;
-    /** True while the batch is parked on the degenerate draw, see uploadGeometry. */
-    private drawsNothing;
-    private previousVB;
-    private nextVB;
-    private sideVB;
-    private widthVB;
-    constructor(settings: VFXBatchSettings, scene: Scene);
-    setupBuffers(): void;
-    private buildGeometryBuffers;
-    expandBuffers(target: number): void;
-    rebuildMaterial(): void;
-    private vector_;
-    private vector2_;
-    private vector3_;
-    private quaternion_;
-    /**
-     * Brings the emitter's world matrix up to date when its transform changed.
-     *
-     * Babylon only recomputes a world matrix once per render id, so a frame that
-     * moves the emitter after that (or a step driven without rendering) would
-     * draw the ribbon against the old one. Recomputing unconditionally every
-     * frame costs a matrix compose per system; checking the transform cache
-     * first makes a still emitter free.
-     */
-    /**
-     * Writes a swept ribbon's vertex pair at `pi`: the sample at (x, y, z)
-     * pushed `half` widths along its side (sx, sy, sz) one way for the first
-     * vertex and the other way for the second.
-     */
-    private writeSweptPair;
-    private static ensureWorldMatrix;
-    update(): void;
-    /**
-     * Records a system's world bounds from the ribbon vertices just written for
-     * it, padded by the widest ribbon. The store only holds each trail's head,
-     * so this is where a trail's extent is known.
-     */
-    private measureSystemBounds;
-    /**
-     * Uploads the vertex data written by `update` and resizes the sub mesh.
-     *
-     * Split out of `update` on purpose: the Babylon mesh/sub-mesh plumbing here
-     * runs a handful of times per frame, and folding it into the per-vertex loop
-     * costs that loop its optimised code.
-     */
-    private uploadGeometry;
-    /**
-     * Points every sub mesh at the mesh's own bounds.
-     *
-     * Updating indices rebuilds the sub meshes, and a fresh one computes its
-     * bounds from the vertex data — which this batch keeps deliberately stale
-     * beyond the range it draws. Transparent sorting reads those bounds every
-     * frame, so they have to be replaced again after every index update, not
-     * only when the geometry is built.
-     */
-    private adoptMeshBounds;
-    dispose(): void;
+/**
+ * One shader the library can compile: a {@link ShaderProgram} with the settings that produce it,
+ * named for the renderer's benefit. See {@link shaderVariants}.
+ */
+interface ShaderVariant {
+    /** The render mode and the features compiled in, for a report. */
+    name: string;
+    /** The program a batch with these settings builds. */
+    program: ShaderProgram;
 }
+/**
+ * Every shader program the library can compile, one per distinct set of defines: every render
+ * mode with every combination of sheet, map, soft particles, alpha test and fog, and the texture
+ * effects alone and together on each shader family. What a shader validator compiles, and what
+ * an application can warm the shader cache with before its first frame (Unity's
+ * ShaderVariantCollection). Built by {@link shaderProgram}, so a variant here is a material a
+ * batch would build.
+ */
+declare function shaderVariants(): ShaderVariant[];
+
+/**
+ * The url a texture's image had in the effect file it was loaded from, relative to that file.
+ * `serializeEffect` writes it by default, so a file saved next to the one it was loaded from loads
+ * the same images.
+ *
+ * `undefined` when there is no such url: a texture made in code or loaded another way; a texture
+ * whose image the loader's resolver inlined (`data:` or `blob:`), which holds the image itself; and
+ * a texture whose `url` was changed since it was loaded (`updateURL`, or a `data:` URI assigned
+ * before saving), since the file's path no longer names what it shows.
+ *
+ * A texture shared between effects (see `QuarksLoaderOptions.shareResources`) keeps the url of the
+ * first effect that loaded it; effects in different folders that join to the same image share it.
+ */
+declare function textureSourceUrl(texture: Texture): string | undefined;
+
+/**
+ * The normalised values of a trail's optional settings (`TrailSettings`), each read with its
+ * default for a value that is unset or out of range, so the batch, the simulation, JSON and
+ * clones agree on what a setting means.
+ */
+/** Most segments one recorded segment of a trail is drawn as, see `TrailSettings.tessellation`. */
+declare const MAX_TRAIL_TESSELLATION = 16;
+/** A trail's tessellation, a whole number from 0 (the default: none) to {@link MAX_TRAIL_TESSELLATION}. */
+declare function trailTessellation(settings: TrailSettings | undefined): number;
+/** A trail's curve tension, from 0 (the default: Catmull-Rom) to 1 (straight segments). */
+declare function trailCurveTension(settings: TrailSettings | undefined): number;
+/** A trail's texture mode, `'stretch'` (the default) unless set to one of the others. */
+declare function trailTextureMode(settings: TrailSettings | undefined): TrailTextureMode;
+/** A trail's texture scale: a finite number above 0, else the default 1. */
+declare function trailTextureScale(settings: TrailSettings | undefined): number;
+/** A trail's minimum distance between samples: a finite number of at least 0, else the default 0. */
+declare function trailMinVertexDistance(settings: TrailSettings | undefined): number;
+/**
+ * How long a trail keeps a sample, in seconds: a finite number above 0, else `Infinity` (the
+ * default, as 0 is: until the history is full).
+ */
+declare function trailLifetime(settings: TrailSettings | undefined): number;
 
-export { ApplyCollision, ApplyForce, ApplySequences, AxisAngleGenerator, BatchedParticleRenderer, BatchedRenderer, BehaviorFromJSON, BehaviorTypes, Bezier, BoxEmitFrom, BoxEmitter, ChangeEmitDirection, CircleEmitter, ColorBySpeed, ColorGeneratorFromJSON, ColorOverLife, ColorRange, ConeEmitter, ConstantColor, ConstantValue, DEG2RAD, DonutEmitter, EdgeEmitter, EffectPool, EmitSubParticleSystem, EmitterFromJSON, EmitterMode, EmitterShapes, Euler, EulerGenerator, ForceOverLife, FrameOverLife, GRADIENT_MAP_WEIGHTS, GeneratorFromJSON, Gradient, GravityForce, GridEmitter, HemisphereEmitter, InheritVelocity, IntervalValue, LimitSpeedOverLife, MathUtils, Matrix3, Matrix4, MeshSurfaceEmitter, MeshSurfaceEmitterPlugin, NodeParticle, Noise, OrbitOverLife, ParticleEmitter, ParticleMeshPhysicsMaterial, ParticleMeshStandardMaterial, ParticleStore, ParticleSystem, PiecewiseBezier, PiecewiseFunction, Plugins, PointEmitter, QuarksLoader, QuarksPrefab, QuarksUtil, Quaternion, QuaternionView, RAD2DEG, RandomColor, RandomColorBetweenGradient, RandomQuatGenerator, RecordState, RectangleEmitter, RenderMode, Rotation3DOverLife, RotationBySpeed, RotationGeneratorFromJSON, RotationOverLife, SequencerFromJSON, ShapeTransform, SizeBySpeed, SizeOverLife, SpeedOverLife, SphereEmitter, SpriteBatch, SpriteParticle, SubEmitterInheritMask, SubParticleEmitMode, TextureSequencer, TrailBatch, TrailParticle, TurbulenceField, UV_DISTORTION_DEFAULT_UV, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, createSeededRandom, cubeFaceUrls, damp, defaultMeshLighting, degToRad, denormalize, ensureEnvAtlasFromCube, erosionEqual, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRandomSource, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, gradientMapEqual, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, mapUVEqual, meshRimEqual, normalize, normalizeErosion, normalizeGradientMap, normalizeMapUV, normalizeMeshRim, normalizeTextureUV, normalizeUVDistortion, _default$5 as particleFragShader, _default$4 as particlePhysicsFragShader, _default$3 as particleVertShader, pingpong, planBehaviorFusion, radToDeg, randFloat, randFloatSpread, randInt, random, readsUV1, registerShaderChunks, seededRandom, setPhysicsResolver, setQuaternionFromProperEuler, setRandomSource, smootherstep, smoothstep, _default$2 as stretchedBillboardVertShader, subEmitterInheritMask, textureUVEqual, textureUVToJSON, _default$1 as trailFragShader, _default as trailVertShader, unloadPlugin, uvDistortionEqual, withRandomSource };
-export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, BeamEnd, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, CullingMode, DonutEmitterParameters, EdgeEmitterParameters, EffectPoolOptions, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FrameOverLifeOptions, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GradientMapChannel, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshLighting, MeshLightingSettings, MeshRim, MeshSettings, ParameterPair, ParameterType, Particle, ParticleErosion, ParticleErosionOptions, ParticleGradientMap, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, ParticleUVDistortion, ParticleUVDistortionOptions, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RandomSource, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, ScalingMode, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SortMode, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, SubEmitterInheritance, TextureUV, TrailSettings, UVChannel, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };
+export { ApplyCollision, ApplyForce, ApplySequences, AxisAngleGenerator, BatchedRenderer, BehaviorFromJSON, BehaviorTypes, Bezier, BoxEmitFrom, BoxEmitter, ChangeEmitDirection, CircleEmitter, ColorBySpeed, ColorGeneratorFromJSON, ColorOverLife, ColorRange, ConeEmitter, ConstantColor, ConstantValue, DEG2RAD, DonutEmitter, EROSION_DEFAULT_SOFTNESS, EdgeEmitter, EffectPool, EmitSubParticleSystem, EmitterFrame, EmitterFromJSON, EmitterMode, EmitterShapes, Euler, EulerGenerator, ForceOverLife, FrameOverLife, GRADIENT_MAP_WEIGHTS, GeneratorFromJSON, Gradient, GravityForce, GridEmitter, HemisphereEmitter, InheritVelocity, IntervalValue, LimitSpeedOverLife, MAX_TRAIL_TESSELLATION, MathUtils, Matrix3, Matrix4, MeshSurfaceEmitter, MeshSurfaceEmitterPlugin, NodeParticle, Noise, OrbitOverLife, ParticleEmitter, ParticleStore, ParticleSystem, PiecewiseBezier, PiecewiseFunction, Plugins, PointEmitter, QUARKS_FORMAT_VERSION, QuarksFormatError, QuarksLoader, QuarksPrefab, QuarksUtil, Quaternion, QuaternionView, RAD2DEG, RandomColor, RandomColorBetweenGradient, RandomQuatGenerator, RecordState, RectangleEmitter, RenderMode, Rotation3DOverLife, RotationBySpeed, RotationGeneratorFromJSON, RotationOverLife, SequencerFromJSON, ShapeTransform, SizeBySpeed, SizeOverLife, SpeedOverLife, SphereEmitter, SpriteParticle, SubEmitterInheritMask, SubParticleEmitMode, TextureSequencer, TrailParticle, TurbulenceField, UV_DISTORTION_DEFAULT_STRENGTH, UV_DISTORTION_DEFAULT_UV, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, createSeededRandom, cubeFaceUrls, damp, decodeSoftDepth, defaultMeshLighting, degToRad, denormalize, disposeEnvAtlas, ensureEnvAtlasFromCube, erosionEqual, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRandomSource, getValueFromEmitterMode, gradientMapEqual, inverseLerp, isPowerOfTwo, lerp, loadPlugin, mapLinear, mapUVEqual, meshRimEqual, normalize, normalizeErosion, normalizeGradientMap, normalizeMapUV, normalizeMeshRim, normalizeTextureUV, normalizeUVDistortion, pingpong, planBehaviorFusion, quarksNodeId, radToDeg, randFloat, randFloatSpread, randInt, random, readBehaviorSpace, readsUV1, seededRandom, serializeEffect, setPhysicsResolver, setQuaternionFromProperEuler, setRandomSource, shaderProgram, shaderVariants, smootherstep, smoothstep, softDepthParams, speedFraction, subEmitterInheritMask, textureSourceUrl, textureUVEqual, textureUVToJSON, trailCurveTension, trailLifetime, trailMinVertexDistance, trailTessellation, trailTextureMode, trailTextureScale, unloadPlugin, uvDistortionEqual, withRandomSource };
+export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BeamEnd, Behavior, BehaviorPlugin, BehaviorSpace, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, CullingMode, DepthTextureOptions, DonutEmitterParameters, EdgeEmitterParameters, EffectPoolOptions, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FrameOverLifeOptions, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GradientMapChannel, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshLighting, MeshLightingSettings, MeshRim, MeshSettings, ParameterPair, ParameterType, Particle, ParticleErosion, ParticleErosionOptions, ParticleGradientMap, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, ParticleUVDistortion, ParticleUVDistortionOptions, PhysicsResolver, Plugin, QuarksBatchLoadOptions, QuarksEffectJSON, QuarksGeometryJSON, QuarksImageJSON, QuarksJSONLoadEntry, QuarksLoadOptions, QuarksLoaderOptions, QuarksNodeJSON, QuarksResourceKind, QuarksResourceResolver, QuarksTextureJSON, QuarksTimelineClip, RandomSource, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, ScalingMode, Sequencer, SerializationOptions, SerializeEffectOptions, ShaderContext, ShaderDepth, ShaderProgram, ShaderSettings, ShaderSources, ShaderVariant, ShapeJSON, ShapeTransformJSON, SoftDepthEncoding, SortMode, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, SubEmitterInheritance, TextureUV, TrailSettings, TrailTextureMode, UVChannel, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };