babylon.quarks 0.25.0 → 0.27.0

package/src/VFXBatch.ts

@@ -1,6 +1,6 @@
 import {BoundingInfo} from '@babylonjs/core/Culling/boundingInfo';
-import {Constants} from '@babylonjs/core/Engines/constants';
 import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {Effect} from '@babylonjs/core/Materials/effect';
 import {ShaderMaterial} from '@babylonjs/core/Materials/shaderMaterial';
 import {Color3} from '@babylonjs/core/Maths/math.color';
 import {Vector2 as BVector2, Vector3 as BVector3, Vector4 as BVector4} from '@babylonjs/core/Maths/math.vector';
@@ -9,6 +9,8 @@ import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Vector3} from 'quarks.core';
 import {VFXBatchSettings} from './BatchedRenderer';
 import type {ParticleSystem} from './ParticleSystem';
+import {storedBatchSettings} from './batchKey';
+import {DepthBinding, softDepthParams} from './softDepth';
 
 /**
  * The order the particles of a batch are drawn in (Unity's Sort Mode). Alpha
@@ -23,12 +25,25 @@ import type {ParticleSystem} from './ParticleSystem';
  */
 export type SortMode = 'none' | 'distance' | 'oldestInFront' | 'youngestInFront';
 
+/** How a system draws its particles (Unity's Render Mode), see {@link ParticleSystem.renderMode}. */
 export enum RenderMode {
+    /** A quad facing the camera (Unity's Billboard). The default. */
     BillBoard = 0,
+    /**
+     * A quad facing the camera and stretched along the particle's velocity (Unity's Stretched
+     * Billboard), by `speedFactor` and `lengthFactor` in the system's `rendererEmitterSettings`.
+     */
     StretchedBillBoard = 1,
+    /** The system's mesh, one instance per particle (Unity's Mesh), see {@link ParticleSystem.instancingGeometry}. */
     Mesh = 2,
+    /**
+     * A ribbon drawn through the particle's past positions (Unity's Trails module, Niagara's
+     * ribbon), facing the camera; its settings are `TrailSettings` in `rendererEmitterSettings`.
+     */
     Trail = 3,
+    /** A quad lying flat in the world's XZ plane, facing up (Unity's Horizontal Billboard). */
     HorizontalBillBoard = 4,
+    /** A quad standing upright and turning only about the world's Y axis to face the camera (Unity's Vertical Billboard). */
     VerticalBillBoard = 5,
     /**
      * A quad laid from each particle to the system's {@link ParticleSystem.beamEnd}
@@ -87,9 +102,12 @@ export 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';
 }
 
 /**
@@ -107,7 +125,7 @@ export function normalizeMeshRim(rim: Partial<MeshRim> | null | undefined): Mesh
         color: [channel(color[0], 1), channel(color[1], 1), channel(color[2], 1)],
         power: Math.max(0.01, channel(rim.power, 2)),
         strength: Math.max(0, channel(rim.strength, 1)),
-        mode: rim.mode === 'mix' ? 'mix' : 'add',
+        mode: rim.mode === 'mix' || rim.mode === 'fade' ? rim.mode : 'add',
     };
 }
 
@@ -129,6 +147,145 @@ export function meshRimEqual(a: MeshRim | undefined, b: MeshRim | undefined): bo
     );
 }
 
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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. */
+export function normalizeTextureUV(
+    uv: Partial<TextureUV> | null | undefined,
+    defaults: Partial<TextureUV> = {}
+): TextureUV {
+    const source = uv && typeof uv === 'object' ? uv : {};
+    const num = (value: unknown, fallback: number) =>
+        typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    const pair = (value: unknown, fallback: [number, number]): [number, number] =>
+        Array.isArray(value) ? [num(value[0], fallback[0]), num(value[1], fallback[1])] : [fallback[0], fallback[1]];
+    const channel = source.channel ?? defaults.channel;
+    return {
+        channel: channel === 1 ? 1 : 0,
+        tiling: pair(source.tiling, defaults.tiling ?? [1, 1]),
+        offset: pair(source.offset, defaults.offset ?? [0, 0]),
+        scroll: pair(source.scroll, defaults.scroll ?? [0, 0]),
+    };
+}
+
+/** True when both lay a texture the same way. */
+export function textureUVEqual(a: TextureUV, b: TextureUV): boolean {
+    return (
+        a === b ||
+        (a.channel === b.channel &&
+            a.tiling[0] === b.tiling[0] &&
+            a.tiling[1] === b.tiling[1] &&
+            a.offset[0] === b.offset[0] &&
+            a.offset[1] === b.offset[1] &&
+            a.scroll[0] === b.scroll[0] &&
+            a.scroll[1] === b.scroll[1])
+    );
+}
+
+/** The fields of `uv` that differ from `defaults`, for JSON written only when set. */
+export function textureUVToJSON(uv: TextureUV, defaults: Partial<TextureUV> = {}): Partial<TextureUV> | undefined {
+    const base = normalizeTextureUV(undefined, defaults);
+    const json: Partial<TextureUV> = {};
+    if (uv.channel !== base.channel) json.channel = uv.channel;
+    if (uv.tiling[0] !== base.tiling[0] || uv.tiling[1] !== base.tiling[1]) json.tiling = [...uv.tiling];
+    if (uv.offset[0] !== base.offset[0] || uv.offset[1] !== base.offset[1]) json.offset = [...uv.offset];
+    if (uv.scroll[0] !== base.scroll[0] || uv.scroll[1] !== base.scroll[1]) json.scroll = [...uv.scroll];
+    return Object.keys(json).length > 0 ? json : 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.
+ */
+export 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}. Without a map the lookup reads
+ * white, so the ramp's right-hand end tints every particle, in every render
+ * mode alike. See {@link VFXBatchSettings.gradientMap}.
+ */
+export 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}. */
+export const GRADIENT_MAP_WEIGHTS: Readonly<Record<GradientMapChannel, readonly [number, number, number, number]>> = {
+    r: [1, 0, 0, 0],
+    g: [0, 1, 0, 0],
+    b: [0, 0, 1, 0],
+    a: [0, 0, 0, 1],
+    luminance: [0.2126, 0.7152, 0.0722, 0],
+};
+
+/** A complete gradient map, or undefined when unset or without a ramp. */
+export function normalizeGradientMap(
+    gradientMap: Partial<ParticleGradientMap> | null | undefined
+): ParticleGradientMap | undefined {
+    if (!gradientMap || typeof gradientMap !== 'object' || !gradientMap.ramp) {
+        return undefined;
+    }
+    const channel = gradientMap.channel;
+    return {
+        ramp: gradientMap.ramp,
+        channel: channel !== undefined && channel in GRADIENT_MAP_WEIGHTS ? channel : 'r',
+    };
+}
+
+/** True when both recolour the same way (or both not at all). */
+export function gradientMapEqual(a: ParticleGradientMap | undefined, b: ParticleGradientMap | undefined): boolean {
+    return a === b || (!!a && !!b && a.ramp === b.ramp && a.channel === b.channel);
+}
+
 /**
  * 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
@@ -137,41 +294,51 @@ export function meshRimEqual(a: MeshRim | undefined, b: MeshRim | undefined): bo
  */
 export 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];
 }
