babylon.quarks 0.28.0 → 0.29.0

package/package.json

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

package/src/BatchedRenderer.ts

@@ -118,6 +118,18 @@ export interface VFXBatchSettings {
      * 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
@@ -704,7 +716,7 @@ export class BatchedRenderer extends TransformNode {
                     !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--;

package/src/EffectPool.ts

@@ -49,7 +49,8 @@ interface RestTransform {
  * 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.
@@ -168,9 +169,9 @@ 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);
         });

package/src/ParticleEmitter.ts

@@ -1,8 +1,46 @@
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
-import {IParticleSystem, Matrix4, SerializationOptions} from 'quarks.core';
+import {IParticleSystem, Matrix4, SerializationOptions, Vector3} from 'quarks.core';
 import {quarksNodeId} from './nodeId';
-import type {BabylonMetaData} from './system/types';
+import type {BabylonMetaData, ScalingMode} from './system/types';
+
+const axisLengths = [0, 0, 0];
+const crossA = new Vector3();
+const crossB = new Vector3();
+
+/** Below this an axis of the world matrix counts as scaled to 0. */
+const ZERO_AXIS = 1e-12;
+
+/**
+ * Sets the length of basis column `axis` of the 4×4 `e` to `target`, keeping its direction and
+ * sign. A column of length 0 is rebuilt as the cross product of the other two, in the order that
+ * keeps the basis right-handed, or as the bare axis when they are degenerate too.
+ */
+function setAxisLength(e: number[], axis: number, lengths: number[], target: number): void {
+    const o = axis * 4;
+    const length = lengths[axis];
+    if (length > ZERO_AXIS) {
+        const k = target / length;
+        e[o] *= k;
+        e[o + 1] *= k;
+        e[o + 2] *= k;
+        return;
+    }
+    const a = (axis + 1) % 3;
+    const b = (axis + 2) % 3;
+    if (lengths[a] > ZERO_AXIS && lengths[b] > ZERO_AXIS) {
+        crossA.set(e[a * 4], e[a * 4 + 1], e[a * 4 + 2]);
+        crossB.set(e[b * 4], e[b * 4 + 1], e[b * 4 + 2]);
+        crossA.cross(crossB).normalize().multiplyScalar(target);
+        e[o] = crossA.x;
+        e[o + 1] = crossA.y;
+        e[o + 2] = crossA.z;
+    } else {
+        e[o] = axis === 0 ? target : 0;
+        e[o + 1] = axis === 1 ? target : 0;
+        e[o + 2] = axis === 2 ? target : 0;
+    }
+}
 
 /** A {@link ParticleEmitter} as its `toJSON` writes it: the node, its transform and its system. */
 export interface ParticleEmitterJSON {
@@ -28,7 +66,7 @@ export interface ParticleEmitterJSON {
 
 /**
  * Above 0 while a particle system disposes its own emitter (`ParticleSystem.dispose()`, which
- * `autoDestroy` calls when the system finishes). Babylon then disposes the child nodes too, and
+ * a `destroy` stop action calls when the system finishes). Babylon then disposes the child nodes too, and
  * child emitters keep their systems playing, so an effect's longer-lived children are not cut off
  * when a short parent finishes. Disposing a node directly (`root.dispose()`) disposes its systems.
  */
@@ -54,40 +92,67 @@ export class ParticleEmitter extends TransformNode {
     system: IParticleSystem;
     private _matrixWorld: Matrix4 = new Matrix4();
     private _matrixWorldFlag = -1;
+    private _matrixWorldMode: ScalingMode | undefined;
+    private readonly _shapeScale = new Vector3(1, 1, 1);
 
     /**
-     * The node's world matrix in quarks.core form. Mirrored from Babylon's
-     * matrix only when that matrix actually changed (tracked by its
-     * `updateFlag`), so repeated reads inside a frame are free.
+     * The matrix the system simulates and draws in, in quarks.core form: the node's world matrix,
+     * with the length of each axis set by the system's {@link ScalingMode}. `'hierarchy'` keeps the
+     * whole world scale; `'local'` sets each axis to the node's own `scaling` (times
+     * `scalingDeterminant`), leaving the parents' scale out; `'shape'` sets each to 1, and
+     * {@link shapeScale} applies the world scale to the emission shape alone. Only the axes'
+     * lengths change, so position, rotation and any mirroring from the hierarchy are kept. An axis
+     * that a parent scales to 0 has no direction left: it is rebuilt square to the other two. A
+     * node whose system has no scaling mode reads as `'hierarchy'`. Recomputed only when Babylon's
+     * matrix changed (tracked by its `updateFlag`) or the mode did, so repeated reads inside a frame
+     * are free.
      */
     get matrixWorld(): Matrix4 {
         const m = this.getWorldMatrix();
         const flag = m.updateFlag;
-        if (flag === this._matrixWorldFlag) {
+        const mode = (this.system as {scalingMode?: ScalingMode} | undefined)?.scalingMode ?? 'hierarchy';
+        if (flag === this._matrixWorldFlag && mode === this._matrixWorldMode) {
             return this._matrixWorld;
         }
         this._matrixWorldFlag = flag;
+        this._matrixWorldMode = mode;
         const e = this._matrixWorld.elements;
         const s = m.m;
-        e[0] = s[0];
-        e[1] = s[1];
-        e[2] = s[2];
-        e[3] = s[3];
-        e[4] = s[4];
-        e[5] = s[5];
-        e[6] = s[6];
-        e[7] = s[7];
-        e[8] = s[8];
-        e[9] = s[9];
-        e[10] = s[10];
-        e[11] = s[11];
-        e[12] = s[12];
-        e[13] = s[13];
-        e[14] = s[14];
-        e[15] = s[15];
+        for (let i = 0; i < 16; i++) {
+            e[i] = s[i];
+        }
+        this._shapeScale.set(1, 1, 1);
+        // Without a parent the world scale is the node's own, so 'local' is 'hierarchy'.
+        if (mode === 'hierarchy' || (mode === 'local' && !this.parent)) {
+            return this._matrixWorld;
+        }
+        const own = this.scaling;
+        const determinant = this.scalingDeterminant;
+        const lengths = axisLengths;
+        for (let axis = 0; axis < 3; axis++) {
+            const o = axis * 4;
+            lengths[axis] = Math.sqrt(e[o] * e[o] + e[o + 1] * e[o + 1] + e[o + 2] * e[o + 2]);
+        }
+        for (let axis = 0; axis < 3; axis++) {
+            const target =
+                mode === 'local' ? Math.abs((axis === 0 ? own.x : axis === 1 ? own.y : own.z) * determinant) : 1;
+            if (mode === 'shape') {
+                this._shapeScale.setComponent(axis, lengths[axis]);
+            }
+            setAxisLength(e, axis, lengths, target);
+        }
         return this._matrixWorld;
     }
 
+    /**
+     * What the system's emission shape is scaled by before {@link matrixWorld} places it: the
+     * node's world scale in `'shape'` mode, which leaves the particles and their motion unscaled,
+     * and 1 otherwise. Read it after `matrixWorld`, which refreshes it.
+     */
+    get shapeScale(): Vector3 {
+        return this._shapeScale;
+    }
+
     /** Whether the node and its parents are enabled; setting it is `setEnabled`. */
     get visible(): boolean {
         return this.isEnabled();
@@ -110,7 +175,7 @@ export class ParticleEmitter extends TransformNode {
     /**
      * Disposes the node and the particle system it carries, so `root.dispose()` on an effect tree
      * also removes its systems from their renderer. Safe to call more than once. When a system
-     * disposes its own emitter (`ParticleSystem.dispose()`, `autoDestroy`), the systems of child
+     * disposes its own emitter (`ParticleSystem.dispose()`, a `destroy` stop action), the systems of child
      * emitters keep playing until they finish or are disposed themselves.
      */
     dispose(doNotRecurse?: boolean, disposeMaterialAndTextures = false): void {

package/src/ParticleSystem.ts

@@ -61,6 +61,7 @@ import {
     moveTrails,
     recordTrailHistory,
     removeDeadTrails,
+    RingBufferStep,
     runBehaviorSteps,
     snapshotPreviousState,
 } from './system/integrate';
@@ -74,10 +75,14 @@ import {
     validAlphaTest,
     validCullingMode,
     validLighting,
+    validLoopRange,
     validMaxParticles,
     validRenderFace,
+    validRingBufferMode,
+    validScalingMode,
     validSoftFade,
     validSortMode,
+    validStopAction,
     validTileCount,
 } from './system/normalize';
 import {ParticleSpawner} from './system/ParticleSpawner';
@@ -116,7 +121,9 @@ import type {
     CullingMode,
     ParticleSystemJSONParameters,
     ParticleSystemParameters,
+    RingBufferMode,
     ScalingMode,
+    StopAction,
 } from './system/types';
 
 export type {
@@ -127,7 +134,9 @@ export type {
     CullingMode,
     ParticleSystemJSONParameters,
     ParticleSystemParameters,
+    RingBufferMode,
     ScalingMode,
+    StopAction,
 } from './system/types';
 
 // Scratch for the per-step emitter matrix of a frame that interpolates, see `update`.
@@ -155,8 +164,42 @@ const stepScale = new Vector3();
  * start values and emission, and the particle's age over its life inside behaviors.
  */
 export class ParticleSystem implements IParticleSystem {
-    /** Dispose the system, its emitter and its batch slot when it finishes. Default false. */
-    autoDestroy: boolean;
+    /**
+     * What the system does once it has finished (Unity's Stop Action): nothing, disable its
+     * emitter, or dispose it; see {@link StopAction}. `'none'` by default.
+     *
+     * As in Unity, the action waits for the system's sub emitters: it runs once the system has
+     * finished and none of the systems it emits into, nor theirs, has a particle left (see
+     * {@link isAlive}), so disabling or disposing a parent does not cut its sub emitters'
+     * particles short. A sub emitter target ({@link onlyUsedByOther}) takes no stop action of its
+     * own: it is empty between its parent's bursts, and its parent decides when the effect is done.
+     */
+    stopAction: StopAction;
+
+    /**
+     * Skips the {@link stopAction} while true, so a tool can play an effect over and over (an
+     * editor's preview, a gallery, a pool of reused copies) and still save the stop action it
+     * was authored with, as Unity applies stop actions only in Play mode. The `finished` event
+     * fires either way. False by default; never saved, cloned or loaded.
+     */
+    ignoreStopAction = false;
+
+    /**
+     * Whether the system disposes itself when it finishes: `stopAction === 'destroy'`. Setting it
+     * true sets that stop action, and false turns a `'destroy'` one into `'none'`.
+     * @deprecated Use {@link stopAction}.
+     */
+    get autoDestroy(): boolean {
+        return this.stopAction === 'destroy';
+    }
+
+    set autoDestroy(value: boolean) {
+        if (value) {
+            this.stopAction = 'destroy';
+        } else if (this.stopAction === 'destroy') {
+            this.stopAction = 'none';
+        }
+    }
     /**
      * Start a looping system as if it had already run one full cycle (Unity's Prewarm), so a fire
      * or a mist is full from its first frame. Default false.
@@ -236,9 +279,24 @@ export class ParticleSystem implements IParticleSystem {
     /**
      * Most particles alive at once (Unity's Max Particles); emission past it is dropped. Undefined
      * means no limit, as does a negative or NaN count given to the constructor; a fraction is
-     * rounded down.
+     * rounded down. With a {@link ringBufferMode}, new particles replace the oldest instead.
      */
     maxParticles?: number;
+    /**
+     * What a full system does with new particles (Unity's Ring Buffer Mode): drop them, or
+     * replace the oldest, which wait frozen or looping until then; see {@link RingBufferMode}.
+     * `'disabled'` by default. Takes effect only with {@link maxParticles}.
+     */
+    ringBufferMode: RingBufferMode;
+    /**
+     * The part of its life a particle plays again in `'loopUntilReplaced'` (Unity's Loop Range):
+     * at the end of its life it goes back to `x` and plays to `y`, as fractions of its life, 0 to
+     * 1. (0, 1), the default, replays its whole life. Both ends are read clamped into 0..1 and in
+     * order, however the vector was set. A range of no length, such as (0.5, 0.5), holds the
+     * particle still at that point of its life; behaviors that act by age stop with it, those
+     * that act per second (rotation speed, forces) still run.
+     */
+    ringBufferLoopRange: Vector2;
     /**
      * The system emits nothing of its own and only spawns what an `EmitSubParticleSystem` on
      * another system sends it (a Unity sub emitter). Default false.
@@ -339,9 +397,12 @@ export class ParticleSystem implements IParticleSystem {
         return this.emitEnded;
     }
 
-    /** Whether continuous or queued emission can still spawn particles before the system is done. */
-    hasPendingEmission(): boolean {
-        return this.emission.hasPendingEmission();
+    /**
+     * Whether continuous or queued emission can still spawn particles before the system is done:
+     * its own, or with `state` one a sub emitter runs into this system for a parent particle.
+     */
+    hasPendingEmission(state?: EmissionState): boolean {
+        return this.emission.hasPendingEmission(state);
     }
 
     /**
@@ -350,7 +411,7 @@ export class ParticleSystem implements IParticleSystem {
      * {@link endEmit} and whose last particle has died.
      */
     isFinished(): boolean {
-        if (this.particleNum > 0) {
+        if (this.particleNum > 0 || this.hasPendingSubEmission()) {
             return false;
         }
         // A sub emitter target emits nothing of its own: empty is finished,
@@ -638,26 +699,15 @@ export class ParticleSystem implements IParticleSystem {
         this.neededToUpdateRender = true;
     }
 
-    /**
-     * The emitter's world scale per axis, measured with {@link motionScale}
-     * before every step; what `'hierarchy'` multiplies start speeds by. Taken
-     * from the system's own emitter rather than the emission matrix, whose
-     * columns carry a parent particle's velocity for a sub emitter.
-     * @internal
-     */
-    readonly hierarchyScale = new Vector3(1, 1, 1);
-
-    /** The mean world scale of the emitter for a world-space `'hierarchy'` system, else 1. */
+    /** The mean scale of the emitter's matrix for a world-space system, else 1. */
     private measureMotionScale(emitterMatrix: Matrix4): number {
-        if (this.scalingMode !== 'hierarchy' || !this.worldSpace) {
-            this.hierarchyScale.set(1, 1, 1);
+        if (!this.worldSpace) {
             return 1;
         }
         const e = emitterMatrix.elements;
         const sx = Math.sqrt(e[0] * e[0] + e[1] * e[1] + e[2] * e[2]);
         const sy = Math.sqrt(e[4] * e[4] + e[5] * e[5] + e[6] * e[6]);
         const sz = Math.sqrt(e[8] * e[8] + e[9] * e[9] + e[10] * e[10]);
-        this.hierarchyScale.set(sx, sy, sz);
         return (sx + sy + sz) / 3;
     }
 
@@ -948,6 +998,34 @@ export class ParticleSystem implements IParticleSystem {
         this.neededToUpdateRender = true;
     }
 
+    /**
+     * Whether the particles' material applies the scene's image processing (exposure, contrast,
+     * tone mapping, vignette, colour curves, colour grading, dithering of
+     * `scene.imageProcessingConfiguration`), as Babylon's own particle systems and materials do;
+     * true by default. A scene whose configuration does nothing leaves the colour as it is, and
+     * one applied by a post process gets the colour in linear space. Particles that multiply the
+     * frame (`ALPHA_MULTIPLY`) are a factor rather than light and are not tone mapped.
+     *
+     * As in Babylon, the processing runs on each particle before it is blended: tone mapping
+     * clamps an HDR colour to the displayable range, and an additive particle picks up what the
+     * configuration does to black (a contrast below 1, colour curves or an
+     * opaque vignette lift it). The configuration is the scene's;
+     * there is no per-system one.
+     *
+     * Switched off, the material writes its colour as authored, and leaves it in gamma space under
+     * a post process, which still processes the frame the particles are in. To keep particles out
+     * of a post process, draw them with a camera the pipeline is not attached to. Saved in the
+     * effect JSON only when switched off.
+     */
+    get applyImageProcessing(): boolean {
+        return this.rendererSettings.applyImageProcessing !== false;
+    }
+
+    set applyImageProcessing(apply: boolean) {
+        this.rendererSettings.applyImageProcessing = apply;
+        this.neededToUpdateRender = true;
+    }
+
     /**
      * Multiplier on the time this system is advanced by (Unity's Simulation
      * Speed): 2 runs the effect twice as fast, 0 freezes it without pausing the
@@ -1003,13 +1081,14 @@ export class ParticleSystem implements IParticleSystem {
     /** What this system does while off screen, see {@link CullingMode}. `'always'` by default. */
     cullingMode: CullingMode = 'always';
 
-    /** What the emitter's world scale does to a world-space system, see {@link ScalingMode}. `'shape'` by default. */
-    scalingMode: ScalingMode = 'shape';
+    /** What the emitter's scale does to the system, see {@link ScalingMode}. `'local'` by default. */
+    scalingMode: ScalingMode = 'local';
 
     /**
-     * What world-space forces and speed limits are multiplied by this step:
-     * the mean of the emitter's world scale axes in `'hierarchy'` mode, 1
-     * otherwise. Updated before every simulation step.
+     * What world-space forces and speed limits are multiplied by this step: the mean of the axes
+     * of the scale the {@link scalingMode} applies (the emitter's own in `'local'`, its world scale
+     * in `'hierarchy'`, 1 in `'shape'`) in a world-space system, 1 in a local-space one, whose
+     * emitter matrix scales them already. Updated before every simulation step.
      */
     motionScale = 1;
 
@@ -1094,7 +1173,9 @@ export class ParticleSystem implements IParticleSystem {
             },
         });
 
-        this.autoDestroy = parameters.autoDestroy ?? false;
+        this.stopAction = validStopAction(
+            parameters.stopAction ?? (parameters.autoDestroy === true ? 'destroy' : undefined)
+        );
         this.duration = parameters.duration ?? 1;
         this.startDelay = parameters.startDelay ?? new ConstantValue(0);
         this.looping = parameters.looping ?? true;
@@ -1109,6 +1190,8 @@ export class ParticleSystem implements IParticleSystem {
         this.emissionOverDistance = parameters.emissionOverDistance ?? new ConstantValue(0);
         this.emissionBursts = normalizeBursts(parameters.emissionBursts);
         this.maxParticles = validMaxParticles(parameters.maxParticles);
+        this.ringBufferMode = validRingBufferMode(parameters.ringBufferMode);
+        this.ringBufferLoopRange = validLoopRange(parameters.ringBufferLoopRange);
         this.onlyUsedByOther = parameters.onlyUsedByOther ?? false;
         this.emitterShape = parameters.shape ?? new SphereEmitter();
         this.behaviors = parameters.behaviors ?? [];
@@ -1166,6 +1249,7 @@ export class ParticleSystem implements IParticleSystem {
             maxParticleSize: parameters.maxParticleSize ?? Infinity,
             renderingGroupId: parameters.renderingGroupId ?? 0,
             applyFog: parameters.applyFog ?? true,
+            applyImageProcessing: parameters.applyImageProcessing ?? true,
             lighting: validLighting(parameters.lighting),
             rim: normalizeMeshRim(parameters.rim),
             mapUV: normalizeMapUV(parameters.mapUV),
@@ -1176,7 +1260,7 @@ export class ParticleSystem implements IParticleSystem {
         this.flip = nonZeroFlip(parameters.flip);
         this.playbackSpeed = parameters.playbackSpeed ?? 1;
         this.cullingMode = validCullingMode(parameters.cullingMode);
-        this.scalingMode = parameters.scalingMode === 'hierarchy' ? 'hierarchy' : 'shape';
+        this.scalingMode = validScalingMode(parameters.scalingMode);
         this.alignToDirection = parameters.alignToDirection === true;
         this.seed = parameters.seed;
         this.ensureMeshNormals();
@@ -1384,7 +1468,7 @@ export class ParticleSystem implements IParticleSystem {
     /**
      * Stops emission and lets the particles alive die out (Unity's `Stop` with
      * `StopEmitting`). The system fires `emitEnd`, then `finished` when the last particle has
-     * died, and is disposed then if {@link autoDestroy} is set. {@link restart} starts it again.
+     * died, and then does what its {@link stopAction} says. {@link restart} starts it again.
      */
     endEmit(): void {
         this.emitEnded = true;
@@ -1468,6 +1552,7 @@ export class ParticleSystem implements IParticleSystem {
         this.emitterShape.reset?.();
         this.emitEnded = false;
         this.finishedEventFired = false;
+        this.stopActionPending = false;
         this.prewarmed = false;
         this.initSystemGenerators();
         this.previousEmitterPos = undefined;
@@ -1518,6 +1603,9 @@ export class ParticleSystem implements IParticleSystem {
         }
 
         if (!this.looping && this.finishedEventFired && this.particleNum === 0) {
+            // Finished; the stop action may still be waiting for the sub emitters' particles.
+            this.applyStopAction();
+            if (this.destroyed) return;
             // Still tick the fixed-step clock. A sub-emitter target
             // (onlyUsedByOther) goes empty between parent bursts; skipping the
             // accumulator here desyncs it from the parent, so the next particles
@@ -1789,6 +1877,7 @@ export class ParticleSystem implements IParticleSystem {
 
     private stepOnce(delta: number, emitterMatrix: Matrix4): void {
         if (this.destroyed) return;
+        this.spawner.fitRing();
         this.motionScale = this.measureMotionScale(emitterMatrix);
         if (!this.onlyUsedByOther) {
             this.emission.emit(delta, this.emissionState, emitterMatrix);
@@ -1832,7 +1921,8 @@ export class ParticleSystem implements IParticleSystem {
                 snapshotColor,
                 this.bounds,
                 this,
-                onDied
+                onDied,
+                this.ringBufferStep()
             );
         } else {
             // Trails: the newborn collapse, then motion, then the trail history,
@@ -1848,6 +1938,58 @@ export class ParticleSystem implements IParticleSystem {
         this.notifyFinished();
     }
 
+    /** Whether a sub emitter of this system still has an emission running into its target. */
+    private hasPendingSubEmission(): boolean {
+        for (const behavior of this.behaviors) {
+            if (behavior instanceof EmitSubParticleSystem && behavior.hasPendingEmission()) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Whether the system still has particles or emission to come (Unity's `IsAlive`): not
+     * {@link isFinished}, or, with `withSubEmitters` (the default), any system it emits into
+     * through an `EmitSubParticleSystem`, and theirs, still has particles.
+     */
+    isAlive(withSubEmitters = true): boolean {
+        if (!this.isFinished()) {
+            return true;
+        }
+        return withSubEmitters && this.subEmittersAlive(new Set<ParticleSystem>([this]));
+    }
+
+    /** Whether a system this one emits into has particles, or one of theirs; `seen` stops a cycle. */
+    private subEmittersAlive(seen: Set<ParticleSystem>): boolean {
+        for (const behavior of this.behaviors) {
+            if (!(behavior instanceof EmitSubParticleSystem)) {
+                continue;
+            }
+            const target = behavior.targetSystem;
+            if (!(target instanceof ParticleSystem) || seen.has(target)) {
+                continue;
+            }
+            seen.add(target);
+            if (target.particleNum > 0 || target.hasPendingSubEmission() || target.subEmittersAlive(seen)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Whether particles outlive their lifetime, held or looped until replaced: a {@link ringBufferMode}
+     * on a system with {@link maxParticles}, outside the Trail render mode.
+     */
+    get ringBufferActive(): boolean {
+        return (
+            this.ringBufferMode !== 'disabled' &&
+            this.maxParticles !== undefined &&
+            this.rendererSettings.renderMode !== RenderMode.Trail
+        );
+    }
+
     /** Re-points every particle at the store, for {@link snapshotPreviousState}. */
     private readonly rebindParticles = (): void => this.spawner.rebind();
 
@@ -1862,15 +2004,56 @@ export class ParticleSystem implements IParticleSystem {
         event.particle = undefined;
     };
 
+    /** The ring buffer step for {@link integrateSprites}, or undefined when particles die by age. */
+    private ringBufferStep(): RingBufferStep | undefined {
+        if (!this.ringBufferActive) {
+            return undefined;
+        }
+        const step = this.ringStep;
+        step.pause = this.ringBufferMode === 'pauseUntilReplaced';
+        // Read through the same clamp as the constructor: the field can be assigned anything.
+        const {x, y} = this.ringBufferLoopRange;
+        const start = Number.isFinite(x) ? Math.min(1, Math.max(0, x)) : 0;
+        const end = Number.isFinite(y) ? Math.min(1, Math.max(0, y)) : 1;
+        step.loopStart = Math.min(start, end);
+        step.loopEnd = Math.max(start, end);
+        return step;
+    }
+
+    private readonly ringStep: RingBufferStep = {pause: true, loopStart: 0, loopEnd: 1};
+
+    /** Set on each finish until the {@link stopAction} has run, which waits for the sub emitters. */
+    private stopActionPending = false;
+
     private notifyFinished(): void {
         if (!this.isFinished()) {
             return;
         }
         if (!this.finishedEventFired) {
             this.finishedEventFired = true;
+            // Once per finish, so an emitter enabled again from a listener or later stays enabled.
+            this.stopActionPending = true;
             this.events.fire({type: 'finished', particleSystem: this});
         }
-        if (this.autoDestroy) {
+        this.applyStopAction();
+    }
+
+    /** Runs a pending {@link stopAction} once no system this one emits into has particles left. */
+    private applyStopAction(): void {
+        if (!this.stopActionPending) {
+            return;
+        }
+        if (this.stopAction === 'none' || this.ignoreStopAction || this.onlyUsedByOther || this.destroyed) {
+            this.stopActionPending = false;
+            return;
+        }
+        if (this.subEmittersAlive(new Set<ParticleSystem>([this]))) {
+            return;
+        }
+        this.stopActionPending = false;
+        if (this.stopAction === 'disable') {
+            this.emitter.setEnabled(false);
+        } else {
             this.dispose();
         }
     }

package/src/QuarksLoader.ts

@@ -337,6 +337,8 @@ interface LoadedMeta {
     textures: {[uuid: string]: Texture | null};
     geometries: {[uuid: string]: GeometryArrays};
     materials: {[uuid: string]: QuarksMaterialJSON};
+    /** The file's `quarksFormat`; 0 for a file written before the field existed. */
+    format: number;
 }
 
 /**
@@ -623,6 +625,7 @@ export class QuarksLoader {
             textures: {},
             geometries: {},
             materials: {},
+            format: typeof format === 'number' ? format : 0,
         };
 
         const {geometries, images, textures: textureList, materials} = json;
@@ -1486,6 +1489,12 @@ export class QuarksLoader {
     }
 
     private parseParticleSystem(json: ParticleSystemJSONParameters, meta: LoadedMeta): ParticleSystem {
+        if (meta.format < 2 && json !== null && typeof json === 'object' && json.scalingMode !== 'hierarchy') {
+            // Before format 2 the emitter's whole world scale reached every system's shape and
+            // particle size, and a local-space system's motion too: 'hierarchy' is the mode that
+            // keeps such an effect's look. 'local' became the default with Unity's meaning.
+            json = {...json, scalingMode: 'hierarchy'};
+        }
         const dependencies: {[uuid: string]: Behavior} = {};
         const ps = ParticleSystem.fromJSON(json, meta, dependencies, this.scene);
         if (json?.shape?.type === 'mesh_surface' && typeof json.shape.mesh === 'string') {

package/src/QuarksSerializer.ts

@@ -23,7 +23,7 @@ import {textureSourceUrl} from './textureSource';
  * reads every earlier version, and files written before the field existed, and warns about a
  * file from a newer version.
  */
-export const QUARKS_FORMAT_VERSION = 1;
+export const QUARKS_FORMAT_VERSION = 2;
 
 /** An image a texture reads: a url, a root-relative path, or a `data:` URI. */
 export interface QuarksImageJSON {