babylon.quarks 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "babylon.quarks",
-    "version": "0.26.0",
+    "version": "0.27.0",
     "description": "A High-Performance Particle System for Babylon.js",
     "type": "module",
     "types": "./dist/types/index.d.ts",
@@ -10,10 +10,16 @@
     "jsdelivr": "./dist/babylon.quarks.umd.min.js",
     "exports": {
         ".": {
-            "import": "./dist/babylon.quarks.esm.js",
-            "require": "./dist/babylon.quarks.cjs",
-            "types": "./dist/types/index.d.ts"
-        }
+            "import": {
+                "types": "./dist/types/index.d.ts",
+                "default": "./dist/babylon.quarks.esm.js"
+            },
+            "require": {
+                "types": "./dist/types/index.d.cts",
+                "default": "./dist/babylon.quarks.cjs"
+            }
+        },
+        "./package.json": "./package.json"
     },
     "files": [
         "dist",
@@ -29,7 +35,7 @@
         "build": "npm run clean && npm run build:types && npm run build:js",
         "test": "jest",
         "docs": "typedoc",
-        "test:coverage": "jest --coverage",
+        "docs:check": "typedoc --out node_modules/.cache/typedoc-check",
         "prettier": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\""
     },
     "repository": {

package/src/BatchedRenderer.ts

@@ -4,72 +4,102 @@ 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,
     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 +108,11 @@ 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 add to the frame (`ALPHA_ADD`,
+     * `ALPHA_ONEONE`) fade toward black rather than the fog colour, which would
+     * fog the whole screen; every other blend mode mixes toward the fog colour,
+     * which is right for alpha blending and only approximate for a multiply or
+     * subtract. Systems that differ are batched apart.
      */
     applyFog: boolean;
     /**
@@ -121,47 +154,63 @@ 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; leave it at the origin,
+ * unturned and unscaled. Particles are placed in the world by their emitters, and a transform on
+ * the renderer would move every one of them again (it warns once when it finds one). A system
+ * belongs to one renderer at a time: adding it to another takes it out of the first.
+ */
 export class BatchedRenderer extends TransformNode {
+    /** Whether the renderer has warned about its own transform; see the class description. */
+    private warnedAboutTransform = false;
+    /** The batches, one draw each. Read to inspect what is drawn; the renderer owns them. */
     batches: Array<VFXBatch> = [];
     /** Seconds this renderer has been updated for; the clock UV and erosion scrolling run on. */
     private elapsed = 0;
+    /** Index into {@link batches} of each system's batch. The renderer owns it. */
     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> = [];
     /**
@@ -303,52 +352,25 @@ 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;
+        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,8 +384,9 @@ export class BatchedRenderer extends TransformNode {
     private assignToBatch(particleSystem: ParticleSystem) {
         const system = particleSystem as IParticleSystem;
         const settings = particleSystem.getRendererSettings();
+        const stored = storedBatchSettings(settings);
         for (let i = 0; i < this.batches.length; i++) {
-            if (BatchedRenderer.equals(this.batches[i].settings, settings)) {
+            if (batchSettingsEqual(this.batches[i].settings, stored)) {
                 this.batches[i].addSystem(system);
                 this.systemToBatchIndex.set(system, i);
                 return;
@@ -373,7 +396,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,15 +404,12 @@ 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.applyMeshLighting(this.meshLighting);
         batch.addSystem(system);
         this.batches.push(batch);
@@ -397,7 +417,11 @@ export class BatchedRenderer extends TransformNode {
         this.systemToBatchIndex.set(system, this.batches.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) {
@@ -426,21 +450,66 @@ export class BatchedRenderer extends TransformNode {
     }
 
     /**
-     * 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.systemToBatchIndex.get(system);
+        if (batchIndex !== undefined) {
+            const batch = this.batches[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.batches.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;
+    /**
+     * 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.batches) {
-            batch.applyDepthTexture(depthTexture);
+            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
@@ -478,7 +547,12 @@ 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 maxQuality = BatchedRenderer.clamp(options.maxQuality ?? state.maxQuality, minQuality, 1);
@@ -492,7 +566,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 +575,7 @@ export class BatchedRenderer extends TransformNode {
         }
     }
 
+    /** A copy of the adaptive performance settings and the current quality. */
     getAdaptivePerformanceState(): AdaptivePerformanceState {
         return {...this.adaptivePerformanceState};
     }
@@ -573,8 +649,19 @@ 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;
+        if (!this.warnedAboutTransform && !this.getWorldMatrix().isIdentity()) {
+            this.warnedAboutTransform = true;
+            console.warn(
+                `[babylon.quarks] BatchedRenderer "${this.name}" is transformed; particles are placed in the world by their emitters, so the renderer's own transform moves them again. Keep the renderer at the origin.`
+            );
+        }
         const adaptiveState = this.adaptivePerformanceState;
         const frameStart = adaptiveState.enabled ? performance.now() : 0;
         if (adaptiveState.enabled) {
@@ -669,10 +756,15 @@ export class BatchedRenderer extends TransformNode {
 
     /** 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) => {
@@ -693,13 +785,24 @@ 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) {
             batch.dispose();
         }
         this.batches = [];
         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.orderedSystems = [];
+        this.orderedSystemsStale = true;
         this.systemToBatchIndex.clear();
         super.dispose();
     }

package/src/EffectPool.ts

@@ -2,9 +2,11 @@ import {Vector3} from '@babylonjs/core/Maths/math.vector';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Node} from '@babylonjs/core/node';
 import {BatchedRenderer} from './BatchedRenderer';
+import {disposeEffect} from './effectResources';
 import {ParticleSystem} from './ParticleSystem';
 import {QuarksUtil} from './QuarksUtil';
 
+/** Options for a new {@link EffectPool}. */
 export interface EffectPoolOptions {
     /** The renderer every copy the pool makes is added to. */
     renderer: BatchedRenderer;
@@ -146,7 +148,8 @@ export class EffectPool {
             system.dispose();
         }
         this.systemsOf.delete(copy);
-        copy.dispose();
+        // Lets go of the textures the copy shares with the template.
+        disposeEffect(copy);
     }
 
     /** The copy a system belongs to is done when all of its systems are. */

package/src/MeshSurfaceEmitter.ts

@@ -1,8 +1,18 @@
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {EmitterShape, IParticleSystem, Particle, Plugin, random, ShapeJSON, ShapeTransform, Vector3} from 'quarks.core';
-
+import {quarksNodeId} from './nodeId';
+
+/**
+ * Emits from the surface of a Babylon mesh (Unity's Shape: Mesh, Unreal's Skeletal/Static Mesh
+ * Location): a point picked at random over the triangles, weighted by their area, moving along the
+ * triangle's normal at the particle's start speed. The mesh's vertices are read once, when it is
+ * set, in the mesh's own space, and laid in the emitter's space as they are, moved by
+ * {@link transform}; moving the mesh node afterwards does not move the shape. A shape without a
+ * mesh emits from the origin along +Z.
+ */
 export class MeshSurfaceEmitter implements EmitterShape {
+    /** The shape's type in effect files. */
     type = 'mesh_surface';
 
     private _triangleIndexToArea: number[] = [];
@@ -13,12 +23,16 @@ export class MeshSurfaceEmitter implements EmitterShape {
     /** Offset, rotation and scale of the mesh within the particle system. */
     transform?: ShapeTransform;
 
-    get mesh() {
+    /** The mesh emitted from. Setting it reads its positions and indices; a mesh without both emits from the origin. */
+    get mesh(): Mesh | undefined {
         return this._mesh;
     }
 
     set mesh(mesh: Mesh | undefined) {
         this._mesh = mesh;
+        this._positions = undefined;
+        this._indices = undefined;
+        this._triangleIndexToArea.length = 0;
         if (!mesh) return;
 
         const positions = mesh.getVerticesData(VertexBuffer.PositionKind);
@@ -55,13 +69,19 @@ export class MeshSurfaceEmitter implements EmitterShape {
         }
     }
 
+    /**
+     * @param mesh The mesh to emit from.
+     * @param meshReferenceId The id of a mesh node in the effect file, kept until the loader links it.
+     * @param transform Offset, rotation and scale of the mesh within the system.
+     */
     constructor(mesh?: Mesh, meshReferenceId?: string, transform?: ShapeTransform) {
         this._meshReferenceId = meshReferenceId;
         this.transform = transform;
         if (mesh) this.mesh = mesh;
     }
 
-    initialize(p: Particle) {
+    /** Places a new particle on the surface and sets its velocity along the triangle's normal. */
+    initialize(p: Particle): void {
         if (!this._positions || !this._indices) {
             p.position.set(0, 0, 0);
             p.velocity.set(0, 0, 1).multiplyScalar(p.startSpeed);
@@ -114,25 +134,30 @@ export class MeshSurfaceEmitter implements EmitterShape {
         this.transform?.apply(p);
     }
 
+    /** The shape in effect-file form; the mesh is written as its node id. */
     toJSON(): ShapeJSON {
         return {
             type: 'mesh_surface',
-            mesh: this._mesh ? (this._mesh as any).uniqueId?.toString() : (this._meshReferenceId ?? ''),
+            mesh: this._mesh ? quarksNodeId(this._mesh) : (this._meshReferenceId ?? ''),
             ...ShapeTransform.toShapeJSON(this.transform),
         };
     }
 
+    /** Reads {@link toJSON} output; the mesh stays an id until `QuarksLoader` links it. */
     static fromJSON(json: any): MeshSurfaceEmitter {
         return new MeshSurfaceEmitter(undefined, json?.mesh, ShapeTransform.fromJSON(json?.transform));
     }
 
+    /** A copy emitting from the same mesh. */
     clone(): EmitterShape {
         return new MeshSurfaceEmitter(this._mesh, this._meshReferenceId, this.transform?.clone());
     }
 
+    /** Does nothing: the shape keeps no state between steps. */
     update(_system: IParticleSystem, _delta: number): void {}
 }
 
+/** Registers {@link MeshSurfaceEmitter} with quarks.core's shape table; loaded when the package is imported. */
 export const MeshSurfaceEmitterPlugin: Plugin = {
     id: 'babylon.quarks',
     initialize: () => {},