-// Limits worth knowing: the mask is sampled with the UV as drawn (on a sheet,
-// the current tile's), erosion only changes alpha (one-one and premultiplied
+// Limits worth knowing: erosion only changes alpha (one-one and premultiplied
 // blending show a hard cut), and with neither a mask nor a map there is
 // nothing to order the cut by, so the shape goes all at once near alpha 0.
 // Scrolling runs on the renderer's clock, not a system's playback speed.
 
+/** {@link ParticleErosion} as given: any field may be left out, the mask's layout too. */
+export type ParticleErosionOptions = Partial<Omit<ParticleErosion, 'maskUV'>> & {
+    /** See {@link ParticleErosion.maskUV}; fields left out take their defaults. */
+    maskUV?: Partial<TextureUV>;
+};
+
+/** The width of the soft band an erosion cut fades over when `softness` is left out, in mask units. */
+export const EROSION_DEFAULT_SOFTNESS = 0.05;
+
 /** A complete erosion from a partial one, every field defaulted, or undefined when `erosion` is unset. */
-export function normalizeErosion(erosion: Partial<ParticleErosion> | null | undefined): ParticleErosion | undefined {
+export function normalizeErosion(erosion: ParticleErosionOptions | null | undefined): ParticleErosion | undefined {
     if (!erosion || typeof erosion !== 'object') {
         return undefined;
     }
     const num = (value: unknown, fallback: number) =>
         typeof value === 'number' && Number.isFinite(value) ? value : fallback;
     const color = Array.isArray(erosion.edgeColor) ? erosion.edgeColor : [1, 1, 1];
-    const scroll = Array.isArray(erosion.maskScroll) ? erosion.maskScroll : [0, 0];
     return {
         mask: erosion.mask ?? null,
-        softness: Math.max(0.0001, num(erosion.softness, 0.05)),
+        maskUV: normalizeTextureUV(erosion.maskUV),
+        softness: Math.max(0.0001, num(erosion.softness, EROSION_DEFAULT_SOFTNESS)),
         edgeWidth: Math.max(0, num(erosion.edgeWidth, 0)),
         edgeColor: [num(color[0], 1), num(color[1], 1), num(color[2], 1)],
-        maskScroll: [num(scroll[0], 0), num(scroll[1], 0)],
     };
 }
 
@@ -185,54 +352,161 @@ export function erosionEqual(a: ParticleErosion | undefined, b: ParticleErosion
     }
     return (
         a.mask === b.mask &&
+        textureUVEqual(a.maskUV, b.maskUV) &&
         a.softness === b.softness &&
         a.edgeWidth === b.edgeWidth &&
         a.edgeColor[0] === b.edgeColor[0] &&
         a.edgeColor[1] === b.edgeColor[1] &&
-        a.edgeColor[2] === b.edgeColor[2] &&
-        a.maskScroll[0] === b.maskScroll[0] &&
-        a.maskScroll[1] === b.maskScroll[1]
+        a.edgeColor[2] === b.edgeColor[2]
     );
 }
 
-/** A UV scroll speed, or undefined when unset or zero. */
-export function normalizeUVScroll(scroll: ArrayLike<number> | null | undefined): [number, number] | undefined {
-    if (!scroll || typeof scroll !== 'object') {
+/** The distortion noise's default layout: drifting up half a repeat a second. */
+export const UV_DISTORTION_DEFAULT_UV: Partial<TextureUV> = {scroll: [0, 0.5]};
+
+/**
+ * UV distortion: the map's UV pushed about by a noise texture, for heat
+ * shimmer, licking flames and breathing auras. See
+ * {@link VFXBatchSettings.uvDistortion}.
+ */
+export 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. */
+export type ParticleUVDistortionOptions = Partial<Omit<ParticleUVDistortion, 'mapUV'>> & {
+    /** See {@link ParticleUVDistortion.mapUV}; fields left out take their defaults. */
+    mapUV?: Partial<TextureUV>;
+};
+
+/** How far a distortion pushes the map's UV at most when `strength` is left out, in UV units. */
+export const UV_DISTORTION_DEFAULT_STRENGTH = 0.05;
+
+/** A complete distortion from a partial one, or undefined when unset or without a map. */
+export function normalizeUVDistortion(
+    distortion: ParticleUVDistortionOptions | null | undefined
+): ParticleUVDistortion | undefined {
+    if (!distortion || typeof distortion !== 'object' || !distortion.map) {
+        return undefined;
+    }
+    const strength = distortion.strength;
+    return {
+        map: distortion.map,
+        mapUV: normalizeTextureUV(distortion.mapUV, UV_DISTORTION_DEFAULT_UV),
+        strength: Math.max(
+            0,
+            typeof strength === 'number' && Number.isFinite(strength) ? strength : UV_DISTORTION_DEFAULT_STRENGTH
+        ),
+    };
+}
+
+/** True when both describe the same distortion (or both none). */
+export function uvDistortionEqual(a: ParticleUVDistortion | undefined, b: ParticleUVDistortion | undefined): boolean {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b) {
+        return false;
+    }
+    return a.map === b.map && a.strength === b.strength && textureUVEqual(a.mapUV, b.mapUV);
+}
+
+/**
+ * The main map's layout, or undefined when it is the identity (channel 0,
+ * untiled, unmoved, still), which costs nothing in the shader.
+ */
+export function normalizeMapUV(uv: Partial<TextureUV> | null | undefined): TextureUV | undefined {
+    if (!uv || typeof uv !== 'object') {
         return undefined;
     }
-    const u = Number.isFinite(scroll[0]) ? scroll[0] : 0;
-    const v = Number.isFinite(scroll[1]) ? scroll[1] : 0;
-    return u === 0 && v === 0 ? undefined : [u, v];
+    const normalized = normalizeTextureUV(uv);
+    return textureUVToJSON(normalized) === undefined ? undefined : normalized;
 }
 
-/** True when both scroll the same way (or both not at all). */
-export function uvScrollEqual(a: [number, number] | undefined, b: [number, number] | undefined): boolean {
-    return a === b || (!!a && !!b && a[0] === b[0] && a[1] === b[1]);
+/** True when both lay the map the same way (or both as drawn). */
+export function mapUVEqual(a: TextureUV | undefined, b: TextureUV | undefined): boolean {
+    return a === b || (!!a && !!b && textureUVEqual(a, b));
 }
 
+/**
+ * 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.
+ */
+export function readsUV1(settings: {
+    mapUV?: TextureUV;
+    uvDistortion?: ParticleUVDistortion;
+    erosion?: ParticleErosion;
+}): boolean {
+    const {mapUV, uvDistortion, erosion} = settings;
+    return (
+        mapUV?.channel === 1 || uvDistortion?.mapUV.channel === 1 || (!!erosion?.mask && erosion.maskUV.channel === 1)
+    );
+}
+
+/**
+ * A batch's copy of the {@link VFXBatchSettings} its systems share: every optional field
+ * defaulted, and every field the batch's render mode ignores at its default (an opaque batch's
+ * `materialBlendMode` reads `ALPHA_DISABLE`, a billboard batch's `rim` is unset). The renderer
+ * adds a system to the batch whose settings match its own.
+ */
 export interface StoredBatchSettings {
+    /** See {@link VFXBatchSettings.instancingGeometry}. */
     instancingGeometry: Float32Array;
+    /** See {@link VFXBatchSettings.instancingIndices}. */
     instancingIndices: Uint32Array | Uint16Array;
+    /** See {@link VFXBatchSettings.instancingUVs}. */
     instancingUVs?: Float32Array;
+    /** The mesh's second UV set, see {@link UVChannel}. */
+    instancingUVs2?: Float32Array;
+    /** See {@link VFXBatchSettings.instancingNormals}. */
     instancingNormals?: Float32Array;
+    /** See {@link VFXBatchSettings.renderMode}. */
     renderMode: RenderMode;
+    /** See {@link VFXBatchSettings.renderOrder}. */
     renderOrder: number;
+    /** See {@link VFXBatchSettings.uTileCount}. */
     uTileCount: number;
+    /** See {@link VFXBatchSettings.vTileCount}. */
     vTileCount: number;
+    /** See {@link VFXBatchSettings.blendTiles}. */
     blendTiles: boolean;
+    /** See {@link VFXBatchSettings.softParticles}. */
     softParticles: boolean;
+    /** See {@link VFXBatchSettings.softNearFade}. */
     softNearFade: number;
+    /** See {@link VFXBatchSettings.softFarFade}. */
     softFarFade: number;
+    /** See {@link VFXBatchSettings.materialBlendMode}. */
     materialBlendMode: number;
+    /** See {@link VFXBatchSettings.materialTransparent}. */
     materialTransparent: boolean;
+    /** See {@link VFXBatchSettings.materialDepthTest}. */
     materialDepthTest: boolean;
+    /** See {@link VFXBatchSettings.materialDepthWrite}. */
     materialDepthWrite: boolean;
+    /** See {@link VFXBatchSettings.materialAlphaTest}. */
     materialAlphaTest: number;
-    texture: any;
+    /** See {@link VFXBatchSettings.texture}. */
+    texture: BaseTexture | null;
+    /** See {@link VFXBatchSettings.reflectionTexture}. */
     reflectionTexture: BaseTexture | null;
+    /** See {@link VFXBatchSettings.reflectionLevel}. */
     reflectionLevel: number;
-    reflectionFaces: BaseTexture[] | null;
+    /** See {@link VFXBatchSettings.reflectionAtlas}. */
     reflectionAtlas: BaseTexture | null;
+    /** See {@link VFXBatchSettings.layerMask}. */
     layerMask: number;
     /** Babylon rendering group the batch mesh draws in, see {@link VFXBatchSettings.renderingGroupId}. */
     renderingGroupId: number;
@@ -250,62 +524,48 @@ export 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;
 }
 
+/**
+ * One draw call of a {@link BatchedRenderer}: the systems that share a material, texture and
+ * geometry, drawn together from one instanced mesh. The renderer makes and frees batches as
+ * systems are added and their settings change; read them through `renderer.batches` to inspect
+ * what is drawn, not to change it.
+ */
 export abstract class VFXBatch {
+    /** The Babylon mesh the batch draws with. */
     mesh: Mesh;
+    /** The systems drawn by this batch. */
     systems: Set<IParticleSystem>;
+    /** The settings every system in the batch shares, with what the render mode ignores at its default. */
     settings: StoredBatchSettings;
+    /** @internal */
     protected maxParticles: number;
+    /** @internal */
     protected scene: Scene;
+    /** @internal */
     protected readonly visibleSystems: IParticleSystem[] = [];
+    /**
+     * The depth texture soft particles read, from {@link BatchedRenderer.setDepthTexture}.
+     * @internal
+     */
+    protected depth: DepthBinding | null;
 
-    protected constructor(settings: VFXBatchSettings, scene: Scene) {
+    /** @internal */
+    protected constructor(settings: VFXBatchSettings, scene: Scene, depth: DepthBinding | null = null) {
         this.scene = scene;
+        this.depth = depth;
         this.maxParticles = 1000;
         this.systems = new Set<IParticleSystem>();
-        this.settings = {
-            instancingGeometry: settings.instancingGeometry,
-            instancingIndices: settings.instancingIndices,
-            instancingUVs: settings.instancingUVs,
-            instancingNormals: settings.instancingNormals,
-            renderMode: settings.renderMode,
-            renderOrder: settings.renderOrder,
-            uTileCount: settings.uTileCount,
-            vTileCount: settings.vTileCount,
-            blendTiles: settings.blendTiles,
-            softParticles: settings.softParticles,
-            softNearFade: settings.softNearFade,
-            softFarFade: settings.softFarFade,
-            materialBlendMode: settings.materialBlendMode,
-            materialTransparent: settings.materialTransparent,
-            materialDepthTest: settings.materialDepthTest,
-            materialDepthWrite: settings.materialDepthWrite,
-            materialAlphaTest: settings.materialAlphaTest,
-            texture: settings.texture,
-            reflectionTexture: settings.reflectionTexture ?? null,
-            reflectionLevel: settings.reflectionLevel ?? 1,
-            reflectionFaces: settings.reflectionFaces ?? null,
-            reflectionAtlas: settings.reflectionAtlas ?? null,
-            pivot: settings.pivot?.clone(),
-            sortMode: settings.sortMode ?? 'none',
-            minParticleSize: settings.minParticleSize ?? 0,
-            maxParticleSize: settings.maxParticleSize ?? Infinity,
-            layerMask: settings.layerMask,
-            renderingGroupId: settings.renderingGroupId ?? 0,
-            applyFog: settings.applyFog ?? true,
-            lighting: settings.lighting,
-            rim: normalizeMeshRim(settings.rim),
-            uvScroll: normalizeUVScroll(settings.uvScroll),
-            gradientMap: settings.gradientMap ?? null,
-            erosion: normalizeErosion(settings.erosion),
-        };
+        this.settings = storedBatchSettings(settings);
         this.mesh = new Mesh('vfxBatch', scene);
         this.configureMesh();
     }
@@ -333,6 +593,12 @@ export abstract class VFXBatch {
         mesh.alphaIndex = this.settings.renderOrder;
         // The shaders fog themselves; Babylon's own fog pass does not apply to a ShaderMaterial.
         mesh.applyFog = false;
+        // Its geometry is one quad or mesh at the origin, not the particles, so a pick or a
+        // collision against it would hit nothing that is drawn. The renderer rebuilds batches
+        // from its systems, so a scene serializer has nothing to write either.
+        mesh.isPickable = false;
+        mesh.checkCollisions = false;
+        mesh.doNotSerialize = true;
     }
 
     private readonly boundsMin_ = new Vector3();
@@ -395,23 +661,26 @@ export abstract class VFXBatch {
     }
 
     /**
-     * Fog defines and uniforms for a material of this batch, and the per-bind
-     * upload of the scene's current fog. Mode 0 (none) when the scene has fog
-     * disabled, so toggling fog at runtime needs no recompile.
+     * Writes a uniform that changes per bind, such as one read off the active camera, to the
+     * material for the next bind and to its bound effect for this one: ShaderMaterial uploads its
+     * stored values before the bind observers run, so a value written only to the material would
+     * reach the GPU one draw late, and with two cameras it would always be the other camera's.
      */
-    protected static readonly FOG_UNIFORMS = ['vFogInfos', 'vFogColor'];
-
-    protected fogDefines(): string[] {
-        if (!this.settings.applyFog) {
-            return [];
+    protected static writeBound(material: ShaderMaterial, write: (target: ShaderMaterial | Effect) => void): void {
+        write(material);
+        // An effect still compiling has no pipeline context to write to; it gets the stored value
+        // when it is first bound. A sub mesh's effect override is not reached here.
+        const effect = material.getEffect();
+        if (effect?.isReady()) {
+            write(effect);
         }
-        const additive =
-            this.settings.materialTransparent &&
-            (this.settings.materialBlendMode === Constants.ALPHA_ADD ||
-                this.settings.materialBlendMode === Constants.ALPHA_ONEONE);
-        return additive ? ['FOG', 'FOG_ADDITIVE'] : ['FOG'];
     }
 
+    /**
+     * The per-bind upload of the scene's current fog. Mode 0 (none) when the scene has fog
+     * disabled, so toggling fog at runtime needs no recompile.
+     * @internal
+     */
     protected bindFog(material: ShaderMaterial): void {
         if (!this.settings.applyFog) {
             return;
@@ -434,90 +703,71 @@ export abstract class VFXBatch {
      */
     time = 0;
 
-    /** Defines of the texture effects (see `shaders/chunks/surface.ts`) this batch uses. */
-    protected surfaceDefines(): string[] {
-        const defines: string[] = [];
-        if (this.settings.uvScroll) {
-            defines.push('UV_SCROLL');
-        }
-        if (this.settings.gradientMap) {
-            defines.push('GRADIENT_MAP');
-        }
-        const erosion = this.settings.erosion;
-        if (erosion) {
-            defines.push('EROSION');
-            if (erosion.mask) {
-                defines.push('EROSION_MASK');
-            }
-        }
-        return defines;
-    }
-
-    /** Adds the uniforms and samplers of the texture effects this batch uses. */
-    protected surfaceUniforms(uniforms: string[], samplers: string[]): void {
-        if (this.settings.uvScroll) {
-            uniforms.push('uvScrollOffset');
-        }
-        if (this.settings.gradientMap) {
-            samplers.push('gradientMap');
-            uniforms.push('gradientMapRange');
-        }
-        const erosion = this.settings.erosion;
-        if (erosion) {
-            uniforms.push('erosionParams', 'erosionEdgeColor');
-            if (erosion.mask) {
-                samplers.push('erosionMask');
-            }
-        }
+    /** True when a texture effect of this batch samples UV channel 1, see {@link UVChannel}. */
+    protected usesUV1(): boolean {
+        return readsUV1(this.settings);
     }
 
     /** Sets the texture effects' textures and constants, and advances their scrolling on every bind. */
     protected bindSurface(material: ShaderMaterial): void {
-        const {uvScroll, gradientMap, erosion} = this.settings;
-        if (gradientMap) {
-            material.setTexture('gradientMap', gradientMap);
+        const {mapUV, uvDistortion, gradientMap, erosion} = this.settings;
+        if (uvDistortion?.map) {
+            material.setTexture('distortionMap', uvDistortion.map);
         }
-        if (erosion) {
-            if (erosion.mask) {
-                material.setTexture('erosionMask', erosion.mask);
-            }
-            material.setVector3(
-                'erosionEdgeColor',
-                new BVector3(erosion.edgeColor[0], erosion.edgeColor[1], erosion.edgeColor[2])
-            );
+        if (gradientMap?.ramp) {
+            material.setTexture('gradientMap', gradientMap.ramp);
+        }
+        if (erosion?.mask) {
+            material.setTexture('erosionMask', erosion.mask);
         }
-        if (!uvScroll && !erosion && !gradientMap) {
+        this.writeSurfaceParams(material);
+        if (!mapUV && !uvDistortion && !erosion?.mask && !gradientMap) {
             return;
         }
         // Wrapped on the CPU: a raw speed × time grows until float32 UVs lose their fraction.
-        const wrap = (value: number) => value - Math.floor(value);
-        const scrollOffset = new BVector2();
-        const erosionParams = new BVector4();
+        // Over two repeats, not one: a mirrored texture repeats every two, and
+        // wrapped over one it jumped to its mirror image at every wrap.
+        const wrap = (value: number) => value - 2 * Math.floor(value / 2);
+        const mapTransform = new BVector4();
+        const distortionTransform = new BVector4();
+        const maskTransform = new BVector4();
         const gradientRange = new BVector2(0, 1);
+        // Only the scroll is wrapped: an offset is kept as given, so a clamped
+        // texture moved off its edge stays moved.
+        const transform = (uv: TextureUV, time: number, out: BVector4) =>
+            out.set(
+                uv.tiling[0],
+                uv.tiling[1],
+                uv.offset[0] + wrap(uv.scroll[0] * time),
+                uv.offset[1] + wrap(uv.scroll[1] * time)
+            );
         // Written to the material for the next bind and to the bound effect for
         // this one: ShaderMaterial uploads its values before the bind observers run.
+        // The layouts are read off the settings on every bind, so a live change
+        // to a tiling or scroll reaches the next draw.
         const write = () => {
             const time = this.time;
             const effect = material.getEffect();
-            if (uvScroll) {
-                scrollOffset.set(wrap(uvScroll[0] * time), wrap(uvScroll[1] * time));
-                material.setVector2('uvScrollOffset', scrollOffset);
-                effect?.setVector2('uvScrollOffset', scrollOffset);
+            const {mapUV, uvDistortion, gradientMap, erosion} = this.settings;
+            if (mapUV) {
+                transform(mapUV, time, mapTransform);
+                material.setVector4('mapTransform', mapTransform);
+                effect?.setVector4('mapTransform', mapTransform);
+            }
+            if (uvDistortion) {
+                transform(uvDistortion.mapUV, time, distortionTransform);
+                material.setVector4('distortionTransform', distortionTransform);
+                effect?.setVector4('distortionTransform', distortionTransform);
             }
-            if (erosion) {
-                erosionParams.set(
-                    erosion.softness,
-                    erosion.edgeWidth,
-                    wrap(erosion.maskScroll[0] * time),
-                    wrap(erosion.maskScroll[1] * time)
-                );
-                material.setVector4('erosionParams', erosionParams);
-                effect?.setVector4('erosionParams', erosionParams);
+            if (erosion?.mask) {
+                transform(erosion.maskUV, time, maskTransform);
+                material.setVector4('erosionMaskTransform', maskTransform);
+                effect?.setVector4('erosionMaskTransform', maskTransform);
             }
-            if (gradientMap) {
+            if (gradientMap?.ramp) {
                 // Texel centres of the first and last texel, so a repeating
                 // ramp does not blend its two ends at black and white.
-                const width = gradientMap.getSize().width;
+                const width = gradientMap.ramp.getSize().width;
                 const half = width > 0 ? 0.5 / width : 0;
                 gradientRange.set(half, 1 - half);
                 material.setVector2('gradientMapRange', gradientRange);
@@ -528,11 +778,56 @@ export abstract class VFXBatch {
         material.onBindObservable.add(write);
     }
 
-    addSystem(system: IParticleSystem) {
+    /** Writes the texture effects' constants (the uniforms their live parameters set). */
+    private writeSurfaceParams(material: ShaderMaterial): void {
+        const {uvDistortion, gradientMap, erosion} = this.settings;
+        if (uvDistortion?.map) {
+            material.setFloat('distortionStrength', uvDistortion.strength);
+        }
+        if (gradientMap?.ramp) {
+            const [r, g, b, a] = GRADIENT_MAP_WEIGHTS[gradientMap.channel];
+            material.setVector4('gradientMapChannel', new BVector4(r, g, b, a));
+        }
+        if (erosion) {
+            material.setVector2('erosionParams', new BVector2(erosion.softness, erosion.edgeWidth));
+            material.setVector3(
+                'erosionEdgeColor',
+                new BVector3(erosion.edgeColor[0], erosion.edgeColor[1], erosion.edgeColor[2])
+            );
+        }
+    }
+
+    /**
+     * Takes new live parameters (see {@link BatchedRenderer.updateSystem}): settings with the same
+     * shader key as the batch's, whose uniform values differ. They are copied into the batch's
+     * settings and written to its material, which is kept.
+     * @internal
+     */
+    applyLiveSettings(settings: StoredBatchSettings): void {
+        Object.assign(this.settings, settings);
+        const material = this.mesh.material;
+        if (material instanceof ShaderMaterial) {
+            this.writeLiveUniforms(material);
+        }
+    }
+
+    /**
+     * Writes every uniform a live parameter sets, from the batch's settings. The base writes the
+     * ones every render mode has; a mode adds its own.
+     * @internal
+     */
+    protected writeLiveUniforms(material: ShaderMaterial): void {
+        this.writeSoftParams(material);
+        this.writeSurfaceParams(material);
+    }
+
+    /** @internal */
+    addSystem(system: IParticleSystem): void {
         this.systems.add(system);
     }
 
-    removeSystem(system: IParticleSystem) {
+    /** @internal */
+    removeSystem(system: IParticleSystem): void {
         this.systems.delete(system);
     }
 
@@ -555,21 +850,90 @@ export abstract class VFXBatch {
         return visibleSystems;
     }
 
-    applyDepthTexture(depthTexture: BaseTexture | null): void {
+    /**
+     * Sets the depth texture soft particles read. Soft particles are compiled in only while there
+     * is one, as Unity turns them off for a camera without a depth texture, so attaching or
+     * removing it, or changing how it is packed, rebuilds a soft batch's material.
+     *
+     * @param depth - The binding, or a bare texture, read as `'linear'` and unpacked.
+     * @internal Use {@link BatchedRenderer.setDepthTexture}.
+     */
+    applyDepthTexture(depth: DepthBinding | BaseTexture | null): void {
+        if (depth instanceof BaseTexture) {
+            depth = {texture: depth, encoding: 'linear', packed: false};
+        }
+        const previous = this.depth;
+        this.depth = depth;
+        if (!this.settings.softParticles) {
+            return;
+        }
+        if (!previous !== !depth || previous?.packed !== depth?.packed) {
+            this.rebuildMaterial();
+            return;
+        }
         const material = this.mesh.material;
-        if (material && material instanceof ShaderMaterial) {
-            material.setTexture('depthTexture', depthTexture);
+        if (depth && material instanceof ShaderMaterial) {
+            material.setTexture('depthTexture', depth.texture);
+        }
+    }
+
+    /**
+     * Sets the soft-particle and alpha-test values on a material, and decodes the depth for the
+     * camera of each draw.
+     */
+    protected bindSoft(material: ShaderMaterial): void {
+        this.writeSoftParams(material);
+        if (this.drawsSoft()) {
+            material.setTexture('depthTexture', this.depth!.texture);
+            // Reused across binds: this runs on every draw call.
+            const projParams = new BVector4(1, 0, 0, 1);
+            material.onBindObservable.add(() => {
+                const camera = this.scene.activeCamera;
+                if (camera && this.depth) {
+                    softDepthParams(camera, this.depth.encoding, projParams);
+                    VFXBatch.writeBound(material, (target) => target.setVector4('projParams', projParams));
+                }
+            });
         }
     }
 
-    /** Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it. */
+    /** Writes the soft-particle fade and the alpha cutoff, the live parameters every mode shares. */
+    private writeSoftParams(material: ShaderMaterial): void {
+        if (this.drawsSoft()) {
+            material.setVector2(
+                'softParams',
+                new BVector2(
+                    this.settings.softNearFade,
+                    1.0 / Math.max(this.settings.softFarFade - this.settings.softNearFade, 0.0001)
+                )
+            );
+        }
+        if (this.settings.materialAlphaTest > 0) {
+            material.setFloat('alphaTest', this.settings.materialAlphaTest);
+        }
+    }
+
+    /** True when this batch draws soft particles: they are on and a depth texture is attached. */
+    protected drawsSoft(): boolean {
+        return this.settings.softParticles && this.depth !== null;
+    }
+
+    /**
+     * Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it.
+     * @internal Use {@link BatchedRenderer.setMeshLighting}.
+     */
     applyMeshLighting(_lighting: MeshLightingSettings): void {}
 
+    /** @internal */
     abstract setupBuffers(): void;
+    /** @internal */
     abstract expandBuffers(target: number): void;
+    /** @internal */
     abstract rebuildMaterial(): void;
+    /** @internal */
     abstract update(): void;
 
+    /** @internal */
     dispose(): void {
         this.mesh.dispose();
     }