babylon.quarks 0.25.0 → 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 {
     /**
@@ -1760,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. */
@@ -1784,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;
     /**
@@ -2149,6 +2169,13 @@ interface FrameOverLifeOptions {
     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.
@@ -2161,7 +2188,8 @@ interface FrameOverLifeOptions {
  * 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, and a random start frame.
+ * segment that loops or holds, a random start frame, and a random frame on
+ * every tick.
  */
 declare class FrameOverLife implements Behavior {
     type: string;
@@ -2170,7 +2198,10 @@ declare class FrameOverLife implements Behavior {
     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);
@@ -2182,6 +2213,10 @@ declare class FrameOverLife implements Behavior {
     /** 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;
@@ -3372,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,
@@ -3383,6 +3421,80 @@ 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
@@ -3391,32 +3503,83 @@ declare function meshRimEqual(a: MeshRim | undefined, b: MeshRim | undefined): b
  */
 interface ParticleErosion {
     /**
-     * Mask whose red channel orders what goes first, sampled with the
-     * particle's UV (the quad, mesh or trail UV, unscrolled). Null: the map's
-     * own alpha, so a soft shape shrinks from its edges.
+     * 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];
-    /** Mask UV scroll, UV units per second. Default `[0, 0]`. */
-    maskScroll: [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: Partial<ParticleErosion> | null | undefined): ParticleErosion | undefined;
+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;
-/** A UV scroll speed, or undefined when unset or zero. */
-declare function normalizeUVScroll(scroll: ArrayLike<number> | null | undefined): [number, number] | undefined;
-/** True when both scroll the same way (or both not at all). */
-declare function uvScrollEqual(a: [number, number] | undefined, b: [number, number] | 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;
@@ -3453,10 +3616,12 @@ interface StoredBatchSettings {
     lighting?: MeshLighting;
     /** Mesh particle rim, see {@link VFXBatchSettings.rim}. */
     rim?: MeshRim;
-    /** Map UV scroll, see {@link VFXBatchSettings.uvScroll}. */
-    uvScroll?: [number, number];
+    /** 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: BaseTexture | null;
+    gradientMap?: ParticleGradientMap;
     /** Alpha erosion, see {@link VFXBatchSettings.erosion}. */
     erosion?: ParticleErosion;
 }
@@ -3501,6 +3666,8 @@ declare abstract class VFXBatch {
      * 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. */
@@ -3529,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;
@@ -3604,20 +3773,12 @@ interface VFXBatchSettings {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles; unset draws none. See {@link MeshRim}. */
     rim?: MeshRim;
-    /**
-     * Scrolls the map's UV by this many UV units per second, `[u, v]`, on the
-     * renderer's clock. The texture should wrap; scrolling one tile of a sheet
-     * runs into its neighbours. Unset or zero: no scroll. Systems that differ
-     * are batched apart.
-     */
-    uvScroll?: [number, number];
-    /**
-     * Colour ramp the map is recoloured through: the map's red channel picks
-     * a colour along U of this texture, and its alpha multiplies the map's. The
-     * particle colour still tints the result. Unset: none. Systems that differ
-     * are batched apart.
-     */
-    gradientMap?: BaseTexture | null;
+    /** 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;
 }
@@ -3964,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;
@@ -3993,12 +4160,14 @@ interface ParticleSystemParameters {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles, see {@link ParticleSystem.rim}. Default none. */
     rim?: Partial<MeshRim>;
-    /** Map UV scroll in UV units per second, see {@link ParticleSystem.uvScroll}. Default none. */
-    uvScroll?: [number, number];
+    /** 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?: BaseTexture | null;
+    gradientMap?: Partial<ParticleGradientMap>;
     /** Alpha erosion, see {@link ParticleSystem.erosion}. Default none. */
-    erosion?: Partial<ParticleErosion>;
+    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'`. */
@@ -4264,22 +4433,28 @@ declare class ParticleSystem implements IParticleSystem {
     get rim(): MeshRim | undefined;
     set rim(rim: Partial<MeshRim> | undefined);
     /**
-     * Scrolls the map's UV by `[u, v]` UV units per second on the renderer's
-     * clock: flowing energy, lava, a smear running along a mesh. The texture
-     * should wrap. Undefined (the default) or zero does not scroll. Assign a
-     * new array to change it. Saved with the material in the effect JSON.
-     */
-    get uvScroll(): [number, number] | undefined;
-    set uvScroll(scroll: [number, number] | undefined);
-    /**
-     * Colour ramp the map is recoloured through (a gradient map): the map's
-     * red channel picks a colour along U of this texture, whose alpha
-     * multiplies the map's; the particle colour still tints the result. One
-     * greyscale texture then serves every palette. Null (the default): none.
-     * Saved with the material in the effect JSON.
-     */
-    get gradientMap(): BaseTexture | null;
-    set gradientMap(texture: BaseTexture | null);
+     * 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
@@ -4290,7 +4465,16 @@ declare class ParticleSystem implements IParticleSystem {
      * Saved with the material in the effect JSON.
      */
     get erosion(): ParticleErosion | undefined;
-    set erosion(erosion: Partial<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
@@ -4311,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;
@@ -4479,6 +4675,18 @@ declare class ParticleSystem implements IParticleSystem {
      * 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;
@@ -4577,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;
@@ -4890,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;
@@ -4956,6 +5172,8 @@ declare class SpriteBatch extends VFXBatch {
     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
@@ -5025,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;
@@ -5053,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;
     /**
@@ -5082,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, erosionEqual, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRandomSource, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, meshRimEqual, normalize, normalizeErosion, normalizeMeshRim, normalizeUVScroll, _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, uvScrollEqual, 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, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshLighting, MeshLightingSettings, MeshRim, MeshSettings, ParameterPair, ParameterType, Particle, ParticleErosion, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RandomSource, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, ScalingMode, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "babylon.quarks",
-    "version": "0.25.0",
+    "version": "0.26.0",
     "description": "A High-Performance Particle System for Babylon.js",
     "type": "module",
     "types": "./dist/types/index.d.ts",

package/src/BatchedRenderer.ts

@@ -12,15 +12,21 @@ import {TrailBatch} from './TrailBatch';
 import {
     defaultMeshLighting,
     erosionEqual,
+    gradientMapEqual,
+    mapUVEqual,
     MeshLighting,
     MeshLightingSettings,
     MeshRim,
     meshRimEqual,
     ParticleErosion,
+    ParticleGradientMap,
+    ParticleUVDistortion,
+    readsUV1,
     RenderMode,
     SortMode,
     StoredBatchSettings,
-    uvScrollEqual,
+    TextureUV,
+    uvDistortionEqual,
     VFXBatch,
 } from './VFXBatch';
 
@@ -28,6 +34,8 @@ export 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;
@@ -103,20 +111,12 @@ export interface VFXBatchSettings {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles; unset draws none. See {@link MeshRim}. */
     rim?: MeshRim;
-    /**
-     * Scrolls the map's UV by this many UV units per second, `[u, v]`, on the
-     * renderer's clock. The texture should wrap; scrolling one tile of a sheet
-     * runs into its neighbours. Unset or zero: no scroll. Systems that differ
-     * are batched apart.
-     */
-    uvScroll?: [number, number];
-    /**
-     * Colour ramp the map is recoloured through: the map's red channel picks
-     * a colour along U of this texture, and its alpha multiplies the map's. The
-     * particle colour still tints the result. Unset: none. Systems that differ
-     * are batched apart.
-     */
-    gradientMap?: BaseTexture | null;
+    /** 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;
 }
@@ -323,6 +323,11 @@ export class BatchedRenderer extends TransformNode {
             a.uTileCount === b.uTileCount &&
             a.vTileCount === b.vTileCount &&
             a.instancingGeometry === b.instancingGeometry &&
+            // Trails draw their own strip and read none of the instanced geometry's UVs.
+            (a.renderMode === RenderMode.Trail || a.instancingUVs === b.instancingUVs) &&
+            // Normals, and the second UV set when read, only matter to meshes.
+            (a.renderMode !== RenderMode.Mesh || a.instancingNormals === b.instancingNormals) &&
+            (a.renderMode !== RenderMode.Mesh || !readsUV1(a) || a.instancingUVs2 === b.instancingUVs2) &&
             a.renderOrder === b.renderOrder &&
             a.layerMask === b.layerMask &&
             a.renderingGroupId === b.renderingGroupId &&
@@ -333,8 +338,9 @@ export class BatchedRenderer extends TransformNode {
             a.maxParticleSize === (b.maxParticleSize ?? Infinity) &&
             (a.lighting ?? 'fixed') === (b.lighting ?? 'fixed') &&
             meshRimEqual(a.rim, b.rim) &&
-            uvScrollEqual(a.uvScroll, b.uvScroll) &&
-            a.gradientMap === (b.gradientMap ?? null) &&
+            mapUVEqual(a.mapUV, b.mapUV) &&
+            uvDistortionEqual(a.uvDistortion, b.uvDistortion) &&
+            gradientMapEqual(a.gradientMap, b.gradientMap) &&
             erosionEqual(a.erosion, b.erosion)
         );
     }