babylon.quarks 0.23.0 → 0.24.1

package/dist/types/index.d.ts

@@ -2,12 +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;
@@ -1047,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 {
 }
@@ -2023,15 +2028,33 @@ 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_;
@@ -2039,7 +2062,14 @@ declare class EmitSubParticleSystem implements Behavior {
     private subEmissions;
     /** 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);
+    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;
     /**
@@ -2055,6 +2085,7 @@ declare class EmitSubParticleSystem implements Behavior {
     static fromJSON(json: any, particleSystem: IParticleSystem): Behavior;
     clone(): Behavior;
     reset(): void;
+    private static validInherit;
     private setMatrixFromParticle;
 }
 
@@ -2176,9 +2207,38 @@ 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};
@@ -2417,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;
@@ -2437,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;
@@ -3142,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,
@@ -3224,8 +3338,18 @@ 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}. */
@@ -3237,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;
     /**
@@ -3296,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
@@ -3304,6 +3467,20 @@ 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.
@@ -3354,7 +3531,43 @@ declare class BatchedRenderer extends TransformNode {
     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;
@@ -3416,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. */
@@ -3491,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;
@@ -3543,6 +3830,24 @@ interface ParticleSystemParameters {
     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 {
@@ -3574,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;
@@ -3697,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;
@@ -3719,6 +4046,29 @@ 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);
     /**
@@ -3742,6 +4092,8 @@ declare class ParticleSystem implements IParticleSystem {
     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;
@@ -3756,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;
@@ -3772,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
@@ -3817,8 +4290,12 @@ 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;
@@ -4096,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;
 }
 
@@ -4105,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\n#ifndef MESH_UNLIT\nuniform vec3 lightDirection;\nuniform vec3 lightColor;\nuniform vec3 ambientColor;\n#endif\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#if defined(USE_ENVMAP_ATLAS) || defined(MESH_RIM)\nuniform vec3 eyePosition;\n#endif\n\n#ifdef MESH_RIM\nuniform vec3 rimColor;\nuniform vec2 rimParams;\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 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#ifdef MESH_UNLIT\n    vec3 color = baseColor.rgb;\n#else\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#endif\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#ifdef MESH_RIM\n    // Fresnel: strongest where the surface turns away from the camera.\n    vec3 V = normalize(eyePosition - vWorldPos);\n    float rim = pow(1.0 - abs(dot(N, V)), rimParams.x) * rimParams.y;\n    #ifdef MESH_RIM_MIX\n    color = mix(color, rimColor, clamp(rim, 0.0, 1.0));\n    #else\n    color += rimColor * rim;\n    #endif\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;
@@ -4149,6 +4638,20 @@ 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;
@@ -4286,6 +4789,12 @@ declare class TrailBatch extends VFXBatch {
      */
     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.
      *
@@ -4307,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, QuaternionView, 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, defaultMeshLighting, degToRad, denormalize, ensureEnvAtlasFromCube, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, 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, 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, MeshLighting, MeshLightingSettings, MeshRim, 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 };