babylon.quarks 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "babylon.quarks",
-    "version": "0.27.0",
+    "version": "0.29.0",
     "description": "A High-Performance Particle System for Babylon.js",
     "type": "module",
     "types": "./dist/types/index.d.ts",
@@ -28,6 +28,11 @@
         "README.md",
         "CHANGELOG.md"
     ],
+    "sideEffects": [
+        "./dist/babylon.quarks.esm.js",
+        "./dist/babylon.quarks.cjs",
+        "./dist/babylon.quarks.umd.min.js"
+    ],
     "scripts": {
         "clean": "rimraf dist dist-types tsconfig.tsbuildinfo",
         "build:types": "tsc --emitDeclarationOnly",
@@ -66,7 +71,7 @@
     },
     "homepage": "https://github.com/Soullnik/babylon.quarks-standalone#readme",
     "peerDependencies": {
-        "@babylonjs/core": ">=9.0.0"
+        "@babylonjs/core": "^9.0.0"
     },
     "devDependencies": {
         "@babylonjs/core": "^9.31.0",

package/src/BatchedRenderer.ts

@@ -20,6 +20,7 @@ import {
     ParticleErosion,
     ParticleGradientMap,
     ParticleUVDistortion,
+    RenderFace,
     RenderMode,
     SortMode,
     TextureUV,
@@ -108,13 +109,27 @@ export interface VFXBatchSettings {
     renderingGroupId: number;
     /**
      * Whether the scene's fog applies to the particles, as it does to any other
-     * 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.
+     * 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;
+    /**
+     * Whether the material applies the scene's image processing (`scene.imageProcessingConfiguration`:
+     * exposure, contrast, tone mapping, vignette, colour curves, colour grading, dithering), as
+     * Babylon's own `ParticleSystem` and its standard and PBR materials do; unset reads as true.
+     * When the configuration is applied by a post process (a `DefaultRenderingPipeline` with image
+     * processing on), the material leaves its colour in linear space for it, as those materials do.
+     * Off, the material does neither: its colour is written as authored. That does not keep the
+     * particles out of a post process, which processes the whole frame; particles that must reach
+     * the screen untouched are drawn by a camera the pipeline is not attached to. Systems that
+     * differ are batched apart. See {@link ParticleSystem.applyImageProcessing}.
+     */
+    applyImageProcessing?: boolean;
     /**
      * Offset of billboard quads from their particle, in particle-size units
      * (Unity's renderer Pivot). On billboards x/y move the quad in its own plane
@@ -125,6 +140,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.
@@ -196,20 +216,27 @@ export interface AdaptivePerformanceState extends AdaptivePerformanceOptions {
  *
  * 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.
+ * 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 {
-    /** 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> = [];
+    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;
-    /** Index into {@link batches} of each system's batch. The renderer owns it. */
-    systemToBatchIndex: Map<IParticleSystem, number> = new Map<IParticleSystem, number>();
     private depth: DepthBinding | null = null;
     /** Systems in insertion order — iterated every frame, unlike the map. */
     private systems: Array<IParticleSystem> = [];
@@ -272,8 +299,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();
 
@@ -282,21 +313,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
@@ -304,31 +330,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
@@ -361,6 +389,10 @@ export class BatchedRenderer extends TransformNode {
             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.
@@ -385,10 +417,10 @@ export class BatchedRenderer extends TransformNode {
         const system = particleSystem as IParticleSystem;
         const settings = particleSystem.getRendererSettings();
         const stored = storedBatchSettings(settings);
-        for (let i = 0; i < this.batches.length; i++) {
-            if (batchSettingsEqual(this.batches[i].settings, stored)) {
-                this.batches[i].addSystem(system);
-                this.systemToBatchIndex.set(system, i);
+        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;
             }
         }
@@ -409,12 +441,12 @@ export class BatchedRenderer extends TransformNode {
             default:
                 throw new Error(`Unsupported render mode: ${settings.renderMode}`);
         }
-        batch.mesh.parent = this;
+        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);
     }
 
     /**
@@ -440,12 +472,12 @@ 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;
     }
 
@@ -456,16 +488,16 @@ export class BatchedRenderer extends TransformNode {
      * 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);
+        const batchIndex = this.batchIndexOf.get(system);
         if (batchIndex !== undefined) {
-            const batch = this.batches[batchIndex];
+            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.batches.some((other) => other !== batch && batchSettingsEqual(other.settings, settings))
+                !this.batchList.some((other) => other !== batch && batchSettingsEqual(other.settings, settings))
             ) {
                 batch.applyLiveSettings(settings);
                 return;
@@ -491,7 +523,7 @@ export class BatchedRenderer extends TransformNode {
      */
     setDepthTexture(depth: BaseTexture | DepthRenderer | null, options: DepthTextureOptions = {}) {
         this.depth = depth ? depthBinding(depth, options) : null;
-        for (const batch of this.batches) {
+        for (const batch of this.batchList) {
             batch.applyDepthTexture(this.depth);
         }
     }
@@ -532,7 +564,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);
         }
     }
@@ -554,7 +586,7 @@ export class BatchedRenderer extends TransformNode {
      */
     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;
@@ -619,7 +651,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);
                 }
@@ -656,19 +690,13 @@ export class BatchedRenderer extends TransformNode {
      */
     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) {
             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;
@@ -682,14 +710,13 @@ 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
+            // A system whose stop action is destroy disposes itself from inside update and drops
             // out of the list; stay on the slot it vacated.
             if (systems[i] !== system) {
                 i--;
@@ -719,8 +746,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;
@@ -744,12 +771,12 @@ 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);
             }
         }
     }
@@ -767,7 +794,7 @@ export class BatchedRenderer extends TransformNode {
         /** 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) {
@@ -790,10 +817,10 @@ export class BatchedRenderer extends TransformNode {
      * 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) {
@@ -803,7 +830,7 @@ export class BatchedRenderer extends TransformNode {
         this.systems.length = 0;
         this.orderedSystems = [];
         this.orderedSystemsStale = true;
-        this.systemToBatchIndex.clear();
+        this.batchIndexOf.clear();
         super.dispose();
     }
 }

package/src/EffectPool.ts

@@ -1,4 +1,4 @@
-import {Vector3} from '@babylonjs/core/Maths/math.vector';
+import {Quaternion, Vector3} from '@babylonjs/core/Maths/math.vector';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Node} from '@babylonjs/core/node';
 import {BatchedRenderer} from './BatchedRenderer';
@@ -16,6 +16,31 @@ export interface EffectPoolOptions {
     maxSize?: number;
 }
 
+/**
+ * Where {@link EffectPool.acquire} puts a copy. Each part left out is the template's own, as the
+ * copy was made, so nothing carries over from the copy's previous use.
+ */
+export interface EffectPlacement {
+    /** Local position under {@link parent}. */
+    position?: Vector3;
+    /** Local rotation as Euler angles in radians; ignored when {@link rotationQuaternion} is set. */
+    rotation?: Vector3;
+    /** Local rotation as a quaternion, for a direction: a hit normal, a muzzle's facing. */
+    rotationQuaternion?: Quaternion;
+    /** Local scale. */
+    scaling?: Vector3;
+    /** The node the copy is parented to; none (world space) by default. */
+    parent?: Node | null;
+}
+
+/** The local transform a copy is put back to on every acquire. */
+interface RestTransform {
+    position: Vector3;
+    rotation: Vector3;
+    rotationQuaternion: Quaternion | null;
+    scaling: Vector3;
+}
+
 /**
  * A pool of copies of one effect, for effects played many times over: hits,
  * footsteps, muzzle flashes, pickups.
@@ -24,11 +49,16 @@ export interface EffectPoolOptions {
  * it; a copy whose every system has finished goes back to the pool by itself,
  * so a one-shot effect needs nothing more. A looping effect is ended with
  * {@link stop}, which lets its particles die out before the copy returns, or
- * dropped at once with {@link release}.
+ * dropped at once with {@link release}. A ring buffer effect (`ringBufferMode`)
+ * never finishes, since its particles never die: release it.
  *
  * Idle copies are parked disabled, which costs the renderer nothing, and keep
  * their place in its batches, so acquiring one allocates nothing.
  *
+ * A copy disposed from outside (by its own `dispose()`, or with a parent it
+ * was acquired under) leaves the pool on its own, and the pool makes a new
+ * one when it needs it.
+ *
  * The template itself is never played by the pool; it is only cloned. Disable
  * it, or keep it out of the renderer, if it is not meant to be seen.
  */
@@ -36,6 +66,7 @@ export class EffectPool {
     private readonly idle: TransformNode[] = [];
     private readonly playing = new Set<TransformNode>();
     private readonly systemsOf = new Map<TransformNode, ParticleSystem[]>();
+    private readonly restOf = new Map<TransformNode, RestTransform>();
     private disposed = false;
 
     constructor(
@@ -63,10 +94,15 @@ export class EffectPool {
 
     /**
      * Takes an idle copy (making one when none is idle and the pool is under
-     * its size), parents it, places it and starts it from the beginning.
-     * Null when the pool is full or disposed.
+     * its size), places it and starts it from the beginning. The copy's
+     * transform is put back to the template's first, so a rotation or scale
+     * from its last use does not stay. Null when the pool is full or disposed.
+     *
+     * @param placement - Where to put the copy, or just its position.
+     * @param parent - The node to parent it to, when `placement` is a position;
+     *   ignored otherwise (use {@link EffectPlacement.parent}).
      */
-    acquire(position?: Vector3, parent: Node | null = null): TransformNode | null {
+    acquire(placement?: Vector3 | EffectPlacement, parent: Node | null = null): TransformNode | null {
         if (this.disposed) {
             return null;
         }
@@ -74,10 +110,12 @@ export class EffectPool {
         if (copy === null) {
             return null;
         }
-        copy.parent = parent;
-        if (position !== undefined) {
-            copy.position.copyFrom(position);
-        }
+        // Told apart by shape, not class: a vector from another copy of Babylon is still a position.
+        const place: EffectPlacement =
+            placement === undefined || typeof (placement as Vector3).x === 'number'
+                ? {position: placement as Vector3 | undefined, parent}
+                : (placement as EffectPlacement);
+        this.placeCopy(copy, place);
         copy.setEnabled(true);
         this.playing.add(copy);
         QuarksUtil.restart(copy);
@@ -100,6 +138,10 @@ export class EffectPool {
         if (!this.playing.delete(copy)) {
             return;
         }
+        if (copy.isDisposed()) {
+            this.forget(copy);
+            return;
+        }
         QuarksUtil.stop(copy);
         copy.setEnabled(false);
         copy.parent = null;
@@ -127,28 +169,66 @@ export class EffectPool {
         const systems: ParticleSystem[] = [];
         QuarksUtil.runOnAllParticleEmitters(copy, (emitter) => {
             const system = emitter.system as unknown as ParticleSystem;
-            // The pool owns the copy's life; a system disposing itself would
-            // pull one emitter out of an effect that is meant to play again.
-            system.autoDestroy = false;
+            // The pool owns the copy's life; a system disposing or disabling itself
+            // would pull one emitter out of an effect that is meant to play again.
+            system.ignoreStopAction = true;
             system.addEventListener('finished', this.onSystemFinished);
             systems.push(system);
         });
         this.systemsOf.set(copy, systems);
+        this.restOf.set(copy, {
+            position: copy.position.clone(),
+            rotation: copy.rotation.clone(),
+            rotationQuaternion: copy.rotationQuaternion?.clone() ?? null,
+            scaling: copy.scaling.clone(),
+        });
         QuarksUtil.addToBatchRenderer(copy, this.options.renderer);
         copy.setEnabled(false);
         copy.parent = null;
+        // A copy disposed from outside, or with a parent it was placed under, is let go of.
+        copy.onDisposeObservable.addOnce(() => this.forget(copy));
         return copy;
     }
 
-    private disposeCopy(copy: TransformNode): void {
-        const systems = this.systemsOf.get(copy) ?? [];
-        for (const system of systems) {
+    /** Puts the copy back to the template's transform, then applies `place`. */
+    private placeCopy(copy: TransformNode, place: EffectPlacement): void {
+        const rest = this.restOf.get(copy)!;
+        copy.parent = place.parent ?? null;
+        // By components: Babylon's copyFrom reads private fields, which a vector from elsewhere lacks.
+        const position = place.position ?? rest.position;
+        const scaling = place.scaling ?? rest.scaling;
+        copy.position.copyFromFloats(position.x, position.y, position.z);
+        copy.scaling.copyFromFloats(scaling.x, scaling.y, scaling.z);
+        if (place.rotationQuaternion !== undefined) {
+            copy.rotationQuaternion = place.rotationQuaternion.clone();
+        } else if (place.rotation !== undefined) {
+            copy.rotationQuaternion = null;
+            copy.rotation.copyFromFloats(place.rotation.x, place.rotation.y, place.rotation.z);
+        } else {
+            copy.rotationQuaternion = rest.rotationQuaternion?.clone() ?? null;
+            copy.rotation.copyFrom(rest.rotation);
+        }
+    }
+
+    /** Drops every trace of a copy, which was or is being disposed. */
+    private forget(copy: TransformNode): void {
+        for (const system of this.systemsOf.get(copy) ?? []) {
             system.removeEventListener('finished', this.onSystemFinished);
             this.options.renderer.deleteSystem(system);
             system.dispose();
         }
         this.systemsOf.delete(copy);
-        // Lets go of the textures the copy shares with the template.
+        this.restOf.delete(copy);
+        this.playing.delete(copy);
+        const index = this.idle.indexOf(copy);
+        if (index !== -1) {
+            this.idle.splice(index, 1);
+        }
+    }
+
+    private disposeCopy(copy: TransformNode): void {
+        this.forget(copy);
+        // Lets go of the textures and materials the copy shares with the template.
         disposeEffect(copy);
     }