babylon.quarks 0.24.1 → 0.26.0

package/dist/types/index.d.ts

@@ -1121,6 +1121,18 @@ interface TrailSettings {
      * @type {boolean}
      */
     recordWorldSpace?: boolean;
+    /**
+     * Sweep the ribbon along this axis of the emitter instead of turning it to
+     * face the camera: every sample records the axis as the emitter held it,
+     * and the ribbon spans the particle's width along it, centred on the
+     * particle. With the emitter on a blade, the axis along the blade and the
+     * width the blade's length, the trail is the surface the blade swept, as a
+     * weapon trail (Unreal's AnimTrail) is. The emitter's scale applies to the
+     * width, and so does the axis's length: give a unit vector for the width
+     * as set. Unset (the default): a camera-facing ribbon.
+     * @type {Vector3}
+     */
+    sideAxis?: Vector3;
 }
 interface MeshSettings {
     /**
@@ -1182,6 +1194,14 @@ interface IParticleSystem {
      * @type {number}
      */
     simulationStep?: number;
+    /**
+     * What world-space forces and speed limits are multiplied by: the
+     * emitter's world scale when the system scales its motion with it (a
+     * world-space system in `'hierarchy'` scaling mode), 1 or undefined
+     * otherwise.
+     * @type {number}
+     */
+    motionScale?: number;
     /**
      * Whether this system only emits through another system, which is when its
      * particles carry their own parent transform.
@@ -1752,6 +1772,12 @@ declare class TrailParticle implements Particle {
     headWidthScale: number;
     /** Ring buffer of recorded colors, 4 floats per sample. */
     historyColors: Float32Array;
+    /**
+     * Ring buffer of recorded side vectors, 3 floats per sample, in the space
+     * the positions are recorded in. Empty unless the trail is swept along an
+     * axis (`TrailSettings.sideAxis`); see {@link ensureSideHistory}.
+     */
+    historySides: Float32Array;
     /** Number of samples the ring buffers can hold. */
     historyCapacity: number;
     /** Slot the next sample is written to. */
@@ -1776,6 +1802,8 @@ declare class TrailParticle implements Particle {
      * @param {number} capacity - Number of samples to hold.
      */
     ensureHistoryCapacity(capacity: number): void;
+    /** Allocates {@link historySides} for the current capacity, once a trail is swept. */
+    ensureSideHistory(): void;
     /** Drops every recorded sample without releasing the buffers. */
     resetHistory(): void;
     /**
@@ -2114,17 +2142,82 @@ declare class ForceOverLife implements Behavior {
 }
 
 /**
- * apply tile number of particle texture by particles' life.
+ * How {@link FrameOverLife} plays the sheet, beyond sampling `frame` over the
+ * particle's life. Every field is optional, and leaving them all out keeps the
+ * plain life-fraction behaviour.
+ */
+interface FrameOverLifeOptions {
+    /**
+     * Frames per second. Above zero the sheet plays by the particle's age in
+     * seconds instead of its life fraction, Unity's "FPS" time mode: `frame`
+     * then gives the first frame of the segment, and the frame advances by one
+     * every `1 / fps` seconds. Needs {@link frameCount}.
+     */
+    fps?: number;
+    /**
+     * Life mode only: how many times `frame` plays over the particle's life
+     * (Unity's "Cycles"). Default 1.
+     */
+    cycles?: number;
+    /**
+     * Frames in the segment that plays, from the first frame. In FPS mode the
+     * frame wraps (or holds, see {@link loop}) at it, counted from `frame`;
+     * in life mode the curve plus a {@link startFrame} offset wraps into
+     * `[0, frameCount)`, so the curve should start at frame 0. 0, the default,
+     * means no segment.
+     */
+    frameCount?: number;
+    /** FPS mode: wrap back to the first frame of the segment (default) or hold its last. */
+    loop?: boolean;
+    /**
+     * FPS mode: every `1 / fps` seconds show a random frame of the segment
+     * instead of the next one, each particle its own sequence: the flicker of
+     * lightning, sparks or a neon sign. Needs {@link frameCount}; `loop` does
+     * not apply. Default false.
+     */
+    random?: boolean;
+    /**
+     * Per-particle frame offset, sampled once at birth: an `IntervalValue(0, n)`
+     * starts each particle on a random frame (Unity's "Start Frame"). Default none.
+     */
+    startFrame?: ValueGenerator;
+}
+/**
+ * Sets the particle's texture tile (`uvTile`) over its life.
+ *
+ * By default `frame` is sampled at the particle's life fraction. The
+ * {@link FrameOverLifeOptions} add the rest of Unity's texture sheet
+ * animation: playing at a fixed frame rate, several cycles per life, a frame
+ * segment that loops or holds, a random start frame, and a random frame on
+ * every tick.
  */
 declare class FrameOverLife implements Behavior {
     type: string;
     private _frame;
-    constructor(frame: FunctionValueGenerator | ValueGenerator);
+    fps: number;
+    cycles: number;
+    frameCount: number;
+    loop: boolean;
+    random: boolean;
+    startFrame?: ValueGenerator;
+    /** A per-particle sample that sets each particle's random sequence apart. */
+    private readonly salt;
+    constructor(frame: FunctionValueGenerator | ValueGenerator, options?: FrameOverLifeOptions);
     get frame(): FunctionValueGenerator | ValueGenerator;
     set frame(frame: FunctionValueGenerator | ValueGenerator);
+    /** True when no option is in play and the frame is just `frame` at the life fraction. */
+    isPlain(): boolean;
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
+    /** The tile for `particle` at `age` seconds, `t` being that age over its life. */
+    frameAt(particle: Particle, age: number, t: number): number;
+    private offset;
+    /** The particle's salt; 0 for a particle born before this behaviour was added. */
+    private saltOf;
+    /** A stable pseudo-random number in [0, 1) for a tick of a particle's sequence. */
+    private static hash;
+    private static wrap;
     private sampleFrame;
     frameUpdate(delta: number): void;
     toJSON(): any;
@@ -2188,7 +2281,11 @@ declare class LimitSpeedOverLife implements Behavior {
     speed: FunctionValueGenerator;
     dampen: number;
     type: string;
-    initialize(particle: Particle): void;
+    /** Learned in {@link initialize}; its motion scale multiplies the limit of a world-space system. */
+    ps?: IParticleSystem;
+    initialize(particle: Particle, particleSystem?: IParticleSystem): void;
+    /** What the limit is multiplied by: the system's motion scale in world space, else 1. */
+    motionScale(): number;
     constructor(speed: FunctionValueGenerator, dampen: number);
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
@@ -3262,7 +3359,14 @@ declare enum RenderMode {
     Mesh = 2,
     Trail = 3,
     HorizontalBillBoard = 4,
-    VerticalBillBoard = 5
+    VerticalBillBoard = 5,
+    /**
+     * A quad laid from each particle to the system's {@link ParticleSystem.beamEnd}
+     * and turned about its length to face the camera (a line renderer): U runs
+     * from the particle (0) to the end (1), V across, the particle's size is
+     * the width. Lightning, tethers, lasers.
+     */
+    Beam = 6
 }
 /**
  * How mesh particles are lit.
@@ -3303,9 +3407,12 @@ interface MeshRim {
     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).
+     * surface toward it, for an outline (a dark ink line with a dark colour);
+     * `'fade'` leaves the colour and fades the faces turned to the camera by
+     * `strength` instead, alpha times `1 - strength * (1 - edge)`: a wall of
+     * light that reads thick along its silhouette and thin across its face.
      */
-    mode: 'add' | 'mix';
+    mode: 'add' | 'mix' | 'fade';
 }
 /**
  * A complete rim from a partial one, every field defaulted and kept in range,
@@ -3314,10 +3421,165 @@ interface MeshRim {
 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;
+/**
+ * Which texture coordinates a texture is sampled with, as Unity's UV channels
+ * and Niagara's ribbon UV0 / UV1:
+ *
+ * - `0`: the particle's first UV, with the sprite sheet's cell applied: on a
+ *   sheet the current frame's cell, on a trail the cell's stretch along it, on
+ *   a mesh its first UV set. Read before the map's own layout and distortion,
+ *   so a texture on it does not move with them.
+ * - `1`: the particle's own UV, never moved by the sheet. The whole quad on a
+ *   billboard, a stretched billboard or a beam (mirrored with the quad when it
+ *   flips); on a trail U along it the way the map's runs (from the tail, or
+ *   from the head with `uvFromHead`) and V across it; on a mesh its second UV
+ *   set (`instancingUVs2`), or its first when it has none.
+ *
+ * A mesh can then repeat its picture along UV0 while a mask on UV1 runs once
+ * across its whole length, as a lightmap UV does in a game engine.
+ */
+type UVChannel = 0 | 1;
+/**
+ * How a texture is laid over the particle: its UV channel, then tiling and
+ * offset as in Unity's material Tiling / Offset, then a scroll on the
+ * renderer's clock as Unreal's Panner. Sampled at
+ * `uv(channel) * tiling + offset + scroll * time`; the offset is used as
+ * given, so a clamped texture can be moved off its edge, and only the
+ * scroll's share is wrapped (over two repeats, so a mirrored texture stays
+ * seamless). A texture that scrolls or tiles should repeat.
+ */
+interface TextureUV {
+    /** See {@link UVChannel}. Default 0. */
+    channel: UVChannel;
+    /** Repeats across the channel's 0…1, `[u, v]`. Default `[1, 1]`. */
+    tiling: [number, number];
+    /** Added after tiling, in texture UV units. Default `[0, 0]`. */
+    offset: [number, number];
+    /** UV units per second on the renderer's clock. Default `[0, 0]`. */
+    scroll: [number, number];
+}
+/** A complete {@link TextureUV} from a partial one, with `defaults` under the fields left out. */
+declare function normalizeTextureUV(uv: Partial<TextureUV> | null | undefined, defaults?: Partial<TextureUV>): TextureUV;
+/** True when both lay a texture the same way. */
+declare function textureUVEqual(a: TextureUV, b: TextureUV): boolean;
+/** The fields of `uv` that differ from `defaults`, for JSON written only when set. */
+declare function textureUVToJSON(uv: TextureUV, defaults?: Partial<TextureUV>): Partial<TextureUV> | undefined;
+/**
+ * Which value of the map's texel picks the colour along a gradient map's
+ * ramp: one channel, so a texture can pack several masks (Unreal's and
+ * Unity's channel-packed textures), or the Rec. 709 luminance of its colour.
+ */
+type GradientMapChannel = 'r' | 'g' | 'b' | 'a' | 'luminance';
+/**
+ * A gradient map (colour ramp): the map is recoloured by looking its
+ * {@link channel} up along U of {@link ramp}. See
+ * {@link VFXBatchSettings.gradientMap}.
+ */
+interface ParticleGradientMap {
+    /**
+     * The ramp, read along U at mid V: low values on the left. Make it without
+     * mipmaps and clamped. Required: without one there is no gradient map.
+     */
+    ramp: BaseTexture | null;
+    /**
+     * The texel value the ramp is looked up by. Default `'r'`. With `'a'` the
+     * ramp's alpha becomes the texel's alpha, so a soft shape can glow at its
+     * fringe and stay solid at its heart; with any other channel the ramp's
+     * alpha multiplies the map's.
+     */
+    channel: GradientMapChannel;
+}
+/** The weights a texel is dotted with to look up the ramp, per {@link GradientMapChannel}. */
+declare const GRADIENT_MAP_WEIGHTS: Readonly<Record<GradientMapChannel, readonly [number, number, number, number]>>;
+/** A complete gradient map, or undefined when unset or without a ramp. */
+declare function normalizeGradientMap(gradientMap: Partial<ParticleGradientMap> | null | undefined): ParticleGradientMap | undefined;
+/** True when both recolour the same way (or both not at all). */
+declare function gradientMapEqual(a: ParticleGradientMap | undefined, b: ParticleGradientMap | undefined): boolean;
+/**
+ * Alpha erosion: the particle's alpha decides how much of its shape is left
+ * instead of how transparent it is, so `ColorOverLife` fading alpha out
+ * dissolves (noise mask) or wipes (gradient mask) the shape away. See
+ * {@link VFXBatchSettings.erosion}.
+ */
+interface ParticleErosion {
+    /**
+     * Mask whose red channel orders what goes first, laid by {@link maskUV}.
+     * Null: the map's own alpha, so a soft shape shrinks from its edges.
+     */
+    mask: BaseTexture | null;
+    /**
+     * How the mask is laid over the particle, see {@link TextureUV}. On UV
+     * channel 1 a gradient mask wipes a whole trail or mesh however its map
+     * repeats. Default channel 0, untiled, still.
+     */
+    maskUV: TextureUV;
+    /** Width of the soft transition at the cut, in mask units. Default 0.05. */
+    softness: number;
+    /** Width of the glowing band above the cut, in mask units; 0 (default) draws none. */
+    edgeWidth: number;
+    /** Colour added in the edge band, linear RGB, may exceed 1. Default `[1, 1, 1]`. */
+    edgeColor: [number, number, number];
+}
+/** {@link ParticleErosion} as given: any field may be left out, the mask's layout too. */
+type ParticleErosionOptions = Partial<Omit<ParticleErosion, 'maskUV'>> & {
+    maskUV?: Partial<TextureUV>;
+};
+/** A complete erosion from a partial one, every field defaulted, or undefined when `erosion` is unset. */
+declare function normalizeErosion(erosion: ParticleErosionOptions | null | undefined): ParticleErosion | undefined;
+/** True when both describe the same erosion (or both none). */
+declare function erosionEqual(a: ParticleErosion | undefined, b: ParticleErosion | undefined): boolean;
+/** The distortion noise's default layout: drifting up half a repeat a second. */
+declare const UV_DISTORTION_DEFAULT_UV: Partial<TextureUV>;
+/**
+ * UV distortion: the map's UV pushed about by a noise texture, for heat
+ * shimmer, licking flames and breathing auras. See
+ * {@link VFXBatchSettings.uvDistortion}.
+ */
+interface ParticleUVDistortion {
+    /**
+     * Noise whose red and green channels, around 0.5, push U and V. It should
+     * wrap (repeat). Required: without one there is no distortion.
+     */
+    map: BaseTexture | null;
+    /**
+     * How the noise is laid over the particle, see {@link TextureUV}. Default
+     * channel 0, untiled, scrolling `[0, 0.5]`.
+     */
+    mapUV: TextureUV;
+    /** How far the map's UV is pushed at most, in UV units. Default 0.05. */
+    strength: number;
+}
+/** {@link ParticleUVDistortion} as given: any field may be left out, the noise's layout too. */
+type ParticleUVDistortionOptions = Partial<Omit<ParticleUVDistortion, 'mapUV'>> & {
+    mapUV?: Partial<TextureUV>;
+};
+/** A complete distortion from a partial one, or undefined when unset or without a map. */
+declare function normalizeUVDistortion(distortion: ParticleUVDistortionOptions | null | undefined): ParticleUVDistortion | undefined;
+/** True when both describe the same distortion (or both none). */
+declare function uvDistortionEqual(a: ParticleUVDistortion | undefined, b: ParticleUVDistortion | undefined): boolean;
+/**
+ * The main map's layout, or undefined when it is the identity (channel 0,
+ * untiled, unmoved, still), which costs nothing in the shader.
+ */
+declare function normalizeMapUV(uv: Partial<TextureUV> | null | undefined): TextureUV | undefined;
+/** True when both lay the map the same way (or both as drawn). */
+declare function mapUVEqual(a: TextureUV | undefined, b: TextureUV | undefined): boolean;
+/**
+ * True when a texture effect of `settings` samples UV channel 1, see
+ * {@link UVChannel}: the map, the distortion noise or an erosion mask laid
+ * on it.
+ */
+declare function readsUV1(settings: {
+    mapUV?: TextureUV;
+    uvDistortion?: ParticleUVDistortion;
+    erosion?: ParticleErosion;
+}): boolean;
 interface StoredBatchSettings {
     instancingGeometry: Float32Array;
     instancingIndices: Uint32Array | Uint16Array;
     instancingUVs?: Float32Array;
+    /** The mesh's second UV set, see {@link UVChannel}. */
+    instancingUVs2?: Float32Array;
     instancingNormals?: Float32Array;
     renderMode: RenderMode;
     renderOrder: number;
@@ -3354,6 +3616,14 @@ interface StoredBatchSettings {
     lighting?: MeshLighting;
     /** Mesh particle rim, see {@link VFXBatchSettings.rim}. */
     rim?: MeshRim;
+    /** The main map's layout, see {@link VFXBatchSettings.mapUV}. */
+    mapUV?: TextureUV;
+    /** Map UV distortion, see {@link VFXBatchSettings.uvDistortion}. */
+    uvDistortion?: ParticleUVDistortion;
+    /** Colour ramp for the map, see {@link VFXBatchSettings.gradientMap}. */
+    gradientMap?: ParticleGradientMap;
+    /** Alpha erosion, see {@link VFXBatchSettings.erosion}. */
+    erosion?: ParticleErosion;
 }
 declare abstract class VFXBatch {
     mesh: Mesh;
@@ -3391,6 +3661,19 @@ declare abstract class VFXBatch {
     protected static readonly FOG_UNIFORMS: string[];
     protected fogDefines(): string[];
     protected bindFog(material: ShaderMaterial): void;
+    /**
+     * Seconds of renderer time, set by the renderer before each fill; what UV
+     * and erosion mask scrolling advance by.
+     */
+    time: number;
+    /** True when a texture effect of this batch samples UV channel 1, see {@link UVChannel}. */
+    protected usesUV1(): boolean;
+    /** Defines of the texture effects (see `shaders/chunks/surface.ts`) this batch uses. */
+    protected surfaceDefines(): string[];
+    /** Adds the uniforms and samplers of the texture effects this batch uses. */
+    protected surfaceUniforms(uniforms: string[], samplers: string[]): void;
+    /** Sets the texture effects' textures and constants, and advances their scrolling on every bind. */
+    protected bindSurface(material: ShaderMaterial): void;
     addSystem(system: IParticleSystem): void;
     removeSystem(system: IParticleSystem): void;
     /**
@@ -3413,6 +3696,8 @@ interface VFXBatchSettings {
     instancingGeometry: Float32Array;
     instancingIndices: Uint32Array | Uint16Array;
     instancingUVs?: Float32Array;
+    /** The mesh's second UV set, see {@link UVChannel}. */
+    instancingUVs2?: Float32Array;
     instancingNormals?: Float32Array;
     renderMode: RenderMode;
     renderOrder: number;
@@ -3488,6 +3773,14 @@ interface VFXBatchSettings {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles; unset draws none. See {@link MeshRim}. */
     rim?: MeshRim;
+    /** How the main map is laid over the particle, see {@link TextureUV}. Unset: as drawn. Systems that differ are batched apart. */
+    mapUV?: TextureUV;
+    /** Colour ramp the map is recoloured through, see {@link ParticleGradientMap}. Unset: none. Systems that differ are batched apart. */
+    gradientMap?: ParticleGradientMap;
+    /** Map UV distortion by a noise texture, see {@link ParticleUVDistortion}. Unset: none. Systems that differ are batched apart. */
+    uvDistortion?: ParticleUVDistortion;
+    /** Alpha erosion (dissolve / wipe), see {@link ParticleErosion}. Unset: none. Systems that differ are batched apart. */
+    erosion?: ParticleErosion;
 }
 interface AdaptivePerformanceOptions {
     targetFrameMs: number;
@@ -3503,6 +3796,8 @@ interface AdaptivePerformanceState extends AdaptivePerformanceOptions {
 }
 declare class BatchedRenderer extends TransformNode {
     batches: Array<VFXBatch>;
+    /** Seconds this renderer has been updated for; the clock UV and erosion scrolling run on. */
+    private elapsed;
     systemToBatchIndex: Map<IParticleSystem, number>;
     depthTexture: BaseTexture | null;
     /** Systems in insertion order — iterated every frame, unlike the map. */
@@ -3778,6 +4073,35 @@ interface BurstParameters {
  * culled either; its parent decides.
  */
 type CullingMode = 'always' | 'pause' | 'pauseAndCatchUp';
+/**
+ * What the emitter's world scale does to a world-space system (Unity's
+ * Scaling Mode, as far as it differs here). A local-space system lives in its
+ * emitter's space, so its scale reaches everything either way.
+ *
+ * - `'shape'` (default): the scale sizes the emission shape and the
+ *   particles; speeds, forces and speed limits stay in world units, so a
+ *   scaled-down effect moves as far as the full-size one.
+ * - `'hierarchy'`: the scale also multiplies start speeds (per axis),
+ *   `ForceOverLife` and `LimitSpeedOverLife` (by the mean of the axes), so the
+ *   whole effect, motion included, scales like a model would.
+ */
+type ScalingMode = 'shape' | 'hierarchy';
+/**
+ * Where a {@link RenderMode.Beam} system's quads end: a point in world space,
+ * or anything with a world position, such as a Babylon `TransformNode`, read
+ * every frame.
+ */
+type BeamEnd = {
+    x: number;
+    y: number;
+    z: number;
+} | {
+    getAbsolutePosition(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
 interface ParticleSystemParameters {
     autoDestroy?: boolean;
     looping?: boolean;
@@ -3801,6 +4125,12 @@ interface ParticleSystemParameters {
     instancingGeometry?: Float32Array;
     instancingIndices?: Uint32Array | Uint16Array;
     instancingUVs?: Float32Array;
+    /**
+     * A second UV set for the mesh (glTF `TEXCOORD_1`, Unity's `uv2`), what
+     * textures on UV channel 1 read on a mesh particle; see `UVChannel`.
+     * Default none: channel 1 reads the first set.
+     */
+    instancingUVs2?: Float32Array;
     instancingNormals?: Float32Array;
     renderMode?: RenderMode;
     rendererEmitterSettings?: RendererEmitterSettings;
@@ -3830,10 +4160,20 @@ interface ParticleSystemParameters {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles, see {@link ParticleSystem.rim}. Default none. */
     rim?: Partial<MeshRim>;
+    /** The main map's layout, see {@link ParticleSystem.mapUV}. Default as drawn. */
+    mapUV?: Partial<TextureUV>;
+    /** Colour ramp for the map, see {@link ParticleSystem.gradientMap}. Default none. */
+    gradientMap?: Partial<ParticleGradientMap>;
+    /** Alpha erosion, see {@link ParticleSystem.erosion}. Default none. */
+    erosion?: ParticleErosionOptions;
+    /** Map UV distortion, see {@link ParticleSystem.uvDistortion}. Default none. */
+    uvDistortion?: ParticleUVDistortionOptions;
     /** 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;
+    /** What the emitter's scale does to a world-space system, see {@link ScalingMode}. Default `'shape'`. */
+    scalingMode?: ScalingMode;
     /** 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'`. */
@@ -3887,6 +4227,8 @@ interface ParticleSystemJSONParameters {
     playbackSpeed?: number;
     /** Written only when not `'always'`. */
     cullingMode?: CullingMode;
+    /** Written only when not `'shape'`. */
+    scalingMode?: ScalingMode;
     /** Written only when set. */
     seed?: number;
     /** Written only when not `'none'`. */
@@ -4090,6 +4432,58 @@ declare class ParticleSystem implements IParticleSystem {
      */
     get rim(): MeshRim | undefined;
     set rim(rim: Partial<MeshRim> | undefined);
+    /**
+     * How the main map is laid over the particle, see {@link TextureUV}: its
+     * UV channel, tiling and offset (Unity's Tiling / Offset) and a scroll on
+     * the renderer's clock (Unreal's Panner), for flowing energy, lava or a
+     * smear running along a mesh. A scrolled or tiled map should repeat. On a
+     * sprite sheet (UV channel 0) the layout applies to the sheet's UV, so a
+     * scroll or tiling there runs into the neighbouring cells. Undefined (the
+     * default), or the identity: the map as drawn. Fields left out take their
+     * defaults; assign a new object to change it. Saved with the material in
+     * the effect JSON.
+     */
+    get mapUV(): TextureUV | undefined;
+    set mapUV(uv: Partial<TextureUV> | undefined);
+    /**
+     * Colour ramp the map is recoloured through (a gradient map), see
+     * {@link ParticleGradientMap}: a channel of the map, or its luminance,
+     * picks a colour along U of the ramp; the particle colour still tints the
+     * result. One greyscale or channel-packed texture then serves every
+     * palette. Undefined (the default), or without a ramp: none. Assign a new
+     * object to change it. Saved with the material in the effect JSON.
+     */
+    get gradientMap(): ParticleGradientMap | undefined;
+    set gradientMap(gradientMap: Partial<ParticleGradientMap> | undefined);
+    /**
+     * Alpha erosion, see {@link ParticleErosion}: the particle's alpha decides
+     * how much of the shape is left rather than how transparent it is, so a
+     * `ColorOverLife` alpha curve dissolves the shape through a noise mask or
+     * wipes it through a gradient one — and an effect told to stop can fade
+     * out that way. Undefined (the default): alpha is plain transparency.
+     * Fields left out take their defaults; assign a new object to change it.
+     * Saved with the material in the effect JSON.
+     */
+    get erosion(): ParticleErosion | undefined;
+    set erosion(erosion: ParticleErosionOptions | undefined);
+    /**
+     * Map UV distortion, see {@link ParticleUVDistortion}: a scrolling noise
+     * texture pushes the map's UV about, for heat shimmer and licking,
+     * breathing shapes. Undefined (the default), or without a map: none.
+     * Fields left out take their defaults; assign a new object to change it.
+     * Saved with the material in the effect JSON.
+     */
+    get uvDistortion(): ParticleUVDistortion | undefined;
+    set uvDistortion(distortion: ParticleUVDistortionOptions | undefined);
+    /**
+     * The emitter's world scale per axis, measured with {@link motionScale}
+     * before every step; what `'hierarchy'` multiplies start speeds by. Taken
+     * from the system's own emitter rather than the emission matrix, whose
+     * columns carry a parent particle's velocity for a sub emitter.
+     */
+    private readonly hierarchyScale;
+    /** The mean world scale of the emitter for a world-space `'hierarchy'` system, else 1. */
+    private measureMotionScale;
     /** `lighting` if it is one of the modes, else the default. */
     private static validLighting;
     private static validSortMode;
@@ -4101,7 +4495,19 @@ declare class ParticleSystem implements IParticleSystem {
     get softFarFade(): number;
     set softFarFade(v: number);
     get instancingGeometry(): Float32Array;
+    /**
+     * The mesh particles' positions. A new geometry with a different vertex
+     * count drops UV sets and normals that no longer fit it: the first UV set
+     * falls back to zeros, the second to none, the normals to +Z. Assign {@link instancingUVs} and
+     * {@link instancingUVs2} after it.
+     */
     set instancingGeometry(geometry: Float32Array);
+    /** The mesh particles' first UV set, two values per vertex. */
+    get instancingUVs(): Float32Array;
+    set instancingUVs(uvs: Float32Array);
+    /** The mesh particles' second UV set, read by textures on UV channel 1; see `UVChannel`. */
+    get instancingUVs2(): Float32Array | undefined;
+    set instancingUVs2(uvs: Float32Array | undefined);
     get blending(): number;
     set blending(blending: number);
     get renderMode(): RenderMode;
@@ -4128,8 +4534,24 @@ declare class ParticleSystem implements IParticleSystem {
      * renderer. 1 by default; saved in the effect JSON only when it differs.
      */
     playbackSpeed: number;
+    /**
+     * Runtime multiplier on how many particles the system emits: bursts,
+     * emission over time and over distance alike. Unlike
+     * {@link setQualityFactor}, which only ever thins an effect, it may go
+     * above 1 to make a stronger version of the same effect. The two multiply.
+     * 1 by default; not saved in the effect JSON.
+     */
+    emissionMultiplier: number;
     /** What this system does while off screen, see {@link CullingMode}. `'always'` by default. */
     cullingMode: CullingMode;
+    /** What the emitter's world scale does to a world-space system, see {@link ScalingMode}. `'shape'` by default. */
+    scalingMode: ScalingMode;
+    /**
+     * What world-space forces and speed limits are multiplied by this step:
+     * the mean of the emitter's world scale axes in `'hierarchy'` mode, 1
+     * otherwise. Updated before every simulation step.
+     */
+    motionScale: number;
     /**
      * 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
@@ -4195,6 +4617,8 @@ declare class ParticleSystem implements IParticleSystem {
     play(): void;
     stop(): void;
     setQualityFactor(qualityFactor: number): void;
+    /** Quality factor times {@link emissionMultiplier}: what emission counts are scaled by. */
+    private emissionFactor;
     /**
      * Appends one particle to the pool, giving it the next row of the store.
      *
@@ -4245,6 +4669,30 @@ declare class ParticleSystem implements IParticleSystem {
      * frame behind the display.
      */
     getWorldBounds(min: Vector3, max: Vector3): boolean;
+    /**
+     * Where a {@link RenderMode.Beam} system's quads end, see {@link BeamEnd}.
+     * Unset (the default), a beam has no length and draws nothing. Not saved
+     * in the effect JSON: it is where this instance is aimed at runtime.
+     */
+    beamEnd?: BeamEnd;
+    /**
+     * Multiplies every particle's colour, alpha included, as it is drawn:
+     * a colour or a fade driven from code for this instance (Unity's custom
+     * per-instance data, Unreal's user parameters). With {@link erosion},
+     * alpha is the erosion level, so this wipes the shape in and out. The
+     * particles' own colours are untouched, so clearing it restores them, and
+     * systems with different tints still batch together. Under additive
+     * (`ALPHA_ONEONE`) or premultiplied blending, which ignore alpha, fade
+     * with the colour instead, or with erosion on. Unset (the default): none.
+     * Not saved in the effect JSON; copied by {@link clone}.
+     */
+    tint?: Vector4;
+    private readonly beamEndScratch;
+    /** The world position of {@link beamEnd} into `out`; false when it is unset. */
+    getBeamEnd(out: Vector3): boolean;
+    /** The largest axis of the emitter's world scale. */
+    private emitterMaxScale;
+    private measureWorldBounds;
     /**
      * Records bounds a renderer measured in world space, for systems whose
      * drawn extent the store does not hold (trail ribbons).
@@ -4337,6 +4785,7 @@ declare class ParticleSystem implements IParticleSystem {
         [uuid: string]: Behavior;
     }, scene?: Scene): ParticleSystem;
     private static nextSerializationId;
+    /** Normals facing +Z, one array per geometry so systems sharing it still batch together. */
     private static createFallbackNormals;
     private toRendererSettingsJSON;
     private ensureGeometryMeta;
@@ -4587,6 +5036,22 @@ declare class QuarksUtil {
      * Nodes that are neither transform nodes nor emitters are skipped.
      */
     static instantiate(root: TransformNode, name?: string): TransformNode;
+    /**
+     * Seconds until the effect under `root` is over when it plays from the
+     * start: for each system its start delay, its duration and its longest
+     * particle life, divided by its playback speed; a sub emitter target goes
+     * on emitting for its own duration after the last of its parents' particles
+     * and ends a particle life after that, wherever it sits in the scene.
+     * Infinity when a system loops, since such an effect only ends on
+     * {@link endEmit}, or when one is frozen at playback speed 0.
+     *
+     * Random values count at their maximum, so this is an upper bound; curves
+     * are sampled. Particles cut short by collisions or culling only make the
+     * real effect shorter.
+     */
+    static getDuration(root: Node): number;
+    /** The largest value `generator` gives: exact for constants and intervals, sampled otherwise. */
+    private static maxOf;
     private static traverseNode;
 }
 
@@ -4634,6 +5099,13 @@ declare class SpriteBatch extends VFXBatch {
     private velocityVB?;
     constructor(settings: VFXBatchSettings, scene: Scene);
     setupBuffers(): void;
+    /**
+     * True when a mesh batch reads UV channel 1 and has a second UV set to
+     * read it from, two values per vertex. A set of any other length is left
+     * out with a warning, and channel 1 then reads the first set.
+     */
+    private warnedUV2;
+    private meshUV2;
     /** Releases the instance vertex buffers so a resize does not leak GPU memory. */
     private disposeExpandableBuffers;
     private buildExpandableBuffers;
@@ -4688,8 +5160,20 @@ declare class SpriteBatch extends VFXBatch {
      * optimised code on every frame.
      */
     private syncStretchedSpeedFactor;
-    /** The quads that take a pivot and flip: every billboard kind, stretched included, but not meshes. */
+    /** Stretched billboards and beams: drawn along a per-instance vector, by the stretched shader. */
+    private static drawsAlongVelocity;
+    private readonly beamEnd_;
+    /**
+     * Writes, for the `count` instances from `first`, the world vector from
+     * each one's drawn position to the system's beam end into the velocity
+     * buffer, which the stretched shader under `BEAM` lays the quad along. A
+     * beam without an end gets no length.
+     */
+    private writeBeams;
+    /** The quads that take a pivot and flip: every billboard kind, stretched included, but not meshes or beams. */
     private static takesPivotAndFlip;
+    /** Multiplies `count` RGBA colours starting at `base` by a system's {@link ParticleSystem.tint}. */
+    private static applyTint;
     /**
      * Negates the size of each flipped particle along the axes it flips on,
      * starting at `base` in `sizes`. The billboard shader scales the quad by
@@ -4759,6 +5243,8 @@ declare class TrailBatch extends VFXBatch {
     private previousBuffer;
     private nextBuffer;
     private uvBuffer;
+    /** UV channel 1: along the trail and across it, without the sheet's cell; only when a texture reads it. */
+    private uv1Buffer;
     private sideBuffer;
     private widthBuffer;
     private colorBuffer;
@@ -4787,6 +5273,12 @@ declare class TrailBatch extends VFXBatch {
      * frame costs a matrix compose per system; checking the transform cache
      * first makes a still emitter free.
      */
+    /**
+     * Writes a swept ribbon's vertex pair at `pi`: the sample at (x, y, z)
+     * pushed `half` widths along its side (sx, sy, sz) one way for the first
+     * vertex and the other way for the second.
+     */
+    private writeSweptPair;
     private static ensureWorldMatrix;
     update(): void;
     /**
@@ -4816,5 +5308,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, 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 };
+export { ApplyCollision, ApplyForce, ApplySequences, AxisAngleGenerator, BatchedParticleRenderer, BatchedRenderer, BehaviorFromJSON, BehaviorTypes, Bezier, BoxEmitFrom, BoxEmitter, ChangeEmitDirection, CircleEmitter, ColorBySpeed, ColorGeneratorFromJSON, ColorOverLife, ColorRange, ConeEmitter, ConstantColor, ConstantValue, DEG2RAD, DonutEmitter, EdgeEmitter, EffectPool, EmitSubParticleSystem, EmitterFromJSON, EmitterMode, EmitterShapes, Euler, EulerGenerator, ForceOverLife, FrameOverLife, GRADIENT_MAP_WEIGHTS, GeneratorFromJSON, Gradient, GravityForce, GridEmitter, HemisphereEmitter, InheritVelocity, IntervalValue, LimitSpeedOverLife, MathUtils, Matrix3, Matrix4, MeshSurfaceEmitter, MeshSurfaceEmitterPlugin, NodeParticle, Noise, OrbitOverLife, ParticleEmitter, ParticleMeshPhysicsMaterial, ParticleMeshStandardMaterial, ParticleStore, ParticleSystem, PiecewiseBezier, PiecewiseFunction, Plugins, PointEmitter, QuarksLoader, QuarksPrefab, QuarksUtil, Quaternion, QuaternionView, RAD2DEG, RandomColor, RandomColorBetweenGradient, RandomQuatGenerator, RecordState, RectangleEmitter, RenderMode, Rotation3DOverLife, RotationBySpeed, RotationGeneratorFromJSON, RotationOverLife, SequencerFromJSON, ShapeTransform, SizeBySpeed, SizeOverLife, SpeedOverLife, SphereEmitter, SpriteBatch, SpriteParticle, SubEmitterInheritMask, SubParticleEmitMode, TextureSequencer, TrailBatch, TrailParticle, TurbulenceField, UV_DISTORTION_DEFAULT_UV, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, createSeededRandom, cubeFaceUrls, damp, defaultMeshLighting, degToRad, denormalize, ensureEnvAtlasFromCube, erosionEqual, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRandomSource, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, gradientMapEqual, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, mapUVEqual, meshRimEqual, normalize, normalizeErosion, normalizeGradientMap, normalizeMapUV, normalizeMeshRim, normalizeTextureUV, normalizeUVDistortion, _default$5 as particleFragShader, _default$4 as particlePhysicsFragShader, _default$3 as particleVertShader, pingpong, planBehaviorFusion, radToDeg, randFloat, randFloatSpread, randInt, random, readsUV1, registerShaderChunks, seededRandom, setPhysicsResolver, setQuaternionFromProperEuler, setRandomSource, smootherstep, smoothstep, _default$2 as stretchedBillboardVertShader, subEmitterInheritMask, textureUVEqual, textureUVToJSON, _default$1 as trailFragShader, _default as trailVertShader, unloadPlugin, uvDistortionEqual, withRandomSource };
+export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, BeamEnd, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, CullingMode, DonutEmitterParameters, EdgeEmitterParameters, EffectPoolOptions, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FrameOverLifeOptions, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GradientMapChannel, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshLighting, MeshLightingSettings, MeshRim, MeshSettings, ParameterPair, ParameterType, Particle, ParticleErosion, ParticleErosionOptions, ParticleGradientMap, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, ParticleUVDistortion, ParticleUVDistortionOptions, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RandomSource, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, ScalingMode, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SortMode, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, SubEmitterInheritance, TextureUV, TrailSettings, UVChannel, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };