babylon.quarks 0.26.0 → 0.28.0

package/src/BatchedRenderer.ts

@@ -4,72 +4,103 @@ import {Texture} from '@babylonjs/core/Materials/Textures/texture';
 import {Frustum} from '@babylonjs/core/Maths/math.frustum';
 import {Plane} from '@babylonjs/core/Maths/math.plane';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {DepthRenderer} from '@babylonjs/core/Rendering/depthRenderer';
 import {Scene} from '@babylonjs/core/scene';
 import {EmitSubParticleSystem, IParticleSystem, Vector3} from 'quarks.core';
+import {batchSettingsEqual, shaderKeyEqual, storedBatchSettings} from './batchKey';
 import {ParticleSystem} from './ParticleSystem';
+import {depthBinding, DepthBinding, DepthTextureOptions, SoftDepthEncoding} from './softDepth';
 import {SpriteBatch} from './SpriteBatch';
 import {TrailBatch} from './TrailBatch';
 import {
     defaultMeshLighting,
-    erosionEqual,
-    gradientMapEqual,
-    mapUVEqual,
     MeshLighting,
     MeshLightingSettings,
     MeshRim,
-    meshRimEqual,
     ParticleErosion,
     ParticleGradientMap,
     ParticleUVDistortion,
-    readsUV1,
+    RenderFace,
     RenderMode,
     SortMode,
-    StoredBatchSettings,
     TextureUV,
-    uvDistortionEqual,
     VFXBatch,
 } from './VFXBatch';
 
+/**
+ * Everything about a system that decides how it is drawn: {@link ParticleSystem.getRendererSettings}
+ * returns it, and the renderer draws systems whose settings match from one batch. Only the
+ * settings a render mode reads count: two billboards that differ in a mesh-only setting, such as
+ * `rim`, share a batch.
+ *
+ * A batch is one draw with one material, so its settings fall into two groups, as a Unity
+ * material's keywords and texture slots against its MaterialPropertyBlock values, or an Unreal
+ * material against a dynamic material instance's parameters. The shader key (render mode,
+ * geometry, textures, blend and depth state, and which effects are on) decides the material.
+ * The live parameters (the fade distances, alpha cutoff, pivot, size limits, reflection level,
+ * rim colour, each effect's numbers, and each texture's tiling, offset and scroll) are uniforms:
+ * changing one on a system that is alone in its batch writes the material in place, with no new
+ * batch or material. A texture's UV channel is part of the shader key, so changing it rebuilds.
+ *
+ * Prefer the system's own setters, which also move it to a matching batch; after changing a
+ * field directly, set {@link ParticleSystem.neededToUpdateRender}.
+ */
 export interface VFXBatchSettings {
+    /** Mesh particles' vertex positions, see {@link ParticleSystem.instancingGeometry}. A quad for other modes. */
     instancingGeometry: Float32Array;
+    /** Triangle indices into {@link instancingGeometry}. */
     instancingIndices: Uint32Array | Uint16Array;
+    /** The mesh's first UV set, two values per vertex. */
     instancingUVs?: Float32Array;
     /** The mesh's second UV set, see {@link UVChannel}. */
     instancingUVs2?: Float32Array;
+    /** The mesh's vertex normals; mesh particles fall back to +Z. */
     instancingNormals?: Float32Array;
+    /** See {@link ParticleSystem.renderMode}. */
     renderMode: RenderMode;
+    /** See {@link ParticleSystem.renderOrder}. */
     renderOrder: number;
+    /** See {@link ParticleSystem.uTileCount}. */
     uTileCount: number;
+    /** See {@link ParticleSystem.vTileCount}. */
     vTileCount: number;
+    /** See {@link ParticleSystem.blendTiles}; read with a sheet, and not by trails. */
     blendTiles: boolean;
+    /** See {@link ParticleSystem.softParticles}. */
     softParticles: boolean;
+    /** See {@link ParticleSystem.softNearFade}. */
     softNearFade: number;
+    /** See {@link ParticleSystem.softFarFade}. */
     softFarFade: number;
+    /** Babylon alpha mode, see {@link ParticleSystem.blending}. */
     materialBlendMode: number;
+    /** Whether the batch draws in the transparent pass. */
     materialTransparent: boolean;
+    /** Whether particles are hidden behind nearer geometry. */
     materialDepthTest: boolean;
+    /** Whether particles write depth. */
     materialDepthWrite: boolean;
+    /** Alpha below which a fragment is discarded; 0 discards nothing. */
     materialAlphaTest: number;
+    /** See {@link ParticleSystem.texture}. */
     texture: Texture | null;
     /**
-     * Cubemap (or other reflection texture) harvested from a Babylon material's
-     * `reflectionTexture`. Mesh batches sample it like StandardMaterial cubic
-     * reflection; other render modes ignore it.
+     * The reflection a mesh particle's material carries (a Babylon material's `reflectionTexture`
+     * or `environmentTexture`). It is not sampled itself: a cube texture is unfolded into
+     * {@link reflectionAtlas} once it has loaded and sampled from there; anything else is kept
+     * only to tell materials apart. Other render modes ignore it.
      */
     reflectionTexture: BaseTexture | null;
     /** Multiplier for the reflection sample — mirrors `texture.level`. */
     reflectionLevel: number;
     /**
-     * Optional six cube-face 2D textures (px,py,pz,nx,ny,nz). Prefer
-     * `reflectionAtlas` on iOS — many simultaneous face samplers still trip
-     * GL_INVALID_OPERATION on WebKit.
-     */
-    reflectionFaces: BaseTexture[] | null;
-    /**
-     * Single 3×2 atlas of cube faces (px py pz / nx ny nz). One sampler2D —
-     * the path that stays valid on iOS WebKit ShaderMaterial draws.
+     * A 3×2 atlas of cube faces (+X +Y +Z over -X -Y -Z) that mesh particles reflect, through one
+     * `sampler2D`: the path that stays valid on iOS WebKit ShaderMaterial draws, where a
+     * `samplerCube` or six face samplers raise GL_INVALID_OPERATION. Built from
+     * {@link reflectionTexture} when that is a cube texture. Other render modes ignore it.
      */
     reflectionAtlas: BaseTexture | null;
+    /** Camera layer mask of the batch mesh, see {@link ParticleSystem.layers}. */
     layerMask: number;
     /**
      * Babylon rendering group (`mesh.renderingGroupId`) the batch draws in,
@@ -78,8 +109,13 @@ export interface VFXBatchSettings {
     renderingGroupId: number;
     /**
      * Whether the scene's fog applies to the particles, as it does to any other
-     * mesh; true by default. Additive particles fade toward black rather than
-     * the fog colour. Systems that differ are batched apart.
+     * mesh; true by default. Particles that lay over the frame (`ALPHA_COMBINE`,
+     * `ALPHA_PREMULTIPLIED`, opaque ones) mix toward the fog colour; particles
+     * that add to it or subtract from it (`ALPHA_ADD`, `ALPHA_ONEONE`,
+     * `ALPHA_SCREENMODE`, `ALPHA_SUBTRACT`, …) fade toward black, since the fog
+     * colour would fog the whole screen; particles that multiply it
+     * (`ALPHA_MULTIPLY`) fade toward white. See {@link blendCategory}. Systems
+     * that differ are batched apart.
      */
     applyFog: boolean;
     /**
@@ -92,6 +128,11 @@ export interface VFXBatchSettings {
     pivot?: Vector3;
     /** Draw order within the batch, see {@link SortMode}. Unset is `'none'`. Systems that differ are batched apart. */
     sortMode?: SortMode;
+    /**
+     * Which faces a mesh particle draws, see {@link RenderFace}. Unset is `'both'`. Mesh systems
+     * that differ are batched apart; other render modes ignore it.
+     */
+    renderFace?: RenderFace;
     /**
      * Smallest size a billboard or stretched particle may have on screen, as a
      * fraction of the viewport height (Unity's Min Particle Size); 0 by default.
@@ -121,47 +162,70 @@ export interface VFXBatchSettings {
     erosion?: ParticleErosion;
 }
 
+/**
+ * How {@link BatchedRenderer.configureAdaptivePerformance} trades particles for frame time: each
+ * update that runs over `targetFrameMs` lowers every system's quality factor (see
+ * {@link ParticleSystem.setQualityFactor}) by `decreaseStep`, each one under it raises the factor
+ * by `increaseStep`, within `minQuality` and `maxQuality`.
+ */
 export interface AdaptivePerformanceOptions {
+    /** CPU time in milliseconds the renderer's update may take before quality drops. Default 16.7. */
     targetFrameMs: number;
+    /** Lowest quality factor, 0.1 to 1 ({@link ParticleSystem.setQualityFactor} clamps lower values). Default 0.35. */
     minQuality: number;
+    /** Highest quality factor, `minQuality` to 1. Default 1. */
     maxQuality: number;
+    /** Quality lost per update over budget. Default 0.08. */
     decreaseStep: number;
+    /** Quality regained per update within budget. Default 0.02. */
     increaseStep: number;
 }
 
-/** True when both pivots put the quad in the same place; a missing pivot is zero. */
-function pivotEqual(a: Vector3 | undefined, b: Vector3 | undefined): boolean {
-    return (a?.x ?? 0) === (b?.x ?? 0) && (a?.y ?? 0) === (b?.y ?? 0) && (a?.z ?? 0) === (b?.z ?? 0);
-}
-
-/** True when both face lists are the same six texture references (or both empty). */
-function reflectionFacesEqual(a: BaseTexture[] | null | undefined, b: BaseTexture[] | null | undefined): boolean {
-    if (a === b) {
-        return true;
-    }
-    if (!a || !b || a.length !== b.length) {
-        return false;
-    }
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] !== b[i]) {
-            return false;
-        }
-    }
-    return true;
-}
-
+/** A snapshot of the renderer's adaptive performance, from {@link BatchedRenderer.getAdaptivePerformanceState}. */
 export interface AdaptivePerformanceState extends AdaptivePerformanceOptions {
+    /** Whether adaptive performance is on. */
     enabled: boolean;
+    /** The quality factor the systems run at now. */
     currentQuality: number;
+    /** CPU time the last measured update took, in milliseconds; kept from the last update while off. */
     lastFrameCpuMs: number;
 }
 
+/**
+ * Draws particle systems, batching the ones that draw alike into one instanced mesh each, and
+ * advances them every frame. It is a node in the scene; make one per scene, add each system with
+ * {@link addSystem}, and call {@link update} once per frame:
+ *
+ * ```ts
+ * const renderer = new BatchedRenderer('particles', scene);
+ * renderer.addSystem(system);
+ * scene.onBeforeRenderObservable.add(() => renderer.update(scene.getEngine().getDeltaTime() / 1000));
+ * ```
+ *
+ * Systems step on a fixed 60 Hz clock, so an effect plays out the same at any frame rate.
+ *
+ * The renderer is a node so the batches have a parent to live under: disabling it hides them,
+ * disposing it disposes them. Its transform moves nothing: particles are placed in the world by
+ * their emitters, and the batch meshes draw them there whatever the renderer's position, rotation
+ * or scale. A system belongs to one renderer at a time: adding it to another takes it out of the
+ * first.
+ */
 export class BatchedRenderer extends TransformNode {
-    batches: Array<VFXBatch> = [];
+    private readonly batchList: Array<VFXBatch> = [];
+    private readonly batchIndexOf = new Map<IParticleSystem, number>();
+
+    /** The batches, one draw each, to inspect what is drawn; the renderer makes and frees them. */
+    get batches(): ReadonlyArray<VFXBatch> {
+        return this.batchList;
+    }
+
+    /** Index into {@link batches} of each system's batch, to inspect; the renderer keeps it. */
+    get systemToBatchIndex(): ReadonlyMap<IParticleSystem, number> {
+        return this.batchIndexOf;
+    }
     /** Seconds this renderer has been updated for; the clock UV and erosion scrolling run on. */
     private elapsed = 0;
-    systemToBatchIndex: Map<IParticleSystem, number> = new Map<IParticleSystem, number>();
-    depthTexture: BaseTexture | null = null;
+    private depth: DepthBinding | null = null;
     /** Systems in insertion order — iterated every frame, unlike the map. */
     private systems: Array<IParticleSystem> = [];
     /**
@@ -223,8 +287,12 @@ export class BatchedRenderer extends TransformNode {
      */
     simulationBudgetMs = Infinity;
 
-    /** Frustum planes of the active cameras, six per camera, rebuilt each update. */
-    private frustumPlanes: Plane[] = [];
+    /** Frustum planes of each active camera, six per camera, reused across updates. */
+    private readonly cameraPlanes: Plane[][] = [];
+    /** Each active camera's `layerMask`, parallel to {@link cameraPlanes}. */
+    private readonly cameraMasks: number[] = [];
+    /** How many cameras {@link cameraPlanes} holds this update. */
+    private cameraCount = 0;
     private readonly boundsMin = new Vector3();
     private readonly boundsMax = new Vector3();
 
@@ -233,21 +301,16 @@ export class BatchedRenderer extends TransformNode {
     }
 
     /**
-     * Gathers the frustum planes of the cameras the scene renders with, six per
-     * camera. Empty when there is no camera yet; systems are then never culled.
+     * Gathers the frustum planes and layer masks of the cameras the scene renders with, and returns
+     * how many. 0 when there is no camera yet; systems are then never culled. Allocates only when a
+     * camera is added.
      */
-    private collectFrustumPlanes(): Plane[] {
+    private collectCameras(): number {
         const scene = this.getScene();
-        const planes = this.frustumPlanes;
         const activeCameras = scene.activeCameras;
         const activeCamera = scene.activeCamera;
-        const cameras: Camera[] =
+        const cameras: readonly Camera[] =
             activeCameras && activeCameras.length > 0 ? activeCameras : activeCamera ? [activeCamera] : [];
-        const needed = cameras.length * 6;
-        while (planes.length < needed) {
-            planes.push(new Plane(0, 0, 0, 0));
-        }
-        planes.length = needed;
         for (let c = 0; c < cameras.length; c++) {
             const camera = cameras[c];
             // Both matrices are recomputed only on demand: a camera moved since
@@ -255,31 +318,33 @@ export class BatchedRenderer extends TransformNode {
             // that has not rendered yet has no projection at all.
             camera.getViewMatrix();
             camera.getProjectionMatrix();
-            const transform = camera.getTransformationMatrix();
-            const slice = c === 0 ? planes : planes.slice(c * 6, c * 6 + 6);
-            Frustum.GetPlanesToRef(transform, slice);
-            if (c !== 0) {
-                for (let p = 0; p < 6; p++) {
-                    planes[c * 6 + p] = slice[p];
-                }
-            }
+            const planes = (this.cameraPlanes[c] ??= [0, 1, 2, 3, 4, 5].map(() => new Plane(0, 0, 0, 0)));
+            Frustum.GetPlanesToRef(camera.getTransformationMatrix(), planes);
+            this.cameraMasks[c] = camera.layerMask;
         }
-        return planes;
+        this.cameraCount = cameras.length;
+        return cameras.length;
     }
 
     /**
-     * True when `system`'s world bounds reach into at least one camera's
-     * frustum, or when it has no bounds to test (empty, or not yet measured).
+     * True when `system`'s world bounds reach into the frustum of at least one camera whose
+     * `layerMask` shares a bit with the system's (a camera that does not render the system's layer
+     * does not see it), or when it has no bounds to test (empty, or not yet measured).
      */
-    private isSystemInView(system: ParticleSystem, planes: Plane[]): boolean {
+    private isSystemInView(system: ParticleSystem): boolean {
         const min = this.boundsMin;
         const max = this.boundsMax;
         if (!system.getWorldBounds(min, max)) {
             return true;
         }
-        for (let c = 0; c < planes.length; c += 6) {
+        const layerMask = system.layers.mask;
+        for (let c = 0; c < this.cameraCount; c++) {
+            if ((this.cameraMasks[c] & layerMask) === 0) {
+                continue;
+            }
+            const planes = this.cameraPlanes[c];
             let inside = true;
-            for (let p = c; p < c + 6; p++) {
+            for (let p = 0; p < 6; p++) {
                 const plane = planes[p];
                 const n = plane.normal;
                 // The box corner farthest along the plane's normal: if even it
@@ -303,52 +368,29 @@ export class BatchedRenderer extends TransformNode {
         return Math.max(min, Math.min(max, value));
     }
 
-    private static equals(a: StoredBatchSettings, b: VFXBatchSettings): boolean {
-        return (
-            a.materialBlendMode === b.materialBlendMode &&
-            a.materialTransparent === b.materialTransparent &&
-            a.materialDepthTest === b.materialDepthTest &&
-            a.materialDepthWrite === b.materialDepthWrite &&
-            a.materialAlphaTest === b.materialAlphaTest &&
-            a.texture === b.texture &&
-            a.reflectionTexture === b.reflectionTexture &&
-            a.reflectionLevel === b.reflectionLevel &&
-            reflectionFacesEqual(a.reflectionFaces, b.reflectionFaces) &&
-            a.reflectionAtlas === b.reflectionAtlas &&
-            a.renderMode === b.renderMode &&
-            a.blendTiles === b.blendTiles &&
-            a.softParticles === b.softParticles &&
-            a.softFarFade === b.softFarFade &&
-            a.softNearFade === b.softNearFade &&
-            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 &&
-            a.applyFog === b.applyFog &&
-            pivotEqual(a.pivot, b.pivot) &&
-            a.sortMode === (b.sortMode ?? 'none') &&
-            a.minParticleSize === (b.minParticleSize ?? 0) &&
-            a.maxParticleSize === (b.maxParticleSize ?? Infinity) &&
-            (a.lighting ?? 'fixed') === (b.lighting ?? 'fixed') &&
-            meshRimEqual(a.rim, b.rim) &&
-            mapUVEqual(a.mapUV, b.mapUV) &&
-            uvDistortionEqual(a.uvDistortion, b.uvDistortion) &&
-            gradientMapEqual(a.gradientMap, b.gradientMap) &&
-            erosionEqual(a.erosion, b.erosion)
-        );
-    }
-
-    addSystem(system: IParticleSystem) {
+    /**
+     * Starts drawing and updating `system`, in the batch whose settings match its own (a new one if
+     * none does). Add each system of an effect, or use `QuarksUtil.addToBatchRenderer` on its root.
+     */
+    addSystem(system: IParticleSystem): void {
+        if (this.isDisposed()) {
+            throw new Error('BatchedRenderer.addSystem: the renderer has been disposed');
+        }
         const particleSystem = system as ParticleSystem;
+        if (particleSystem.emitter.getScene() !== this.getScene()) {
+            // Its batch would hold meshes and materials of two scenes.
+            throw new Error('BatchedRenderer.addSystem: the system belongs to another scene');
+        }
+        const previous = particleSystem._renderer;
+        if (previous !== undefined && previous !== this) {
+            // One renderer at a time, or two would step and draw it.
+            previous.deleteSystem(system);
+        }
         particleSystem._renderer = this;
-        if (!this.systemToBatchIndex.has(system) && this.systems.indexOf(system) === -1) {
+        // Added again after its settings changed: out of the old batch first, so it lands in the
+        // one that matches now rather than in both.
+        this.removeFromBatch(system);
+        if (this.systems.indexOf(system) === -1) {
             this.systems.push(system);
             this.orderedSystemsStale = true;
         }
@@ -362,10 +404,11 @@ export class BatchedRenderer extends TransformNode {
     private assignToBatch(particleSystem: ParticleSystem) {
         const system = particleSystem as IParticleSystem;
         const settings = particleSystem.getRendererSettings();
-        for (let i = 0; i < this.batches.length; i++) {
-            if (BatchedRenderer.equals(this.batches[i].settings, settings)) {
-                this.batches[i].addSystem(system);
-                this.systemToBatchIndex.set(system, i);
+        const stored = storedBatchSettings(settings);
+        for (let i = 0; i < this.batchList.length; i++) {
+            if (batchSettingsEqual(this.batchList[i].settings, stored)) {
+                this.batchList[i].addSystem(system);
+                this.batchIndexOf.set(system, i);
                 return;
             }
         }
@@ -373,7 +416,7 @@ export class BatchedRenderer extends TransformNode {
         const scene = this.getScene();
         switch (settings.renderMode) {
             case RenderMode.Trail:
-                batch = new TrailBatch(settings, scene);
+                batch = new TrailBatch(settings, scene, this.depth);
                 break;
             case RenderMode.Mesh:
             case RenderMode.BillBoard:
@@ -381,23 +424,24 @@ export class BatchedRenderer extends TransformNode {
             case RenderMode.HorizontalBillBoard:
             case RenderMode.StretchedBillBoard:
             case RenderMode.Beam:
-                batch = new SpriteBatch(settings, scene);
+                batch = new SpriteBatch(settings, scene, this.depth);
                 break;
             default:
                 throw new Error(`Unsupported render mode: ${settings.renderMode}`);
         }
-        batch.mesh.parent = this;
-        if (this.depthTexture) {
-            batch.applyDepthTexture(this.depthTexture);
-        }
+        batch.attachTo(this);
         batch.applyMeshLighting(this.meshLighting);
         batch.addSystem(system);
-        this.batches.push(batch);
+        this.batchList.push(batch);
         this.batchEmptyFrames.push(0);
-        this.systemToBatchIndex.set(system, this.batches.length - 1);
+        this.batchIndexOf.set(system, this.batchList.length - 1);
     }
 
-    deleteSystem(system: IParticleSystem) {
+    /**
+     * Stops drawing and updating `system`; disposing the system calls it. Its particles are left as they are.
+     * @returns Whether the system was in one of this renderer's batches.
+     */
+    deleteSystem(system: IParticleSystem): boolean {
         const removed = this.removeFromBatch(system);
         const index = this.systems.indexOf(system);
         if (index !== -1) {
@@ -416,31 +460,76 @@ export class BatchedRenderer extends TransformNode {
 
     /** Detaches a system from its batch, leaving the renderer's system list alone. */
     private removeFromBatch(system: IParticleSystem): boolean {
-        const batchIndex = this.systemToBatchIndex.get(system);
+        const batchIndex = this.batchIndexOf.get(system);
         if (batchIndex === undefined) {
             return false;
         }
-        this.batches[batchIndex].removeSystem(system);
-        this.systemToBatchIndex.delete(system);
+        this.batchList[batchIndex].removeSystem(system);
+        this.batchIndexOf.delete(system);
         return true;
     }
 
     /**
-     * Re-buckets a system whose render settings changed. The system keeps its
-     * place in the update order, so this is safe to call mid-frame.
+     * Takes a system's changed render settings. When only live parameters changed (see
+     * {@link VFXBatchSettings}) and the system is alone in its batch, the batch's material is
+     * written in place. Otherwise the system moves to the batch its settings now match. The
+     * system keeps its place in the update order, so this is safe to call mid-frame.
      */
     updateSystem(system: IParticleSystem) {
+        const batchIndex = this.batchIndexOf.get(system);
+        if (batchIndex !== undefined) {
+            const batch = this.batchList[batchIndex];
+            const settings = storedBatchSettings((system as ParticleSystem).getRendererSettings());
+            if (
+                batch.systems.size === 1 &&
+                shaderKeyEqual(batch.settings, settings) &&
+                // A batch that already draws with these values takes the system instead, so two
+                // batches never hold the same settings.
+                !this.batchList.some((other) => other !== batch && batchSettingsEqual(other.settings, settings))
+            ) {
+                batch.applyLiveSettings(settings);
+                return;
+            }
+        }
         this.removeFromBatch(system);
         this.addSystem(system);
     }
 
-    setDepthTexture(depthTexture: BaseTexture | null) {
-        this.depthTexture = depthTexture;
-        for (const batch of this.batches) {
-            batch.applyDepthTexture(depthTexture);
+    /**
+     * Sets the scene depth that soft particles fade against. Without one, soft particles are not
+     * compiled in and draw hard, as Unity does for a camera with no depth texture.
+     *
+     * Pass the `DepthRenderer` itself to have its encoding read off it, for example
+     * `renderer.setDepthTexture(scene.enableDepthRenderer(camera))`. A bare texture is read as
+     * Babylon's default `'linear'` metric unless `options.encoding` says otherwise; see
+     * {@link SoftDepthEncoding}. The depth should be drawn by the camera that draws the particles.
+     * The texture is held, not the renderer: set it again if the `DepthRenderer` is disposed or
+     * replaced.
+     *
+     * @param depth - A depth texture, a Babylon `DepthRenderer`, or null to turn soft particles off.
+     * @param options - What the texture stores, when it cannot be read off a `DepthRenderer`.
+     */
+    setDepthTexture(depth: BaseTexture | DepthRenderer | null, options: DepthTextureOptions = {}) {
+        this.depth = depth ? depthBinding(depth, options) : null;
+        for (const batch of this.batchList) {
+            batch.applyDepthTexture(this.depth);
         }
     }
 
+    /** The depth texture soft particles fade against, see {@link setDepthTexture}. */
+    get depthTexture(): BaseTexture | null {
+        return this.depth?.texture ?? null;
+    }
+
+    set depthTexture(texture: BaseTexture | null) {
+        this.setDepthTexture(texture);
+    }
+
+    /** What the depth texture stores, see {@link setDepthTexture}. */
+    get depthEncoding(): SoftDepthEncoding | null {
+        return this.depth?.encoding ?? null;
+    }
+
     /**
      * Sets the light mesh particles with `lighting: 'fixed'` (the default) are
      * lit by, for every mesh batch of this renderer, including ones created
@@ -463,7 +552,7 @@ export class BatchedRenderer extends TransformNode {
         if (lighting.ambient) {
             current.ambient = lighting.ambient.clone();
         }
-        for (const batch of this.batches) {
+        for (const batch of this.batchList) {
             batch.applyMeshLighting(current);
         }
     }
@@ -478,9 +567,14 @@ export class BatchedRenderer extends TransformNode {
         };
     }
 
-    configureAdaptivePerformance(options: Partial<AdaptivePerformanceOptions> = {}) {
+    /**
+     * Turns on adaptive performance: the renderer measures its own update and thins every system's
+     * emission while it runs over budget, see {@link AdaptivePerformanceOptions}. Options left out
+     * keep their current values.
+     */
+    configureAdaptivePerformance(options: Partial<AdaptivePerformanceOptions> = {}): void {
         const state = this.adaptivePerformanceState;
-        const minQuality = BatchedRenderer.clamp(options.minQuality ?? state.minQuality, 0.05, 1);
+        const minQuality = BatchedRenderer.clamp(options.minQuality ?? state.minQuality, 0.1, 1);
         const maxQuality = BatchedRenderer.clamp(options.maxQuality ?? state.maxQuality, minQuality, 1);
         state.targetFrameMs = Math.max(options.targetFrameMs ?? state.targetFrameMs, 0.1);
         state.minQuality = minQuality;
@@ -492,7 +586,8 @@ export class BatchedRenderer extends TransformNode {
         this.lastAppliedQuality = Number.NaN;
     }
 
-    disableAdaptivePerformance(resetQuality = true) {
+    /** Turns adaptive performance off, and by default puts every system back at `maxQuality`. */
+    disableAdaptivePerformance(resetQuality = true): void {
         this.adaptivePerformanceState.enabled = false;
         if (resetQuality) {
             this.adaptivePerformanceState.currentQuality = this.adaptivePerformanceState.maxQuality;
@@ -500,6 +595,7 @@ export class BatchedRenderer extends TransformNode {
         }
     }
 
+    /** A copy of the adaptive performance settings and the current quality. */
     getAdaptivePerformanceState(): AdaptivePerformanceState {
         return {...this.adaptivePerformanceState};
     }
@@ -543,7 +639,9 @@ export class BatchedRenderer extends TransformNode {
                 if (behavior.type !== 'EmitSubParticleSystem') {
                     continue;
                 }
-                const target = (behavior as EmitSubParticleSystem).subParticleSystem?.system;
+                // A uuid string is a link the loader could not resolve: no target.
+                const sub = (behavior as EmitSubParticleSystem).subParticleSystem;
+                const target = typeof sub === 'object' ? sub.system : undefined;
                 if (target !== undefined && known.has(target)) {
                     targets.push(target);
                 }
@@ -573,7 +671,12 @@ export class BatchedRenderer extends TransformNode {
         return ordered;
     }
 
-    update(delta: number) {
+    /**
+     * Advances every visible system by `delta` seconds and refills the batches. Call it once per
+     * frame. A system whose emitter is disabled is frozen; one no camera sees pauses if its
+     * {@link ParticleSystem.cullingMode} says so.
+     */
+    update(delta: number): void {
         this.elapsed += delta;
         const adaptiveState = this.adaptivePerformanceState;
         const frameStart = adaptiveState.enabled ? performance.now() : 0;
@@ -581,7 +684,7 @@ export class BatchedRenderer extends TransformNode {
             this.applyAdaptiveQuality();
         }
         const systems = this.orderSystems();
-        const planes = this.cullingEnabled ? this.collectFrustumPlanes() : null;
+        const cameraCount = this.cullingEnabled ? this.collectCameras() : 0;
         const budgetStart =
             this.simulationBudgetMs !== Infinity || this.catchUpBudgetMs !== Infinity ? performance.now() : 0;
         const stepDeadline = this.simulationBudgetMs === Infinity ? Infinity : budgetStart + this.simulationBudgetMs;
@@ -595,11 +698,10 @@ export class BatchedRenderer extends TransformNode {
                 // A system no camera sees pauses, by its own choice. One that
                 // only serves as a sub emitter target follows its parent.
                 system.culled =
-                    planes !== null &&
-                    planes.length > 0 &&
+                    cameraCount > 0 &&
                     system.cullingMode !== 'always' &&
                     system.onlyUsedByOther !== true &&
-                    !this.isSystemInView(system, planes);
+                    !this.isSystemInView(system);
                 system.update(delta, stepDeadline, catchUpDeadline);
             }
             // An autoDestroy system disposes itself from inside update and drops
@@ -632,8 +734,8 @@ export class BatchedRenderer extends TransformNode {
     /** Rebuild instance buffers from current particle state without advancing simulation. */
     refreshBatches(): void {
         const emptyFrames = this.batchEmptyFrames;
-        for (let i = 0; i < this.batches.length; i++) {
-            const batch = this.batches[i];
+        for (let i = 0; i < this.batchList.length; i++) {
+            const batch = this.batchList[i];
             batch.time = this.elapsed;
             if (batch.systems.size > 0) {
                 emptyFrames[i] = 0;
@@ -657,25 +759,30 @@ export class BatchedRenderer extends TransformNode {
 
     /** Disposes the batch at `index` and repairs the system→batch mapping. */
     private removeBatch(index: number): void {
-        this.batches[index].dispose();
-        this.batches.splice(index, 1);
+        this.batchList[index].dispose();
+        this.batchList.splice(index, 1);
         this.batchEmptyFrames.splice(index, 1);
-        for (const [system, batchIndex] of this.systemToBatchIndex) {
+        for (const [system, batchIndex] of this.batchIndexOf) {
             if (batchIndex > index) {
-                this.systemToBatchIndex.set(system, batchIndex - 1);
+                this.batchIndexOf.set(system, batchIndex - 1);
             }
         }
     }
 
     /** Per-batch particle vs GPU instance counts — for diagnosing stale render state. */
     getBatchRenderStats(): Array<{
+        /** Index into {@link batches}. */
         batchIndex: number;
+        /** The batch's render mode. */
         renderMode: RenderMode;
+        /** Instances the batch mesh draws. */
         instanceCount: number;
+        /** Live particles of the batch's systems. */
         particleCount: number;
+        /** The emitter names of the batch's systems. */
         systemNames: string[];
     }> {
-        return this.batches.map((batch, batchIndex) => {
+        return this.batchList.map((batch, batchIndex) => {
             let particleCount = 0;
             const systemNames: string[] = [];
             for (const system of batch.systems) {
@@ -693,14 +800,25 @@ export class BatchedRenderer extends TransformNode {
         });
     }
 
+    /**
+     * Disposes the batches and their meshes and materials, and lets the systems go: they keep
+     * their particles and can be added to another renderer. The renderer cannot be used again.
+     */
     dispose(): void {
-        for (const batch of this.batches) {
+        for (const batch of this.batchList) {
             batch.dispose();
         }
-        this.batches = [];
+        this.batchList.length = 0;
         this.batchEmptyFrames.length = 0;
+        for (const system of this.systems) {
+            if ((system as ParticleSystem)._renderer === this) {
+                (system as ParticleSystem)._renderer = undefined;
+            }
+        }
         this.systems.length = 0;
-        this.systemToBatchIndex.clear();
+        this.orderedSystems = [];
+        this.orderedSystemsStale = true;
+        this.batchIndexOf.clear();
         super.dispose();
     }
 }