babylon.quarks 0.21.0 → 0.24.0

package/dist/types/index.d.ts

@@ -2,10 +2,13 @@ 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 { Node } from '@babylonjs/core/node';
 
 declare class Vector2 {
     x: number;
@@ -366,6 +369,25 @@ declare const MathUtils: {
     denormalize: typeof denormalize;
 };
 
+/**
+ * A `Quaternion` whose components live in a shared `Float32Array` at a fixed
+ * offset. Every `Quaternion` method reads and writes `_x` .. `_w`, so replacing
+ * those four with accessors inherits the whole API; they are installed on the
+ * prototype because TypeScript forbids overriding an inherited property with
+ * an accessor in the class body (TS2611).
+ */
+declare class QuaternionView extends Quaternion {
+    data: Float32Array;
+    offset: number;
+    _x: number;
+    _y: number;
+    _z: number;
+    _w: number;
+    constructor(data: Float32Array, offset: number);
+    /** Points the view at a new backing array and row offset. */
+    bind(data: Float32Array, offset: number): void;
+}
+
 /**
  * A `Vector3` whose components live in a shared `Float32Array` at a fixed
  * offset rather than in three own properties.
@@ -648,6 +670,12 @@ declare class Gradient implements FunctionColorGenerator {
      * signature check so a gradient edited in an editor is picked up.
      */
     refreshTable(): void;
+    /**
+     * The sampled table {@link genColor} currently reads from, or null while
+     * none has been built. Lets a compiled behavior pass interpolate the table
+     * inline instead of calling in here once per particle.
+     */
+    sampledTable(): Float32Array | null;
     /** Drops the sampled table, so later reads go back to evaluating the keys. */
     clearTable(): void;
     genColor(memory: GeneratorMemory, color: Vector4, t: number): Vector4;
@@ -808,6 +836,12 @@ declare class PiecewiseBezier extends PiecewiseFunction<Bezier> implements Funct
      * change. That is a handful of float compares per frame.
      */
     refreshTable(): void;
+    /**
+     * The sampled table {@link genValue} currently reads from, or null while
+     * none has been built. Lets a compiled behavior pass interpolate the table
+     * inline instead of calling in here once per particle.
+     */
+    sampledTable(): Float32Array | null;
     /** Drops the sampled table, so later reads go back to evaluating the curve. */
     clearTable(): void;
     genValue(memory: GeneratorMemory, t?: number): number;
@@ -908,6 +942,38 @@ declare class ParticleStore {
      * tightly balanced emitters flicker.
      */
     scalars: Float64Array;
+    /**
+     * Scalars the renderer uploads and the behaviors write, one per row, so a
+     * batch copies them as ranges instead of visiting every particle object:
+     * sprite rotation angle and its rate, texture tile, mirroring bits and the
+     * speed the particle was born with. A mesh particle keeps its quaternion
+     * rotation on the particle; its `rotation` row here is then unused.
+     */
+    rotation: Float32Array;
+    angularVelocity: Float32Array;
+    uvTile: Float32Array;
+    startSpeed: Float32Array;
+    /** Bit 1 mirrors along U, bit 2 along V. */
+    flip: Uint8Array;
+    /**
+     * Quaternion rotation and one step's quaternion turn, 4 per row, for
+     * particles that rotate by quaternion (mesh render mode). Empty until
+     * {@link ensureQuaternionColumns} is asked for them, so systems of
+     * billboards do not pay for columns they never read.
+     */
+    rotationQuaternion: Float32Array;
+    angularVelocityQuaternion: Float32Array;
+    /**
+     * Numeric copy of each particle's generator memory, {@link memoryStride}
+     * values per row. The spawn path calls every generator's `startGen` in a
+     * fixed order, so a given slot holds the same generator's sample for every
+     * particle, which lets a compiled behavior pass read a particle's random
+     * sample from a column instead of through its `memory` array. Slots that
+     * hold something other than a number are NaN here; readers then fall back
+     * to the array. Empty until {@link recordMemory} sees the first spawn.
+     */
+    memory: Float64Array;
+    memoryStride: number;
     /** Values per row in {@link scalars}. */
     static readonly SCALAR_STRIDE = 3;
     /** Offsets within a {@link scalars} row. */
@@ -936,7 +1002,29 @@ declare class ParticleStore {
      * leaves every particle's view of it pointing at the old one.
      */
     keepPreviousVelocity(): boolean;
+    /**
+     * Mirrors a freshly spawned particle's generator memory into the
+     * {@link memory} column, widening the column when this spawn used more
+     * slots than any before it.
+     */
+    recordMemory(row: number, memory: ReadonlyArray<unknown>): void;
+    /**
+     * Whether {@link previousSize} is a snapshot of its own or an alias of
+     * {@link size}. A system whose behaviors never change a particle's size
+     * after birth has nothing to carry between steps for it, and aliasing the
+     * two saves the copy a step would otherwise make; readers that interpolate
+     * from previous to current then get the current value unchanged.
+     */
+    useSizeSnapshot(enabled: boolean): void;
+    /** The same for {@link previousColor}, see {@link useSizeSnapshot}. */
+    useColorSnapshot(enabled: boolean): void;
+    /**
+     * Allocates the quaternion columns. Returns true on the call that did,
+     * which means views already bound to the store need re-binding.
+     */
+    ensureQuaternionColumns(): boolean;
     swapRows(a: number, b: number): void;
+    private static swap1;
     private static growDouble;
     private static swap3;
     private static swap4;
@@ -944,8 +1032,15 @@ declare class ParticleStore {
 }
 
 interface EmissionState {
+    /** Bursts whose first wave has fired this loop, in time order. */
     burstIndex: number;
+    /** Wave of the burst being spawned right now (0 for its first wave). */
     burstWaveIndex: number;
+    /**
+     * Waves fired so far this loop, per burst. Created by the system on first
+     * use, so states made elsewhere (sub emitters) can leave it out.
+     */
+    burstWaves?: number[];
     burstParticleIndex: number;
     burstParticleCount: number;
     isBursting: boolean;
@@ -953,6 +1048,10 @@ interface EmissionState {
     waitEmiting: number;
     travelDistance: number;
     previousWorldPos?: Vector3;
+    /** The particle a sub emission comes from, when it does; see `EmitSubParticleSystem.inherit`. */
+    particle?: Particle;
+    /** Bit mask of the parent's properties the spawned particles take, see `SubEmitterInheritMask`. */
+    inherit?: number;
 }
 interface Resource {
 }
@@ -1384,10 +1483,11 @@ declare class SpriteParticle implements Particle {
      */
     parentMatrix?: Matrix4;
     /**
-     * Initial speed of the particle.
+     * Initial speed of the particle, kept in the store's `startSpeed` column.
      * @type {number}
      */
-    startSpeed: number;
+    get startSpeed(): number;
+    set startSpeed(value: number);
     /**
      * Initial color of the particle.
      * @type {Vector4}
@@ -1447,31 +1547,51 @@ declare class SpriteParticle implements Particle {
     get speedModifier(): number;
     set speedModifier(value: number);
     /**
-     * Angular velocity of the particle.
+     * View of this particle's row in the store's quaternion rotation column,
+     * when it rotates by quaternion (mesh render mode); undefined while it
+     * rotates by an angle, which then lives in the store's `rotation` column.
+     * Always present so every sprite particle keeps one hidden class.
+     */
+    private rotationQuaternion;
+    /** Same split for the turn rate: a quaternion step here, a scalar rate in the store. */
+    private angularVelocityQuaternion;
+    /**
+     * Angular velocity of the particle: a rate in radians per second for an
+     * angle rotation, one step's turn for a quaternion rotation. Both live in
+     * the store so the renderer and compiled behaviors read them as ranges;
+     * assigning a quaternion copies it into the particle's row and returns a
+     * view of that row from then on.
      * @type {number | Quaternion}
      */
-    angularVelocity?: number | Quaternion;
+    get angularVelocity(): number | Quaternion;
+    set angularVelocity(value: number | Quaternion | undefined);
     /**
-     * Rotation of the particle.
+     * Rotation of the particle: an angle, or a quaternion for mesh particles.
+     * Both live in the store; see {@link angularVelocity} for how assigning a
+     * quaternion behaves.
      * @type {number | Quaternion}
      */
-    rotation: number | Quaternion;
+    get rotation(): number | Quaternion;
+    set rotation(value: number | Quaternion);
     /**
      * Color of the particle.
      * @type {Vector4}
      */
     color: Vector4;
     /**
-     * UV tile index.
+     * UV tile index, kept in the store's `uvTile` column.
      * @type {number}
      */
-    uvTile: number;
+    get uvTile(): number;
+    set uvTile(value: number);
     /**
      * Mirroring picked at birth from the system's `flip` fractions: bit 1
-     * mirrors the sprite along U, bit 2 along V. 0 draws it as is.
+     * mirrors the sprite along U, bit 2 along V. 0 draws it as is. Kept in
+     * the store's `flip` column.
      * @type {number}
      */
-    flip: number;
+    get flip(): number;
+    set flip(value: number);
     /**
      * @param store - Column storage to bind to. A private single-row store is
      * created when omitted, so a standalone `new SpriteParticle()` still works.
@@ -1519,10 +1639,11 @@ declare class TrailParticle implements Particle {
      */
     parentMatrix?: Matrix4;
     /**
-     * Initial speed of the particle.
+     * Initial speed of the particle, kept in the store's `startSpeed` column.
      * @type {number}
      */
-    startSpeed: number;
+    get startSpeed(): number;
+    set startSpeed(value: number);
     /**
      * Initial color of the particle.
      * @type {Vector4}
@@ -1604,16 +1725,31 @@ declare class TrailParticle implements Particle {
      * sample without allocating. This list is no longer populated or rendered.
      * @type {LinkedList<RecordState>}
      */
-    previous: LinkedList<RecordState>;
+    get previous(): LinkedList<RecordState>;
+    set previous(value: LinkedList<RecordState>);
+    private _previous;
     /**
-     * UV tile index.
+     * UV tile index, kept in the store's `uvTile` column.
      * @type {number}
      */
-    uvTile: number;
+    get uvTile(): number;
+    set uvTile(value: number);
     /** Ring buffer of recorded positions, 3 floats per sample. */
     historyPositions: Float32Array;
-    /** Ring buffer of recorded widths, 1 float per sample. */
+    /** Ring buffer of the widths the renderer draws, 1 float per sample. */
     historySizes: Float32Array;
+    /**
+     * Ring buffer of the particle's size (`size.x`) at each sample, before any
+     * behavior rescaled it. Width behaviors scale this rather than
+     * `historySizes`, so their factor is never compounded step after step.
+     */
+    historyBaseSizes: Float32Array;
+    /**
+     * Factor the next recorded sample's width is drawn with — what a width
+     * behavior gives the head of the trail, which is recorded after the
+     * behaviors have run. 1 unless such a behavior sets it.
+     */
+    headWidthScale: number;
     /** Ring buffer of recorded colors, 4 floats per sample. */
     historyColors: Float32Array;
     /** Number of samples the ring buffers can hold. */
@@ -1790,15 +1926,30 @@ declare class ApplySequences implements Behavior {
  *
  * Each behavior walking the particle array on its own means the array, and
  * every particle in it, is re-read once per behavior. Merging the ones this
- * module recognises into one pass reads each particle once — worth roughly
- * 1.2x at a hundred thousand particles and up to 1.6x at twenty thousand,
- * where the per-pass overhead weighs most.
+ * module recognises into one pass reads each particle once.
+ *
+ * The compiled pass works on the {@link ParticleStore} columns directly. Going
+ * through the particle objects instead — `particles[i].color.x` — means three
+ * dependent loads through objects scattered over the heap for every number
+ * touched (the particle, its `Vector4View`, the view's array), and at tens of
+ * thousands of particles that pointer chasing, not the arithmetic, is what the
+ * step spends its time on: measured at roughly ten times the cost of reading
+ * the same numbers out of the columns. The particle object is only reached for
+ * when a generator needs the particle's own memory (a per-particle random
+ * sample) or holds an object-valued attribute (a quaternion rotation).
+ *
+ * The pass relies on the system's invariant that `particles[i]` owns row `i`
+ * of the store, which the system keeps when it compacts the dead.
  *
  * A behavior that is not recognised keeps its own pass, in its original place
  * in the order, so nothing here depends on the built-in set being complete.
  */
-/** Runs the compiled work for `particles[0..count)`. */
-type FusedPass = (behaviors: Array<Behavior>, particles: Array<Particle>, count: number, delta: number) => void;
+/**
+ * Runs the compiled work for `particles[0..count)`. `store` is the column
+ * storage behind the particles; when omitted it is taken from the first
+ * particle.
+ */
+type FusedPass = (behaviors: Array<Behavior>, particles: Array<Particle>, count: number, delta: number, store?: ParticleStore) => void;
 /** One step of a plan: either a compiled run of behaviors, or a single behavior. */
 interface FusionStep {
     /** Behaviors this step covers, in order. */
@@ -1810,7 +1961,9 @@ interface FusionStep {
  * Splits `behaviors` into steps, merging consecutive recognised ones.
  *
  * Only consecutive behaviors are merged: a behavior that stays on its own must
- * still see the particles exactly where the original order left them.
+ * still see the particles exactly where the original order left them. A lone
+ * recognised behavior is compiled too: the gain is not only the merged loop
+ * but the column access, which its own `updateAll` does not have.
  */
 declare function planBehaviorFusion(behaviors: Array<Behavior>): Array<FusionStep>;
 
@@ -1875,29 +2028,64 @@ declare enum SubParticleEmitMode {
     Birth = 1,
     Frame = 2
 }
+/** A parent particle property sub emitted particles can take over (Unity's sub emitter Inherit). */
+type SubEmitterInheritance = 'color' | 'size' | 'rotation' | 'lifetime';
+/** Bits of `EmissionState.inherit`, one per {@link SubEmitterInheritance}. */
+declare const SubEmitterInheritMask: {
+    readonly color: 1;
+    readonly size: 2;
+    readonly rotation: 4;
+    readonly lifetime: 8;
+};
+/** The mask for a list of inherited properties. */
+declare function subEmitterInheritMask(inherit: ReadonlyArray<SubEmitterInheritance>): number;
 /**
  * Emit a sub particle system from particles.
  */
 declare class EmitSubParticleSystem implements Behavior {
-    private particleSystem;
+    particleSystem: IParticleSystem;
     useVelocityAsBasis: boolean;
     subParticleSystem: IEmitter | undefined;
     mode: SubParticleEmitMode;
     emitProbability: number;
+    /**
+     * 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).
+     */
+    inherit: SubEmitterInheritance[];
     type: string;
     private q_;
     private v_;
     private v2_;
     private subEmissions;
-    constructor(particleSystem: IParticleSystem, useVelocityAsBasis: boolean, subParticleSystem: IEmitter | undefined, mode?: SubParticleEmitMode, emitProbability?: number);
+    /** Finished emission states, kept for reuse: a burst of deaths would otherwise allocate one plus a matrix each. */
+    private spareEmissions;
+    constructor(particleSystem: IParticleSystem, useVelocityAsBasis: boolean, subParticleSystem: IEmitter | undefined, mode?: SubParticleEmitMode, emitProbability?: number, 
+    /**
+     * 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).
+     */
+    inherit?: SubEmitterInheritance[]);
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
+    /**
+     * 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.
+     */
+    private get target();
     private emit;
     frameUpdate(delta: number): void;
     toJSON(): any;
     static fromJSON(json: any, particleSystem: IParticleSystem): Behavior;
     clone(): Behavior;
     reset(): void;
+    private static validInherit;
     private setMatrixFromParticle;
 }
 
@@ -2019,10 +2207,48 @@ declare class Noise implements Behavior {
     power: FunctionValueGenerator | ValueGenerator;
     positionAmount: FunctionValueGenerator | ValueGenerator;
     rotationAmount: FunctionValueGenerator | ValueGenerator;
+    /**
+     * How fast the noise field moves past the particles (Unity's Scroll
+     * Speed), in noise time per second; 0 leaves it still. Sampled once per
+     * frame, so a curve is read at t = 0.
+     */
+    scrollSpeed: FunctionValueGenerator | ValueGenerator;
+    /**
+     * Reshapes the raw noise (Unity's Remap): the curve is read at the
+     * noise value mapped from [-1, 1] to [0, 1], and what it returns is
+     * used in its place. Unset, the noise is used as is.
+     */
+    remap?: FunctionValueGenerator | undefined;
     type: string;
     duration: number;
-    constructor(frequency: FunctionValueGenerator | ValueGenerator, power: FunctionValueGenerator | ValueGenerator, positionAmount?: FunctionValueGenerator | ValueGenerator, rotationAmount?: FunctionValueGenerator | ValueGenerator);
+    constructor(frequency: FunctionValueGenerator | ValueGenerator, power: FunctionValueGenerator | ValueGenerator, positionAmount?: FunctionValueGenerator | ValueGenerator, rotationAmount?: FunctionValueGenerator | ValueGenerator, 
+    /**
+     * How fast the noise field moves past the particles (Unity's Scroll
+     * Speed), in noise time per second; 0 leaves it still. Sampled once per
+     * frame, so a curve is read at t = 0.
+     */
+    scrollSpeed?: FunctionValueGenerator | ValueGenerator, 
+    /**
+     * Reshapes the raw noise (Unity's Remap): the curve is read at the
+     * noise value mapped from [-1, 1] to [0, 1], and what it returns is
+     * used in its place. Unset, the noise is used as is.
+     */
+    remap?: FunctionValueGenerator | undefined);
+    /** Noise time the field has scrolled by so far. */
+    private scrollOffset;
+    private readonly scrollMemory;
+    /** The noise value a generator gives at `time`, through the remap when there is one. */
+    private sample;
     initialize(particle: Particle): void;
+    /**
+     * Values of the generators that are constants, cached by {@link frameUpdate};
+     * NaN where the generator has to be evaluated per particle.
+     */
+    private _frequency;
+    private _power;
+    private _positionAmount;
+    private _rotationAmount;
+    private static constantOf;
     update(particle: Particle, _: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
     toJSON(): any;
@@ -2090,14 +2316,27 @@ declare class RotationBySpeed implements Behavior {
 
 /**
  * Apply rotation to particles over their life.
+ *
+ * A billboard (rotation is an angle) turns in its own plane. A mesh particle
+ * (rotation is a quaternion) turns about its local Z axis — the axis a
+ * number `startRotation` turns a mesh about, and what Unity's Rotation over
+ * Lifetime without separate axes does to mesh particles. For any other axis,
+ * or a turn about all three, use {@link Rotation3DOverLife}.
  */
 declare class RotationOverLife implements Behavior {
     angularVelocity: ValueGenerator | FunctionValueGenerator;
     type: string;
+    /** Scratch for a mesh particle's rotation step; also read by the fused pass. */
+    tempQuat: Quaternion;
     constructor(angularVelocity: ValueGenerator | FunctionValueGenerator);
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
+    /**
+     * Turns a mesh particle by `angle` about its own Z axis, keeping the step
+     * for the renderer to draw a fraction of between simulation steps.
+     */
+    turnAboutZ(particle: Particle, rotation: Quaternion, angle: number): void;
     toJSON(): any;
     static fromJSON(json: any): Behavior;
     frameUpdate(delta: number): void;
@@ -2216,6 +2455,7 @@ declare class TurbulenceField implements Behavior {
     constructor(scale: Vector3, octaves: number, velocityMultiplier: Vector3, timeScale: Vector3);
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
+    updateAll(particles: Array<Particle>, count: number, delta: number): void;
     toJSON(): any;
     frameUpdate(delta: number): void;
     static fromJSON(json: any): Behavior;
@@ -2237,10 +2477,18 @@ declare class VelocityOverLife implements Behavior {
     orbitalY: FunctionValueGenerator | ValueGenerator;
     orbitalZ: FunctionValueGenerator | ValueGenerator;
     space: VelocityOverLifeSpace;
+    /** Speed away from the orbit centre (Unity's Radial), in the authored space's units. */
+    radial: FunctionValueGenerator | ValueGenerator;
+    /** Where the orbital speeds turn around, relative to the emitter (Unity's Orbital Offset). */
+    orbitalOffset: Vector3;
     type: string;
     /** Learned in {@link initialize}, so undefined until this behavior sees a particle. */
     ps?: IParticleSystem;
-    constructor(linearX?: FunctionValueGenerator | ValueGenerator, linearY?: FunctionValueGenerator | ValueGenerator, linearZ?: FunctionValueGenerator | ValueGenerator, orbitalX?: FunctionValueGenerator | ValueGenerator, orbitalY?: FunctionValueGenerator | ValueGenerator, orbitalZ?: FunctionValueGenerator | ValueGenerator, space?: VelocityOverLifeSpace);
+    constructor(linearX?: FunctionValueGenerator | ValueGenerator, linearY?: FunctionValueGenerator | ValueGenerator, linearZ?: FunctionValueGenerator | ValueGenerator, orbitalX?: FunctionValueGenerator | ValueGenerator, orbitalY?: FunctionValueGenerator | ValueGenerator, orbitalZ?: FunctionValueGenerator | ValueGenerator, space?: VelocityOverLifeSpace, 
+    /** Speed away from the orbit centre (Unity's Radial), in the authored space's units. */
+    radial?: FunctionValueGenerator | ValueGenerator, 
+    /** Where the orbital speeds turn around, relative to the emitter (Unity's Orbital Offset). */
+    orbitalOffset?: Vector3);
     _temp: Vector3;
     _tempEmitterPos: Vector3;
     _tempQ: Quaternion;
@@ -2257,6 +2505,8 @@ declare class VelocityOverLife implements Behavior {
     _axisX: Vector3;
     _axisY: Vector3;
     _axisZ: Vector3;
+    /** The orbit centre in the simulation space, refreshed with the axes. */
+    _center: Vector3;
     initialize(particle: Particle, particleSystem: IParticleSystem): void;
     frameUpdate(delta: number): void;
     update(particle: Particle, delta: number): void;
@@ -2268,13 +2518,29 @@ declare class VelocityOverLife implements Behavior {
 }
 
 /**
- * Apply width to particles based on their length.
+ * 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
+ * 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
+ * is. The head itself gets the curve's value at 0.
+ *
+ * With `absolute` set the curve is the width itself, in world units, ignoring
+ * the particle's size; the head keeps the particle's size. That is how this
+ * behavior read every curve up to 0.21, and an effect JSON written by those
+ * versions (it has no `absolute` field) still loads that way.
  */
 declare class WidthOverLength implements Behavior {
     width: FunctionValueGenerator;
+    absolute: boolean;
     type: string;
     initialize(particle: Particle): void;
-    constructor(width: FunctionValueGenerator);
+    /**
+     * @param width - Width along the trail, head (0) to tail (1).
+     * @param absolute - Read `width` as world units instead of a multiplier on the particle's size.
+     */
+    constructor(width: FunctionValueGenerator, absolute?: boolean);
     update(particle: Particle): void;
     frameUpdate(delta: number): void;
     toJSON(): any;
@@ -2946,6 +3212,50 @@ declare class TextureSequencer implements Sequencer {
     fromImage(img: CanvasImageSource, threshold: number): void;
 }
 
+/**
+ * The one source of randomness for particle simulation.
+ *
+ * Every roll a particle system makes — spawn positions, interval values,
+ * random colours and rotations, burst probability, noise offsets — goes
+ * through {@link random}, so it can be replaced: with a seeded generator for
+ * reproducible tests, replays and lock-step multiplayer, or with a system's own
+ * generator while that system steps (see `ParticleSystem.seed`).
+ *
+ * UUIDs are deliberately not drawn from here; two effects loaded under the same
+ * seed must still get distinct ids.
+ */
+/** A generator in the shape of `Math.random`: uniform in [0, 1). */
+type RandomSource = () => number;
+/** Uniform random number in [0, 1) from the current source. */
+declare function random(): number;
+/** The generator {@link random} currently draws from. */
+declare function getRandomSource(): RandomSource;
+/**
+ * Replaces the generator every roll draws from; `null` restores `Math.random`.
+ * Returns the previous source, so a caller can put it back.
+ */
+declare function setRandomSource(next: RandomSource | null): RandomSource;
+/**
+ * A small, fast seeded generator (mulberry32): the same seed always yields
+ * the same sequence, on every platform. Good enough for visual randomness;
+ * not for anything cryptographic.
+ */
+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;
+
+/**
+ * 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.
+ *
+ * - `'none'`: as they are, system by system. Right for additive blending.
+ * - `'distance'`: farthest from the active camera first, so nearer particles
+ *   cover farther ones.
+ * - `'oldestInFront'` / `'youngestInFront'`: by age.
+ *
+ * Sorting runs over the whole batch after each fill. Trails are not sorted.
+ */
+type SortMode = 'none' | 'distance' | 'oldestInFront' | 'youngestInFront';
 declare enum RenderMode {
     BillBoard = 0,
     StretchedBillBoard = 1,
@@ -2954,6 +3264,56 @@ declare enum RenderMode {
     HorizontalBillBoard = 4,
     VerticalBillBoard = 5
 }
+/**
+ * How mesh particles are lit.
+ *
+ * - `'fixed'` (default): one directional light plus ambient, the same for every
+ *   mesh batch of a renderer, set with {@link BatchedRenderer.setMeshLighting}.
+ * - `'unlit'`: no lighting term — the texture times the particle colour, for
+ *   emissive meshes (fire, energy, glowing blades).
+ * - `'scene'`: follows the scene's first enabled `DirectionalLight` or
+ *   `HemisphericLight` every frame, falling back to the fixed light when there
+ *   is none.
+ *
+ * Only mesh particles are lit; other render modes ignore it.
+ */
+type MeshLighting = 'unlit' | 'fixed' | 'scene';
+/** The light {@link MeshLighting} `'fixed'` mesh particles are lit by. */
+interface MeshLightingSettings {
+    /** Direction the light travels in, world space. Default `(0.4, -1, 0.6)`. */
+    direction: Vector3$1;
+    /** Light colour, intensity folded in. Default white. */
+    color: Color3;
+    /** Light every face gets regardless of its direction. Default `(0.35, 0.35, 0.35)`. */
+    ambient: Color3;
+}
+/** The light mesh particles have always been lit by. */
+declare function defaultMeshLighting(): MeshLightingSettings;
+/**
+ * A rim (Fresnel) term on mesh particles: a colour that grows where the surface
+ * turns away from the camera, `pow(1 - |N·V|, power) * strength`. Unset: no rim.
+ * Only mesh particles draw it.
+ */
+interface MeshRim {
+    /** Edge colour, linear RGB. Default `[1, 1, 1]`. */
+    color: [number, number, number];
+    /** Falloff exponent; higher keeps the rim to a thinner edge. Default 2. */
+    power: number;
+    /** How much of the rim is applied, usually 0…1. Default 1. */
+    strength: number;
+    /**
+     * `'add'` (default) adds the colour, for a glowing edge; `'mix'` blends the
+     * surface toward it, for an outline (a dark ink line with a dark colour).
+     */
+    mode: 'add' | 'mix';
+}
+/**
+ * A complete rim from a partial one, every field defaulted and kept in range,
+ * or undefined when `rim` is unset.
+ */
+declare function normalizeMeshRim(rim: Partial<MeshRim> | null | undefined): MeshRim | undefined;
+/** True when both describe the same rim (or both none). */
+declare function meshRimEqual(a: MeshRim | undefined, b: MeshRim | undefined): boolean;
 interface StoredBatchSettings {
     instancingGeometry: Float32Array;
     instancingIndices: Uint32Array | Uint16Array;
@@ -2978,8 +3338,22 @@ interface StoredBatchSettings {
     reflectionFaces: BaseTexture[] | null;
     reflectionAtlas: BaseTexture | null;
     layerMask: number;
+    /** Babylon rendering group the batch mesh draws in, see {@link VFXBatchSettings.renderingGroupId}. */
+    renderingGroupId: number;
+    /** Whether the scene's fog is applied, see {@link VFXBatchSettings.applyFog}. */
+    applyFog: boolean;
     /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
     pivot?: Vector3;
+    /** Draw order within the batch, see {@link SortMode}. */
+    sortMode: SortMode;
+    /** Smallest size a particle may have on screen, see {@link VFXBatchSettings.minParticleSize}. */
+    minParticleSize: number;
+    /** Largest size a particle may have on screen, see {@link VFXBatchSettings.maxParticleSize}. */
+    maxParticleSize: number;
+    /** Mesh particle lighting, see {@link VFXBatchSettings.lighting}. */
+    lighting?: MeshLighting;
+    /** Mesh particle rim, see {@link VFXBatchSettings.rim}. */
+    rim?: MeshRim;
 }
 declare abstract class VFXBatch {
     mesh: Mesh;
@@ -2987,8 +3361,36 @@ declare abstract class VFXBatch {
     settings: StoredBatchSettings;
     protected maxParticles: number;
     protected scene: Scene;
-    private readonly visibleSystems;
+    protected readonly visibleSystems: IParticleSystem[];
     protected constructor(settings: VFXBatchSettings, scene: Scene);
+    /**
+     * Applies the batch-level scene settings to {@link mesh}. Called on every
+     * mesh the batch creates, since the buffers rebuild it.
+     *
+     * The bounds of a batch mesh are not kept, so Babylon cannot sort it among
+     * the scene's transparent meshes by distance; `alphaIndex` from the
+     * system's render order puts it where the author said, and the rendering
+     * group and layer mask reach the mesh at all (they used to stop at the
+     * settings).
+     */
+    protected configureMesh(): void;
+    private readonly boundsMin_;
+    private readonly boundsMax_;
+    /**
+     * Sets the batch mesh's bounds to the union of its filled systems' world
+     * bounds, so Babylon skips the draw when none of them is in view. Called
+     * after each fill, over the systems {@link getVisibleSystems} last returned.
+     * A batch whose systems have no measured bounds stays always drawn.
+     */
+    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
+     * disabled, so toggling fog at runtime needs no recompile.
+     */
+    protected static readonly FOG_UNIFORMS: string[];
+    protected fogDefines(): string[];
+    protected bindFog(material: ShaderMaterial): void;
     addSystem(system: IParticleSystem): void;
     removeSystem(system: IParticleSystem): void;
     /**
@@ -2998,6 +3400,8 @@ declare abstract class VFXBatch {
      */
     getVisibleSystems(): IParticleSystem[];
     applyDepthTexture(depthTexture: BaseTexture | null): void;
+    /** Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it. */
+    applyMeshLighting(_lighting: MeshLightingSettings): void;
     abstract setupBuffers(): void;
     abstract expandBuffers(target: number): void;
     abstract rebuildMaterial(): void;
@@ -3044,6 +3448,17 @@ interface VFXBatchSettings {
      */
     reflectionAtlas: BaseTexture | null;
     layerMask: number;
+    /**
+     * Babylon rendering group (`mesh.renderingGroupId`) the batch draws in,
+     * 0 by default. Systems with different groups are batched apart.
+     */
+    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.
+     */
+    applyFog: boolean;
     /**
      * Offset of billboard quads from their particle, in particle-size units
      * (Unity's renderer Pivot). On billboards x/y move the quad in its own plane
@@ -3052,6 +3467,27 @@ interface VFXBatchSettings {
      * y across, and z is unused. Absent or zero: no offset. Meshes ignore it.
      */
     pivot?: Vector3;
+    /** Draw order within the batch, see {@link SortMode}. Unset is `'none'`. Systems that differ are batched apart. */
+    sortMode?: SortMode;
+    /**
+     * Smallest size a billboard or stretched particle may have on screen, as a
+     * fraction of the viewport height (Unity's Min Particle Size); 0 by default.
+     * Meshes and trails ignore it. Systems that differ are batched apart.
+     */
+    minParticleSize?: number;
+    /**
+     * Largest size a billboard or stretched particle may have on screen, as a
+     * fraction of the viewport height (Unity's Max Particle Size); unlimited by
+     * default. Meshes and trails ignore it. Systems that differ are batched apart.
+     */
+    maxParticleSize?: number;
+    /**
+     * How mesh particles are lit (`'unlit'`, `'fixed'` or `'scene'`); unset is
+     * `'fixed'`. See {@link MeshLighting}. Other render modes ignore it.
+     */
+    lighting?: MeshLighting;
+    /** Rim (Fresnel) term on mesh particles; unset draws none. See {@link MeshRim}. */
+    rim?: MeshRim;
 }
 interface AdaptivePerformanceOptions {
     targetFrameMs: number;
@@ -3094,7 +3530,44 @@ declare class BatchedRenderer extends TransformNode {
     private static readonly EMPTY_BATCH_GRACE_FRAMES;
     private adaptivePerformanceState;
     private lastAppliedQuality;
+    private meshLighting;
+    /**
+     * Whether systems whose {@link ParticleSystem.cullingMode} is not
+     * `'always'` are tested against the active cameras each frame and paused
+     * while unseen. Off, every system simulates every frame; the batches' own
+     * frustum culling of the draw stays on either way.
+     */
+    cullingEnabled: boolean;
+    /**
+     * Time per frame, in milliseconds, that systems coming back into view may
+     * spend together on the steps they missed while culled (`'pauseAndCatchUp'`).
+     * Steps that do not fit are dropped, not deferred, so a crowd of effects
+     * reappearing at once costs at most this. 2 by default.
+     */
+    catchUpBudgetMs: number;
+    /**
+     * Time per frame, in milliseconds, after which the systems still to be
+     * advanced run one step instead of catching up on a long frame. The time
+     * the skipped steps would have covered is dropped, so a frame that already
+     * ran long cannot make the next one longer still. Unlimited by default;
+     * {@link configureAdaptivePerformance} does not set it.
+     */
+    simulationBudgetMs: number;
+    /** Frustum planes of the active cameras, six per camera, rebuilt each update. */
+    private frustumPlanes;
+    private readonly boundsMin;
+    private readonly boundsMax;
     constructor(name: string, scene: Scene);
+    /**
+     * Gathers the frustum planes of the cameras the scene renders with, six per
+     * camera. Empty when there is no camera yet; systems are then never culled.
+     */
+    private collectFrustumPlanes;
+    /**
+     * True when `system`'s world bounds reach into at least one camera's
+     * frustum, or when it has no bounds to test (empty, or not yet measured).
+     */
+    private isSystemInView;
     private static clamp;
     private static equals;
     addSystem(system: IParticleSystem): void;
@@ -3109,6 +3582,20 @@ declare class BatchedRenderer extends TransformNode {
      */
     updateSystem(system: IParticleSystem): void;
     setDepthTexture(depthTexture: BaseTexture | null): void;
+    /**
+     * Sets the light mesh particles with `lighting: 'fixed'` (the default) are
+     * lit by, for every mesh batch of this renderer, including ones created
+     * later. Fields left out keep their current value. Also the fallback for
+     * `'scene'` lighting when the scene has no directional or hemispheric light.
+     *
+     * @example
+     * ```ts
+     * renderer.setMeshLighting({direction: new Vector3(-0.3, -1, 0.2), color: new Color3(1, 0.9, 0.75)});
+     * ```
+     */
+    setMeshLighting(lighting: Partial<MeshLightingSettings>): void;
+    /** A copy of the light set with {@link setMeshLighting}. */
+    getMeshLighting(): MeshLightingSettings;
     configureAdaptivePerformance(options?: Partial<AdaptivePerformanceOptions>): void;
     disableAdaptivePerformance(resetQuality?: boolean): void;
     getAdaptivePerformanceState(): AdaptivePerformanceState;
@@ -3142,6 +3629,63 @@ declare class BatchedRenderer extends TransformNode {
 
 declare const BatchedParticleRenderer: typeof BatchedRenderer;
 
+interface EffectPoolOptions {
+    /** The renderer every copy the pool makes is added to. */
+    renderer: BatchedRenderer;
+    /** Copies made up front, so the first plays do not pay for cloning. Default 0. */
+    prewarm?: number;
+    /** Most copies the pool will ever hold; {@link EffectPool.acquire} returns null past it. Default unlimited. */
+    maxSize?: number;
+}
+/**
+ * A pool of copies of one effect, for effects played many times over: hits,
+ * footsteps, muzzle flashes, pickups.
+ *
+ * {@link acquire} hands out an idle copy (or makes one), places it and plays
+ * it; a copy whose every system has finished goes back to the pool by itself,
+ * so a one-shot effect needs nothing more. A looping effect is ended with
+ * {@link stop}, which lets its particles die out before the copy returns, or
+ * dropped at once with {@link release}.
+ *
+ * Idle copies are parked disabled, which costs the renderer nothing, and keep
+ * their place in its batches, so acquiring one allocates nothing.
+ *
+ * The template itself is never played by the pool; it is only cloned. Disable
+ * it, or keep it out of the renderer, if it is not meant to be seen.
+ */
+declare class EffectPool {
+    private readonly template;
+    private readonly options;
+    private readonly idle;
+    private readonly playing;
+    private readonly systemsOf;
+    private disposed;
+    constructor(template: TransformNode, options: EffectPoolOptions);
+    /** Copies currently playing. */
+    get activeCount(): number;
+    /** Copies parked and ready. */
+    get idleCount(): number;
+    /**
+     * Takes an idle copy (making one when none is idle and the pool is under
+     * its size), parents it, places it and starts it from the beginning.
+     * Null when the pool is full or disposed.
+     */
+    acquire(position?: Vector3$1, parent?: Node | null): TransformNode | null;
+    /**
+     * Ends the emission of a playing copy; it returns to the pool on its own
+     * once its particles have died, looping systems included.
+     */
+    stop(copy: TransformNode): void;
+    /** Puts a copy back at once, particles and all, parked and disabled. */
+    release(copy: TransformNode): void;
+    /** Disposes every copy, playing or idle. The template is left alone. */
+    dispose(): void;
+    private makeCopy;
+    private disposeCopy;
+    /** The copy a system belongs to is done when all of its systems are. */
+    private readonly onSystemFinished;
+}
+
 /** 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. */
@@ -3217,6 +3761,23 @@ interface BurstParameters {
     interval: number;
     probability: number;
 }
+/**
+ * What a system does while no camera can see its particles (Unity's Culling
+ * Mode). The {@link BatchedRenderer} tests each system's bounds against the
+ * active cameras' frusta every frame.
+ *
+ * - `'always'` keeps simulating off screen, so an effect is exactly where it
+ *   would have been when it comes back into view. The default, and the only
+ *   safe choice for an emitter whose particles reach the screen from off it.
+ * - `'pause'` freezes the system off screen and resumes it where it left off.
+ * - `'pauseAndCatchUp'` freezes it too, then runs the missed time (up to a few
+ *   seconds) within the renderer's catch-up budget when it is seen again.
+ *
+ * An empty system is never culled, so it can start emitting and grow the
+ * bounds that decide its visibility. A system another one emits into is never
+ * culled either; its parent decides.
+ */
+type CullingMode = 'always' | 'pause' | 'pauseAndCatchUp';
 interface ParticleSystemParameters {
     autoDestroy?: boolean;
     looping?: boolean;
@@ -3265,6 +3826,28 @@ interface ParticleSystemParameters {
     pivot?: Vector3;
     /** Fraction of billboard particles mirrored along U (x) and V (y), see {@link ParticleSystem.flip}. */
     flip?: Vector2;
+    /** How mesh particles are lit, see {@link ParticleSystem.lighting}. Default `'fixed'`. */
+    lighting?: MeshLighting;
+    /** Rim (Fresnel) term on mesh particles, see {@link ParticleSystem.rim}. Default none. */
+    rim?: Partial<MeshRim>;
+    /** Multiplier on the time the system is advanced by, see {@link ParticleSystem.playbackSpeed}. Default 1. */
+    playbackSpeed?: number;
+    /** What the system does while off screen, see {@link CullingMode}. Default `'always'`. */
+    cullingMode?: CullingMode;
+    /** Seed for this system's own random generator, see {@link ParticleSystem.seed}. Default none. */
+    seed?: number;
+    /** Draw order within the batch, see {@link ParticleSystem.sortMode}. Default `'none'`. */
+    sortMode?: SortMode;
+    /** Whether particles start turned along their direction of travel, see {@link ParticleSystem.alignToDirection}. Default false. */
+    alignToDirection?: boolean;
+    /** Smallest on-screen size, as a fraction of the viewport height, see {@link ParticleSystem.minParticleSize}. Default 0. */
+    minParticleSize?: number;
+    /** Largest on-screen size, as a fraction of the viewport height, see {@link ParticleSystem.maxParticleSize}. Default unlimited. */
+    maxParticleSize?: number;
+    /** Babylon rendering group of the batch, see {@link ParticleSystem.renderingGroupId}. Default 0. */
+    renderingGroupId?: number;
+    /** Whether the scene's fog applies, see {@link ParticleSystem.applyFog}. Default true. */
+    applyFog?: boolean;
     scene?: Scene;
 }
 interface BurstParametersJSON {
@@ -3296,6 +3879,24 @@ interface ParticleSystemJSONParameters {
     instancingGeometry?: any;
     renderMode: number;
     renderOrder?: number;
+    /** Written only when not 0. */
+    renderingGroupId?: number;
+    /** Written only when false. */
+    applyFog?: boolean;
+    /** Written only when not 1. */
+    playbackSpeed?: number;
+    /** Written only when not `'always'`. */
+    cullingMode?: CullingMode;
+    /** Written only when set. */
+    seed?: number;
+    /** Written only when not `'none'`. */
+    sortMode?: SortMode;
+    /** Written only when true. */
+    alignToDirection?: boolean;
+    /** Written only when not 0. */
+    minParticleSize?: number;
+    /** Written only when limited. */
+    maxParticleSize?: number;
     speedFactor?: number;
     texture?: string;
     material?: string;
@@ -3392,6 +3993,8 @@ declare class ParticleSystem implements IParticleSystem {
     private previousEmitterPos?;
     private tempEmitterPos;
     private temp;
+    /** Emitter matrix moved along the step's path, see spawnAlongPath. */
+    private pathMatrix;
     private normalMatrix;
     private memory;
     private listeners;
@@ -3404,6 +4007,12 @@ declare class ParticleSystem implements IParticleSystem {
     /** 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;
     /** @internal **/
     _renderer?: BatchedRenderer;
     set time(time: number);
@@ -3411,7 +4020,11 @@ declare class ParticleSystem implements IParticleSystem {
     get isEmitEnded(): boolean;
     /** Whether continuous or queued emission can still spawn particles before the system is done. */
     hasPendingEmission(): boolean;
-    /** Non-looping system with no particles left and nothing left to emit. */
+    /**
+     * No particles left and nothing left to emit: a non-looping system that
+     * ran its course, or a looping one whose emission was ended with
+     * {@link endEmit} and whose last particle has died.
+     */
     isFinished(): boolean;
     get layers(): {
         mask: number;
@@ -3433,8 +4046,54 @@ declare class ParticleSystem implements IParticleSystem {
      * {@link VFXBatchSettings.pivot}. Assign a new vector to change it: editing
      * the returned one in place does not reach the renderer.
      */
+    /**
+     * The order this system's batch draws its particles in (Unity's Sort
+     * Mode), `'none'` by default. Alpha blended smoke wants `'distance'`;
+     * additive effects need nothing. Sorting covers the whole batch, so systems
+     * with different modes are batched apart. See {@link SortMode}.
+     */
+    get sortMode(): SortMode;
+    set sortMode(mode: SortMode);
+    /**
+     * Smallest size a billboard or stretched particle is drawn at, as a
+     * fraction of the viewport height (Unity's Min Particle Size); 0 by
+     * default. Keeps distant sparks from vanishing. Meshes and trails ignore it.
+     */
+    get minParticleSize(): number;
+    set minParticleSize(size: number);
+    /**
+     * Largest size a billboard or stretched particle is drawn at, as a fraction
+     * of the viewport height (Unity's Max Particle Size, 0.5 there); unlimited
+     * by default. Keeps a close particle from filling the screen. Meshes and
+     * trails ignore it.
+     */
+    get maxParticleSize(): number;
+    set maxParticleSize(size: number);
     get pivot(): Vector3 | undefined;
     set pivot(v: Vector3 | undefined);
+    /**
+     * How mesh particles are lit: `'fixed'` (the default — the renderer's
+     * light, see {@link BatchedRenderer.setMeshLighting}), `'unlit'` (texture
+     * times colour, for emissive meshes) or `'scene'` (the scene's first
+     * directional or hemispheric light). Saved with the material in the effect
+     * JSON. Other render modes ignore it.
+     */
+    get lighting(): MeshLighting;
+    set lighting(lighting: MeshLighting);
+    /**
+     * Rim (Fresnel) term on mesh particles — a glowing edge (`mode: 'add'`) or
+     * an outline (`'mix'`), see {@link MeshRim}. Undefined (the default) draws
+     * none. Fields left out of an assigned rim take their defaults; assign a
+     * new object to change it, editing the returned one does not reach the
+     * renderer. Saved with the material in the effect JSON. Other render modes
+     * ignore it.
+     */
+    get rim(): MeshRim | undefined;
+    set rim(rim: Partial<MeshRim> | undefined);
+    /** `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;
     get softNearFade(): number;
@@ -3449,6 +4108,87 @@ declare class ParticleSystem implements IParticleSystem {
     set renderMode(renderMode: RenderMode);
     get renderOrder(): number;
     set renderOrder(renderOrder: number);
+    /**
+     * Babylon rendering group the particles draw in (`mesh.renderingGroupId`),
+     * 0 by default. Use it to draw an effect after the scene's other transparent
+     * meshes, or before an overlay group.
+     */
+    get renderingGroupId(): number;
+    set renderingGroupId(group: 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. Saved in the effect JSON only when switched off.
+     */
+    get applyFog(): boolean;
+    set applyFog(apply: boolean);
+    /**
+     * 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.
+     */
+    playbackSpeed: number;
+    /** What this system does while off screen, see {@link CullingMode}. `'always'` by default. */
+    cullingMode: CullingMode;
+    /**
+     * Whether each particle starts turned along the direction its shape sends
+     * it (Unity's Align To Direction): a mesh particle's +Z is pointed along
+     * the velocity, a billboard's top is turned toward it in the emitter's XY
+     * plane. The start rotation is applied on top. A particle with no speed is
+     * left as it is. False by default.
+     */
+    alignToDirection: boolean;
+    private seedValue?;
+    /** The system's own generator while it steps, when seeded; see {@link seed}. */
+    private rng?;
+    /**
+     * Seed for this system's own random generator. Set, every roll the system
+     * makes while it steps (spawn positions, interval values, random colours
+     * and rotations, burst probability) comes from a generator started from
+     * this seed, and restarted with it on {@link restart}: the effect plays out
+     * identically every time, on every machine — for replays, lock-step
+     * 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.
+     */
+    get seed(): number | undefined;
+    set seed(seed: number | undefined);
+    /**
+     * Set by the renderer each frame: true while no active camera sees the
+     * system's bounds and its {@link cullingMode} is not `'always'`.
+     * @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
+     * {@link BatchedRenderer} shares its own budget among all its systems
+     * 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;
     constructor(parameters: ParticleSystemParameters);
     private applyMaterialSettings;
     pause(): void;
@@ -3465,12 +4205,52 @@ declare class ParticleSystem implements IParticleSystem {
     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;
     endEmit(): void;
     dispose(): void;
     restart(): void;
     private firstTimeUpdate;
-    /** @internal */
-    update(delta: number): void;
+    /**
+     * Advances the system by `delta` seconds of host time.
+     *
+     * `stepDeadline` is a `performance.now()` time after which no further
+     * catch-up step of this frame is run: a frame long enough to need several
+     * steps gets at least one, and the time the rest would have covered is
+     * dropped rather than carried, so one slow frame does not grow the next.
+     * `catchUpDeadline` bounds the steps a `'pauseAndCatchUp'` system runs on
+     * coming back into view; unset, the system allows itself
+     * {@link catchUpBudgetMs}. The renderer supplies both from its budgets.
+     * @internal
+     */
+    update(delta: number, stepDeadline?: number, catchUpDeadline?: number): void;
+    /** 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.
+     */
+    private storeBounds;
+    /** Distance of the farthest vertex of the mesh particles' geometry from its origin. */
+    private meshGeometryRadius;
+    /**
+     * World-space axis-aligned bounds of everything this system draws, padded
+     * for particle size, into `min` and `max`. False when the system has no
+     * particles, or none have been measured yet; the caller should then treat
+     * it as visible. Measured in full every few simulated steps and carried,
+     * padded for the motion since, in between: conservative, and at most a
+     * frame behind the display.
+     */
+    getWorldBounds(min: Vector3, max: Vector3): boolean;
+    /**
+     * 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;
     /**
      * Time the display is ahead of (positive) or still ahead of the simulation
      * (negative — the simulation ran a hair early), in seconds. Magnitude never
@@ -3510,9 +4290,47 @@ declare class ParticleSystem implements IParticleSystem {
      * change the generated code's indices.
      */
     private behaviorSteps;
-    /** Advances emission, behaviors, motion and culling by one fixed timestep. */
+    /**
+     * Advances emission, behaviors, motion and culling by one fixed timestep,
+     * on the system's own random generator when it has a {@link seed}.
+     */
     private simulateStep;
+    private stepOnce;
     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.
+     */
+    private spawnAlongPath;
     emit(delta: number, emissionState: EmissionState, emitterMatrix: Matrix4): void;
     toJSON(metaData?: BabylonMetaData | string, _options?: SerializationOptions): ParticleSystemJSONParameters;
     static fromJSON(json: ParticleSystemJSONParameters, meta: BabylonMetaData, dependencies?: {
@@ -3755,8 +4573,20 @@ declare class QuarksUtil {
     static restart(root: Node): void;
     static setAutoDestroy(root: Node, autoDestroy: boolean): void;
     static endEmit(root: Node): void;
-    /** True when every emitter under `root` is a finished non-looping system (or looping). */
+    /**
+     * True when every system under `root` is finished: non-looping ones that
+     * ran their course, looping ones whose emission was ended (see
+     * {@link endEmit}) and whose particles are gone. A looping system still
+     * emitting keeps the effect unfinished.
+     */
     static isEffectFinished(root: Node): boolean;
+    /**
+     * A deep copy of an effect: the node tree under `root` with every particle
+     * system cloned, sub emitter links pointing at the copies, and the same
+     * transforms and enabled state. The copy is not added to any renderer.
+     * Nodes that are neither transform nodes nor emitters are skipped.
+     */
+    static instantiate(root: TransformNode, name?: string): TransformNode;
     private static traverseNode;
 }
 
@@ -3764,21 +4594,21 @@ declare function registerShaderChunks(): void;
 declare function getShaderChunk(chunkName: string): string | undefined;
 declare function getRegisteredShaderChunks(): Readonly<Record<string, string>>;
 
-declare const _default$7: "\nattribute vec3 position;\nattribute vec2 uv;\nattribute vec3 normal;\nattribute vec3 offset;\nattribute vec4 color;\nattribute vec3 size;\nattribute vec4 rotation;\nattribute float uvTile;\n\nuniform mat4 world;\nuniform mat4 view;\nuniform mat4 projection;\n\n#ifdef UV_TILE\nuniform float tileCountX;\nuniform float tileCountY;\n#endif\n\nvarying vec2 vUV;\nvarying vec4 vColor;\nvarying vec3 vNormal;\nvarying vec3 vWorldPos;\n\n#ifdef TILE_BLEND\nvarying vec2 vUV2;\nvarying float vTileBlend;\n#endif\n\n#ifdef SOFT_PARTICLES\nvarying vec4 projPosition;\nvarying float linearDepth;\n#endif\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 scaledPosition = position * size;\n    vec3 rotatedPosition = applyQuaternion(scaledPosition, rotation);\n    vec3 rotatedNormal = normalize(applyQuaternion(normal, rotation));\n    vec3 localPos = rotatedPosition + offset;\n\n    vec4 worldPos = world * vec4(localPos, 1.0);\n    vec4 viewPos = view * worldPos;\n    gl_Position = projection * viewPos;\n\n    vWorldPos = worldPos.xyz;\n    vNormal = normalize((world * vec4(rotatedNormal, 0.0)).xyz);\n\n#ifdef SOFT_PARTICLES\n    projPosition = gl_Position;\n    linearDepth = -viewPos.z;\n#endif\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    #ifdef TILE_BLEND\n        float nextTile = ceil(uvTile);\n        float nextU = mod(nextTile, tc.x) / tc.x;\n        float nextV = 1.0 - floor(nextTile / tc.x) / tc.y - 1.0 / tc.y;\n        vUV2 = uv / tc + vec2(nextU, nextV);\n        vTileBlend = fract(uvTile);\n    #endif\n#else\n    vUV = uv;\n#endif\n\n    vColor = color;\n}\n";
+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: "\nvarying vec2 vUV;\nvarying vec4 vColor;\n\n#ifdef TILE_BLEND\nvarying vec2 vUV2;\nvarying float vTileBlend;\n#endif\n\n#ifdef USE_MAP\nuniform sampler2D map;\n#endif\n\n#ifdef SOFT_PARTICLES\nuniform sampler2D depthTexture;\nuniform vec2 softParams;\nuniform vec4 projParams;\nvarying vec4 projPosition;\nvarying float linearDepth;\n#endif\n\n#ifdef USE_ALPHATEST\nuniform float alphaTest;\n#endif\n\nvoid main() {\n    vec4 baseColor = vColor;\n\n#ifdef USE_MAP\n    vec4 texColor = texture2D(map, vUV);\n    #ifdef TILE_BLEND\n        vec4 texColor2 = texture2D(map, vUV2);\n        texColor = mix(texColor, texColor2, vTileBlend);\n    #endif\n    baseColor *= texColor;\n#endif\n\n#ifdef USE_COLOR_AS_ALPHA\n    baseColor.a *= (baseColor.r + baseColor.g + baseColor.b) / 3.0;\n#endif\n\n#ifdef USE_ALPHATEST\n    if (baseColor.a < alphaTest) discard;\n#else\n    if (baseColor.a < 0.01) discard;\n#endif\n\n    gl_FragColor = baseColor;\n\n#ifdef SOFT_PARTICLES\n    vec2 p2 = projPosition.xy / projPosition.w;\n    p2 = 0.5 * p2 + 0.5;\n    float readDepth = texture2D(depthTexture, p2.xy).r;\n    float zNear = projParams.x;\n    float zFar = projParams.y;\n    float viewDepth = (zFar * zNear) / (zFar - readDepth * (zFar - zNear));\n    float fade = clamp(softParams.y * ((viewDepth - softParams.x) - linearDepth), 0.0, 1.0);\n    gl_FragColor *= fade;\n#endif\n}\n";
+declare const _default$5: string;
 
-declare const _default$4: "\nvarying vec2 vUV;\nvarying vec4 vColor;\nvarying vec3 vNormal;\nvarying vec3 vWorldPos;\n\nuniform vec3 lightDirection;\nuniform vec3 lightColor;\nuniform vec3 ambientColor;\n\n#ifdef TILE_BLEND\nvarying vec2 vUV2;\nvarying float vTileBlend;\n#endif\n\n#ifdef USE_MAP\nuniform sampler2D map;\n#endif\n\n// One 3\u00D72 atlas (px py pz / nx ny nz). Avoids samplerCube and multi-face\n// sampler bindings that raise GL_INVALID_OPERATION on iOS WebKit.\n#ifdef USE_ENVMAP_ATLAS\nuniform sampler2D envAtlas;\nuniform vec3 eyePosition;\nuniform float reflectionLevel;\n\nvec3 sampleEnvAtlas(vec3 r) {\n    vec3 a = abs(r);\n    vec2 localUV;\n    float cellX;\n    float cellY;\n    // Atlas layout: +X +Y +Z on row 0, -X -Y -Z on row 1.\n    if (a.x >= a.y && a.x >= a.z) {\n        cellX = 0.0;\n        if (r.x >= 0.0) {\n            cellY = 0.0;\n            localUV = vec2(-r.z, -r.y) / a.x * 0.5 + 0.5;\n        } else {\n            cellY = 1.0;\n            localUV = vec2(r.z, -r.y) / a.x * 0.5 + 0.5;\n        }\n    } else if (a.y >= a.z) {\n        cellX = 1.0;\n        if (r.y >= 0.0) {\n            cellY = 0.0;\n            localUV = vec2(r.x, r.z) / a.y * 0.5 + 0.5;\n        } else {\n            cellY = 1.0;\n            localUV = vec2(r.x, -r.z) / a.y * 0.5 + 0.5;\n        }\n    } else {\n        cellX = 2.0;\n        if (r.z >= 0.0) {\n            cellY = 0.0;\n            localUV = vec2(r.x, -r.y) / a.z * 0.5 + 0.5;\n        } else {\n            cellY = 1.0;\n            localUV = vec2(-r.x, -r.y) / a.z * 0.5 + 0.5;\n        }\n    }\n    vec2 uv = (vec2(cellX, cellY) + clamp(localUV, 0.0, 1.0)) / vec2(3.0, 2.0);\n    return texture2D(envAtlas, uv).rgb;\n}\n#endif\n\n#ifdef SOFT_PARTICLES\nuniform sampler2D depthTexture;\nuniform vec2 softParams;\nuniform vec4 projParams;\nvarying vec4 projPosition;\nvarying float linearDepth;\n#endif\n\n#ifdef USE_ALPHATEST\nuniform float alphaTest;\n#endif\n\nvoid main() {\n    vec4 baseColor = vColor;\n\n#ifdef USE_MAP\n    vec4 texColor = texture2D(map, vUV);\n    #ifdef TILE_BLEND\n        vec4 texColor2 = texture2D(map, vUV2);\n        texColor = mix(texColor, texColor2, vTileBlend);\n    #endif\n    baseColor *= texColor;\n#endif\n\n#ifdef USE_ALPHATEST\n    if (baseColor.a < alphaTest) discard;\n#else\n    if (baseColor.a < 0.01) discard;\n#endif\n\n    vec3 N = normalize(vNormal);\n    vec3 L = normalize(-lightDirection);\n    float NdotL = max(dot(N, L), 0.0);\n    vec3 litColor = ambientColor + lightColor * NdotL;\n\n    vec3 color = baseColor.rgb * litColor;\n\n#ifdef USE_ENVMAP_ATLAS\n    vec3 viewDir = normalize(vWorldPos - eyePosition);\n    vec3 reflectionCoords = reflect(viewDir, N);\n    color += sampleEnvAtlas(reflectionCoords) * reflectionLevel;\n#endif\n\n    gl_FragColor = vec4(color, baseColor.a);\n\n#ifdef SOFT_PARTICLES\n    vec2 p2 = projPosition.xy / projPosition.w;\n    p2 = 0.5 * p2 + 0.5;\n    float readDepth = texture2D(depthTexture, p2.xy).r;\n    float zNear = projParams.x;\n    float zFar = projParams.y;\n    float viewDepth = (zFar * zNear) / (zFar - readDepth * (zFar - zNear));\n    float fade = clamp(softParams.y * ((viewDepth - softParams.x) - linearDepth), 0.0, 1.0);\n    gl_FragColor *= fade;\n#endif\n}\n";
+declare const _default$4: string;
 
-declare const _default$3: "\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 float rotation;\nattribute float uvTile;\n\n// Uniforms\nuniform mat4 world;\nuniform mat4 view;\nuniform mat4 projection;\nuniform mat4 worldViewProjection;\n\n#ifdef UV_TILE\nuniform float tileCountX;\nuniform float tileCountY;\n#endif\n\n#ifdef PIVOT\n// Quad offset in particle-size units: xy in the quad's plane, z toward the camera.\nuniform vec3 pivot;\n#endif\n\n// Varyings\nvarying vec2 vUV;\nvarying vec4 vColor;\n#ifdef TILE_BLEND\nvarying vec2 vUV2;\nvarying float vTileBlend;\n#endif\n#ifdef SOFT_PARTICLES\nvarying vec4 projPosition;\nvarying float linearDepth;\n#endif\n\nvoid main() {\n    float c = cos(rotation);\n    float s = sin(rotation);\n\n    // A negative size mirrors the quad, which is how flipped particles arrive.\n    vec2 alignedPosition = position.xy * size.xy;\n#ifdef PIVOT\n    // The pivot turns with the particle but is not mirrored with it.\n    alignedPosition += pivot.xy * abs(size.xy);\n#endif\n    vec2 rotatedPosition;\n    rotatedPosition.x = c * alignedPosition.x - s * alignedPosition.y;\n    rotatedPosition.y = s * alignedPosition.x + c * alignedPosition.y;\n\n#ifdef HORIZONTAL\n    vec4 mvPosition = world * vec4(offset, 1.0);\n    mvPosition.x += rotatedPosition.x;\n    mvPosition.z -= rotatedPosition.y;\n#ifdef PIVOT\n    mvPosition.y += pivot.z * abs(size.x);\n#endif\n    mvPosition = view * mvPosition;\n#elif defined(VERTICAL)\n    vec4 mvPosition = world * vec4(offset, 1.0);\n    mvPosition.y += rotatedPosition.y;\n    mvPosition = view * mvPosition;\n    mvPosition.x += rotatedPosition.x;\n#else\n    vec4 mvPosition = view * world * vec4(offset, 1.0);\n    mvPosition.xy += rotatedPosition;\n#endif\n#ifdef PIVOT\n#ifndef HORIZONTAL\n    // Toward the camera along its view axis, whichever way the view space\n    // faces: anything in front of the camera has the sign of the far side.\n    mvPosition.z -= sign(mvPosition.z) * pivot.z * abs(size.x);\n#endif\n#endif\n\n    gl_Position = projection * mvPosition;\n#ifdef SOFT_PARTICLES\n    projPosition = gl_Position;\n    linearDepth = -mvPosition.z;\n#endif\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        #ifdef TILE_BLEND\n            float nextTile = ceil(uvTile);\n            float nextU = mod(nextTile, tc.x) / tc.x;\n            float nextV = 1.0 - floor(nextTile / tc.x) / tc.y - 1.0 / tc.y;\n            vUV2 = uv / tc + vec2(nextU, nextV);\n            vTileBlend = fract(uvTile);\n        #endif\n    #else\n        vUV = uv;\n    #endif\n\n    vColor = color;\n}\n";
+declare const _default$3: string;
 
-declare const _default$2: "\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 float rotation;\nattribute float uvTile;\nattribute vec4 velocity;\n\n// Uniforms\nuniform mat4 world;\nuniform mat4 view;\nuniform mat4 projection;\nuniform float speedFactor;\n\n#ifdef UV_TILE\nuniform float tileCountX;\nuniform float tileCountY;\n#endif\n\n#ifdef PIVOT\n// Streak offset in particle-size units: x from head to tail, y across.\nuniform vec3 pivot;\n#endif\n\n// Varyings\nvarying vec2 vUV;\nvarying vec4 vColor;\n#ifdef TILE_BLEND\nvarying vec2 vUV2;\nvarying float vTileBlend;\n#endif\n#ifdef SOFT_PARTICLES\nvarying vec4 projPosition;\nvarying float linearDepth;\n#endif\n\nvoid main() {\n    float lengthFactor = velocity.w;\n    // A flipped particle arrives with a negative size: the streak keeps its\n    // extent and mirrors its texture instead (see quadUV below).\n    float avgSize = (abs(size.x) + abs(size.y)) * 0.5;\n    vec4 mvPosition = view * world * vec4(offset, 1.0);\n    vec3 viewVelocity = mat3(view * world) * velocity.xyz;\n    float vlength = length(viewVelocity);\n    // Stretch direction is the velocity direction; only a genuinely motionless particle has none.\n    // Deriving it via normalize keeps the stretch aligned even when the speed contribution is ~0\n    // (e.g. speedFactor 0), instead of collapsing the whole burst onto a fixed screen axis.\n    vec3 vdir = vlength > 0.000001 ? viewVelocity / vlength : vec3(0.0, 0.0, 1.0);\n    vec3 side = normalize(cross(mvPosition.xyz, vdir));\n    mvPosition.xyz += position.y * side * avgSize;\n    // Equivalent to viewVelocity * (1.0 + lengthFactor / vlength) for moving particles, but the\n    // size-based term (vdir * lengthFactor) survives when the velocity contribution vanishes.\n    mvPosition.xyz -= (position.x + 0.5) * (viewVelocity + vdir * lengthFactor) * avgSize;\n#ifdef PIVOT\n    // In particle-size units along the quad's own axes: x from head to tail, y across.\n    mvPosition.xyz += (pivot.y * side - pivot.x * vdir) * avgSize;\n#endif\n    gl_Position = projection * mvPosition;\n    vec2 quadUV = vec2(size.x < 0.0 ? 1.0 - uv.x : uv.x, size.y < 0.0 ? 1.0 - uv.y : uv.y);\n#ifdef SOFT_PARTICLES\n    projPosition = gl_Position;\n    linearDepth = -mvPosition.z;\n#endif\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 = quadUV / tc + vec2(tileU, tileV);\n        #ifdef TILE_BLEND\n            float nextTile = ceil(uvTile);\n            float nextU = mod(nextTile, tc.x) / tc.x;\n            float nextV = 1.0 - floor(nextTile / tc.x) / tc.y - 1.0 / tc.y;\n            vUV2 = quadUV / tc + vec2(nextU, nextV);\n            vTileBlend = fract(uvTile);\n        #endif\n    #else\n        vUV = quadUV;\n    #endif\n\n    vColor = color;\n}\n";
+declare const _default$2: string;
 
-declare const _default$1: "\nvarying vec2 vUV;\nvarying vec4 vColor;\n\n#ifdef USE_MAP\nuniform sampler2D map;\n#endif\n\nvoid main() {\n    vec4 baseColor = vColor;\n\n#ifdef USE_MAP\n    vec4 texColor = texture2D(map, vUV);\n    baseColor *= texColor;\n#endif\n\n    if (baseColor.a < 0.01) discard;\n\n    gl_FragColor = baseColor;\n}\n";
+declare const _default$1: string;
 
-declare const _default: "\nattribute vec3 position;\nattribute vec3 previous;\nattribute vec3 next;\nattribute float side;\nattribute float width;\nattribute vec2 uv;\nattribute vec4 color;\n\nuniform mat4 view;\nuniform mat4 projection;\nuniform float lineWidth;\nuniform vec2 resolution;\nuniform float sizeAttenuation;\n\nvarying vec2 vUV;\nvarying vec4 vColor;\n\nvec2 fix(vec4 i, float aspect) {\n    vec2 res = i.xy / i.w;\n    res.x *= aspect;\n    return res;\n}\n\nvoid main() {\n    float aspect = resolution.x / resolution.y;\n    vec4 finalPosition = projection * view * vec4(position, 1.0);\n    vec4 prevPos = projection * view * vec4(previous, 1.0);\n    vec4 nextPos = projection * view * vec4(next, 1.0);\n\n    vec2 currentP = fix(finalPosition, aspect);\n    vec2 prevP = fix(prevPos, aspect);\n    vec2 nextP = fix(nextPos, aspect);\n\n    float w = lineWidth * width;\n    vec2 dir;\n    if (distance(nextP, currentP) < 0.0001) {\n        dir = normalize(currentP - prevP);\n    } else if (distance(prevP, currentP) < 0.0001) {\n        dir = normalize(nextP - currentP);\n    } else {\n        vec2 dir1 = normalize(currentP - prevP);\n        vec2 dir2 = normalize(nextP - currentP);\n        dir = normalize(dir1 + dir2);\n    }\n    vec4 normal = vec4(-dir.y, dir.x, 0.0, 1.0);\n    normal.xy *= 0.5 * w;\n    normal *= projection;\n    if (sizeAttenuation == 0.0) {\n        normal.xy *= finalPosition.w;\n        normal.xy /= (vec4(resolution, 0.0, 1.0) * projection).xy;\n    }\n    finalPosition.xy += normal.xy * side;\n    gl_Position = finalPosition;\n    vUV = uv;\n    vColor = color;\n}\n";
+declare const _default: string;
 
 declare class SpriteBatch extends VFXBatch {
     private static whiteTextureByScene;
@@ -3792,6 +4622,10 @@ declare class SpriteBatch extends VFXBatch {
     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;
@@ -3804,7 +4638,33 @@ declare class SpriteBatch extends VFXBatch {
     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_;
@@ -3838,6 +4698,23 @@ declare class SpriteBatch extends VFXBatch {
      * 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`.
@@ -3901,9 +4778,23 @@ declare class TrailBatch extends VFXBatch {
     private vector2_;
     private vector3_;
     private quaternion_;
-    /** Forces the emitter's world matrix to be current before sampling it. */
+    /**
+     * 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.
+     */
     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.
      *
@@ -3925,5 +4816,5 @@ declare class TrailBatch extends VFXBatch {
     dispose(): void;
 }
 
-export { ApplyCollision, ApplyForce, ApplySequences, AxisAngleGenerator, BatchedParticleRenderer, BatchedRenderer, BehaviorFromJSON, BehaviorTypes, Bezier, BoxEmitFrom, BoxEmitter, ChangeEmitDirection, CircleEmitter, ColorBySpeed, ColorGeneratorFromJSON, ColorOverLife, ColorRange, ConeEmitter, ConstantColor, ConstantValue, DEG2RAD, DonutEmitter, EdgeEmitter, EmitSubParticleSystem, EmitterFromJSON, EmitterMode, EmitterShapes, Euler, EulerGenerator, ForceOverLife, FrameOverLife, 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, RAD2DEG, RandomColor, RandomColorBetweenGradient, RandomQuatGenerator, RecordState, RectangleEmitter, RenderMode, Rotation3DOverLife, RotationBySpeed, RotationGeneratorFromJSON, RotationOverLife, SequencerFromJSON, ShapeTransform, SizeBySpeed, SizeOverLife, SpeedOverLife, SphereEmitter, SpriteBatch, SpriteParticle, SubParticleEmitMode, TextureSequencer, TrailBatch, TrailParticle, TurbulenceField, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, cubeFaceUrls, damp, degToRad, denormalize, ensureEnvAtlasFromCube, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, normalize, _default$5 as particleFragShader, _default$4 as particlePhysicsFragShader, _default$3 as particleVertShader, pingpong, planBehaviorFusion, radToDeg, randFloat, randFloatSpread, randInt, registerShaderChunks, seededRandom, setPhysicsResolver, setQuaternionFromProperEuler, smootherstep, smoothstep, _default$2 as stretchedBillboardVertShader, _default$1 as trailFragShader, _default as trailVertShader, unloadPlugin };
-export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, DonutEmitterParameters, EdgeEmitterParameters, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshSettings, ParameterPair, ParameterType, Particle, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, TrailSettings, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };
+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, 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, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, createSeededRandom, cubeFaceUrls, damp, defaultMeshLighting, degToRad, denormalize, ensureEnvAtlasFromCube, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRandomSource, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, meshRimEqual, normalize, normalizeMeshRim, _default$5 as particleFragShader, _default$4 as particlePhysicsFragShader, _default$3 as particleVertShader, pingpong, planBehaviorFusion, radToDeg, randFloat, randFloatSpread, randInt, random, registerShaderChunks, seededRandom, setPhysicsResolver, setQuaternionFromProperEuler, setRandomSource, smootherstep, smoothstep, _default$2 as stretchedBillboardVertShader, subEmitterInheritMask, _default$1 as trailFragShader, _default as trailVertShader, unloadPlugin, withRandomSource };
+export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, CullingMode, DonutEmitterParameters, EdgeEmitterParameters, EffectPoolOptions, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshLighting, MeshLightingSettings, MeshRim, MeshSettings, ParameterPair, ParameterType, Particle, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RandomSource, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SortMode, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, SubEmitterInheritance, TrailSettings, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };