babylon.quarks 0.20.0 → 0.23.0

package/dist/types/index.d.ts

@@ -2,6 +2,8 @@ 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 { 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 { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
 import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
@@ -366,6 +368,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 +669,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 +835,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 +941,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 +1001,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 +1031,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;
@@ -1384,10 +1478,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 +1542,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 +1634,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 +1720,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 +1921,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 +1956,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>;
 
@@ -1889,9 +2037,18 @@ declare class EmitSubParticleSystem implements Behavior {
     private v_;
     private v2_;
     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);
     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;
@@ -2023,6 +2180,15 @@ declare class Noise implements Behavior {
     duration: number;
     constructor(frequency: FunctionValueGenerator | ValueGenerator, power: FunctionValueGenerator | ValueGenerator, positionAmount?: FunctionValueGenerator | ValueGenerator, rotationAmount?: FunctionValueGenerator | ValueGenerator);
     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 +2256,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 +2395,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;
@@ -2268,13 +2448,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;
@@ -2954,6 +3150,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;
@@ -2980,6 +3226,10 @@ interface StoredBatchSettings {
     layerMask: number;
     /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
     pivot?: Vector3;
+    /** Mesh particle lighting, see {@link VFXBatchSettings.lighting}. */
+    lighting?: MeshLighting;
+    /** Mesh particle rim, see {@link VFXBatchSettings.rim}. */
+    rim?: MeshRim;
 }
 declare abstract class VFXBatch {
     mesh: Mesh;
@@ -2998,6 +3248,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;
@@ -3052,6 +3304,13 @@ interface VFXBatchSettings {
      * y across, and z is unused. Absent or zero: no offset. Meshes ignore it.
      */
     pivot?: Vector3;
+    /**
+     * 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,6 +3353,7 @@ declare class BatchedRenderer extends TransformNode {
     private static readonly EMPTY_BATCH_GRACE_FRAMES;
     private adaptivePerformanceState;
     private lastAppliedQuality;
+    private meshLighting;
     constructor(name: string, scene: Scene);
     private static clamp;
     private static equals;
@@ -3109,6 +3369,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;
@@ -3265,6 +3539,10 @@ 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>;
     scene?: Scene;
 }
 interface BurstParametersJSON {
@@ -3392,6 +3670,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 +3684,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);
@@ -3435,6 +3721,27 @@ declare class ParticleSystem implements IParticleSystem {
      */
     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 nonZeroPivot;
     private static nonZeroFlip;
     get softNearFade(): number;
@@ -3513,6 +3820,40 @@ declare class ParticleSystem implements IParticleSystem {
     /** Advances emission, behaviors, motion and culling by one fixed timestep. */
     private simulateStep;
     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?: {
@@ -3535,6 +3876,18 @@ declare class ParticleSystem implements IParticleSystem {
     clone(): ParticleSystem;
 }
 
+/** Kind of linked asset the loader asks a {@link QuarksResourceResolver} to handle. */
+type QuarksResourceKind = 'effect' | 'geometry' | 'image';
+/**
+ * Hooks for resolving relative source links (textures, geometry files) and loading their JSON.
+ * Omit either method to keep the default (`baseUrl` join / `fetch`).
+ */
+interface QuarksResourceResolver {
+    /** Resolve a relative url to an absolute / blob / data url. Default: {@link QuarksLoader.joinUrl}. */
+    resolve?(url: string, kind: QuarksResourceKind, baseUrl: string): string | Promise<string>;
+    /** Load a JSON asset (geometry files). Default: `fetch(resolvedUrl).json()`. */
+    fetchJson?(resolvedUrl: string): Promise<unknown>;
+}
 interface QuarksLoaderOptions {
     baseUrl?: string;
     /**
@@ -3546,19 +3899,96 @@ interface QuarksLoaderOptions {
      * change one effect's texture settings without touching the others.
      */
     shareResources?: boolean;
+    /** Custom url / fetch backend (File picker, CDN, IndexedDB). */
+    resolver?: QuarksResourceResolver;
+}
+/** One in-memory effect for {@link QuarksLoader.loadFromJSONAll}. */
+interface QuarksJSONLoadEntry {
+    json: unknown;
+    /** Overrides loader `baseUrl` for relative texture / geometry links in this effect. */
+    baseUrl?: string;
+}
+/**
+ * Options for {@link QuarksLoader.loadAll} / {@link QuarksLoader.loadFromJSONAll}.
+ * Batch loads share the per-scene fetch cache and `shareResources`, so N effects that point at
+ * the same `assets/geometries/*.json` or texture only pay for that asset once.
+ */
+interface QuarksBatchLoadOptions {
+    /**
+     * Max concurrent effect-document fetches (phase 1). Linked geometry/image resolve still runs
+     * across the whole pack in parallel so shared urls coalesce. Default: all at once.
+     */
+    concurrency?: number;
+    /**
+     * Called once per effect when it has fully settled (parsed successfully, or failed under
+     * `continueOnError`). `done` is how many of `total` have settled so far.
+     */
+    onProgress?: (done: number, total: number) => void;
+    /**
+     * When true, a failed effect becomes `null` in the result array and the rest keep loading.
+     * When false (default), the first failure rejects the whole batch.
+     */
+    continueOnError?: boolean;
 }
 declare class QuarksLoader {
     private scene;
     private options;
     constructor(scene: Scene, options?: QuarksLoaderOptions);
+    /** Fetches an effect JSON from `url`, resolves linked sources, and parses it. */
     load(url: string): Promise<TransformNode>;
+    /**
+     * Resolves linked geometry / image urls on `json` (via {@link resolveResources}) then parses.
+     * Use when the effect JSON is already in hand (File, CDN payload, editor import).
+     */
+    loadFromJSON(json: any, baseUrl?: string): Promise<TransformNode>;
+    /**
+     * Loads many effects in parallel for battle / level preload. Phase 1 fetches every effect
+     * JSON (optionally concurrency-limited); phase 2 resolves all linked geometries/images across
+     * the pack together so shared asset urls hit the fetch cache once; phase 3 parses.
+     *
+     * @example
+     * ```ts
+     * const roots = await loader.loadAll([
+     *   'fx/hit.json', 'fx/explosion.json', 'fx/heal.json',
+     * ], { concurrency: 6, continueOnError: true });
+     * ```
+     */
+    loadAll(urls: string[], options?: QuarksBatchLoadOptions & {
+        continueOnError?: false;
+    }): Promise<TransformNode[]>;
+    loadAll(urls: string[], options: QuarksBatchLoadOptions & {
+        continueOnError: true;
+    }): Promise<(TransformNode | null)[]>;
+    /**
+     * Same two-phase batch as {@link loadAll}, but effect JSON is already in memory (asset pack,
+     * IndexedDB, editor). Entries may be bare JSON or `{ json, baseUrl }`.
+     */
+    loadFromJSONAll(entries: Array<QuarksJSONLoadEntry | unknown>, options?: QuarksBatchLoadOptions & {
+        continueOnError?: false;
+    }): Promise<TransformNode[]>;
+    loadFromJSONAll(entries: Array<QuarksJSONLoadEntry | unknown>, options: QuarksBatchLoadOptions & {
+        continueOnError: true;
+    }): Promise<(TransformNode | null)[]>;
+    /**
+     * Inlines external geometry files and rewrites relative image urls through the loader's
+     * {@link QuarksResourceResolver}. Idempotent for already-inlined geometries. Failures warn
+     * and leave the entry as is.
+     */
+    resolveResources(json: any, baseUrl?: string): Promise<void>;
+    /**
+     * Same as instance {@link resolveResources}, but usable without constructing a loader (e.g.
+     * editor import that only prepares JSON). Pass `scene` to share the per-scene fetch cache.
+     */
+    static resolveLinkedResources(json: any, options?: {
+        baseUrl?: string;
+        resolver?: QuarksResourceResolver;
+        scene?: Scene;
+    }): Promise<void>;
     /**
      * Inlines geometries that an export wrote to their own file (`{uuid, type: 'QuarksGeometry',
-     * url}` — e.g. the Unity exporter's "geometries as files"): each `url` is passed to
-     * `loadGeometry`, and the `positions / indices / uvs / normals` it returns replace the url in
-     * place, so `parse()` (which is synchronous) sees an ordinary inline geometry. `load()` does
-     * this with `fetch`; call it yourself before `parse()` when the files come from elsewhere.
-     * A geometry that fails to load is left as is and warned about.
+     * url}`). Prefer {@link load}, {@link loadFromJSON}, or {@link resolveResources} — those use
+     * the loader's resolver and fetch cache. Kept for callers that already have a custom
+     * `loadGeometry` and no `QuarksLoader` instance.
      */
     static resolveExternalGeometries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void>;
     parse(json: any, baseUrl?: string): TransformNode;
@@ -3566,15 +3996,31 @@ declare class QuarksLoader {
     /** The scene's copy of an identical geometry when resources are shared, else `geometry` itself. */
     private share;
     /**
-     * Forgets the textures and geometries shared between loads into `scene` (see
-     * {@link QuarksLoaderOptions.shareResources}). Effects already loaded keep theirs; the next
-     * load creates new ones. Textures are not disposed — they may still be in use.
+     * Forgets the textures, geometries, and in-flight JSON fetches shared between loads into
+     * `scene` (see {@link QuarksLoaderOptions.shareResources}). Effects already loaded keep
+     * theirs; the next load creates new ones. Textures are not disposed — they may still be in use.
      */
     static clearSharedResources(scene: Scene): void;
+    /** Joins `baseUrl` with a relative `url`; leaves data/blob/absolute/root-absolute urls alone. */
+    static joinUrl(baseUrl: string, url: string): string;
     private parseSphereGeometry;
     private parseBufferGeometry;
     private extractInterleavedAttribute;
     private int32ArrayToFloat32;
+    private resolveResourceUrl;
+    /** Fetches one effect JSON; documents are not fetch-cached because resolve mutates them. */
+    private fetchEffectDocument;
+    /**
+     * Resolve every document's linked resources in parallel (shared urls coalesce via the
+     * scene fetch cache), then parse. Each index settles exactly once for `onProgress`.
+     */
+    private loadDocuments;
+    /** Runs `fn` over `items` with at most `concurrency` in flight (or all if unset/≤0). */
+    private static mapPool;
+    private static resolveWith;
+    /** One in-flight fetch per scene + resolved url when `scene` is set; otherwise uncached. */
+    private static fetchJsonWith;
+    private static inlineGeometryEntries;
     private parseImages;
     /**
      * Flags an image entry that is plainly not an image, which otherwise only
@@ -3586,13 +4032,6 @@ declare class QuarksLoader {
      * file backs.
      */
     private static warnIfNotAnImageUrl;
-    /**
-     * `img.url` is already absolute for data/blob URIs and full http(s) URLs — common for
-     * "portable" exports that embed textures as base64 (see ensurePortableTextureUrl in
-     * babylon.quarks-editor). Prepending baseUrl to those turns e.g.
-     * "data:image/png;base64,AAAA" into an invalid path like "/some/dir/data:image/png;base64,AAAA".
-     */
-    private static resolveUrl;
     private parseTextures;
     private mapWrapMode;
     private parseMaterials;
@@ -3672,7 +4111,7 @@ declare const _default$6: "\n// Per-vertex attributes\nattribute vec3 position;\
 
 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$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: "\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$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";
 
@@ -3694,6 +4133,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;
@@ -3707,6 +4150,18 @@ declare class SpriteBatch extends VFXBatch {
     private buildExpandableBuffers;
     expandBuffers(target: number): void;
     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_;
@@ -3740,6 +4195,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`.
@@ -3803,7 +4275,15 @@ 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;
     /**
@@ -3827,5 +4307,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, QuarksLoaderOptions, 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, 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 };