babylon.quarks 0.27.0 → 0.29.0

package/src/ParticleSystem.ts

@@ -23,6 +23,7 @@ import {
     ParticleSystemEventType,
     Quaternion,
     RandomSource,
+    readFormatPart,
     RendererEmitterSettings,
     RotationGenerator,
     SerializationOptions,
@@ -60,10 +61,11 @@ import {
     moveTrails,
     recordTrailHistory,
     removeDeadTrails,
+    RingBufferStep,
     runBehaviorSteps,
     snapshotPreviousState,
 } from './system/integrate';
-import {liveAtlas, MaterialOverrides, resolveMaterialSettings} from './system/materialResolve';
+import {liveAtlas, MaterialOverrides, ParticleMaterialSource, resolveMaterialSettings} from './system/materialResolve';
 import {
     DEFAULT_SOFT_FAR_FADE,
     nonZeroFlip,
@@ -73,9 +75,14 @@ import {
     validAlphaTest,
     validCullingMode,
     validLighting,
+    validLoopRange,
     validMaxParticles,
+    validRenderFace,
+    validRingBufferMode,
+    validScalingMode,
     validSoftFade,
     validSortMode,
+    validStopAction,
     validTileCount,
 } from './system/normalize';
 import {ParticleSpawner} from './system/ParticleSpawner';
@@ -101,6 +108,7 @@ import {
     ParticleGradientMap,
     ParticleUVDistortion,
     ParticleUVDistortionOptions,
+    RenderFace,
     RenderMode,
     SortMode,
     TextureUV,
@@ -113,7 +121,9 @@ import type {
     CullingMode,
     ParticleSystemJSONParameters,
     ParticleSystemParameters,
+    RingBufferMode,
     ScalingMode,
+    StopAction,
 } from './system/types';
 
 export type {
@@ -124,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`.
@@ -152,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.
@@ -233,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.
@@ -295,7 +356,7 @@ export class ParticleSystem implements IParticleSystem {
     private readonly emission = new EmissionController(this, this.spawner);
     private readonly events = new EventDispatcher();
     private readonly layerMaskProxy: {mask: number};
-    private materialRef: any = null;
+    private materialRef: ParticleMaterialSource | null = null;
     private sceneRef: Scene | undefined;
     private qualityFactor = 1;
     private destroyed = false;
@@ -336,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);
     }
 
     /**
@@ -347,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,
@@ -395,11 +459,11 @@ export class ParticleSystem implements IParticleSystem {
      * is not drawn with; particles always use quarks' own shaders. Null leaves the settings as they
      * are.
      */
-    get material(): any {
+    get material(): ParticleMaterialSource | null {
         return this.materialRef;
     }
 
-    set material(material: any) {
+    set material(material: ParticleMaterialSource | null) {
         this.materialRef = material;
         this.applyMaterialSettings(material);
     }
@@ -473,6 +537,21 @@ export class ParticleSystem implements IParticleSystem {
         this.neededToUpdateRender = true;
     }
 
+    /**
+     * Which faces of a mesh particle are drawn (Unity's Render Face): `'both'` by default,
+     * `'front'` to cull the back faces of a closed mesh, `'back'` to see only its inside. Applies
+     * to the Mesh render mode; the other modes draw both faces. See {@link RenderFace}. Saved in
+     * the effect JSON only when not `'both'`.
+     */
+    get renderFace(): RenderFace {
+        return this.rendererSettings.renderFace ?? 'both';
+    }
+
+    set renderFace(face: RenderFace) {
+        this.rendererSettings.renderFace = validRenderFace(face);
+        this.neededToUpdateRender = true;
+    }
+
     /**
      * Smallest size a billboard or stretched particle is drawn at, as a
      * fraction of the viewport height (Unity's Min Particle Size); 0 by
@@ -620,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;
     }
 
@@ -930,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
@@ -946,6 +1042,24 @@ export class ParticleSystem implements IParticleSystem {
 
     private playbackSpeedValue = 1;
 
+    /**
+     * A runtime multiplier on {@link playbackSpeed} that is not part of the effect: what a
+     * timeline, a slow-motion moment or a game's pause menu sets on a system it plays, like
+     * Unreal's Custom Time Dilation or Unity's `VisualEffect.playRate`. The system runs at
+     * `playbackSpeed * timeDilation`. 1 by default; never saved, cloned or loaded. A negative,
+     * NaN or infinite value is read as 0. A `QuarksPrefab` sets it to its `timeScale` on the systems of
+     * its tracks.
+     */
+    get timeDilation(): number {
+        return this.timeDilationValue;
+    }
+
+    set timeDilation(dilation: number) {
+        this.timeDilationValue = dilation > 0 && dilation < Infinity ? dilation : 0;
+    }
+
+    private timeDilationValue = 1;
+
     /**
      * Runtime multiplier on how many particles the system emits: bursts,
      * emission over time and over distance alike. Unlike
@@ -967,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;
 
@@ -1058,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;
@@ -1073,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 ?? [];
@@ -1125,10 +1244,12 @@ export class ParticleSystem implements IParticleSystem {
             layerMask: parameters.layerMask ?? 0x0fffffff,
             pivot: nonZeroPivot(parameters.pivot),
             sortMode: validSortMode(parameters.sortMode),
+            renderFace: validRenderFace(parameters.renderFace),
             minParticleSize: Math.max(0, parameters.minParticleSize ?? 0),
             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),
@@ -1139,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();
@@ -1184,7 +1305,7 @@ export class ParticleSystem implements IParticleSystem {
      * ran) while the system still uses it, drops it and builds a new one if the cube is still alive,
      * so the batch never samples a disposed texture.
      */
-    private watchEnvAtlas(atlas: BaseTexture | null, material: any): void {
+    private watchEnvAtlas(atlas: BaseTexture | null, material: ParticleMaterialSource | null): void {
         atlas?.onDisposeObservable.addOnce(() => {
             if (this.destroyed || this.rendererSettings.reflectionAtlas !== atlas) {
                 return;
@@ -1211,7 +1332,7 @@ export class ParticleSystem implements IParticleSystem {
         });
     }
 
-    private applyMaterialSettings(material: any, overrides: MaterialOverrides = {}) {
+    private applyMaterialSettings(material: ParticleMaterialSource | null, overrides: MaterialOverrides = {}) {
         /* istanbul ignore if -- rendererSettings is always assigned in the constructor before any code path can call this private method */
         if (!this.rendererSettings) {
             return;
@@ -1261,10 +1382,30 @@ export class ParticleSystem implements IParticleSystem {
     }
 
     /**
-     * Resumes a paused system. It only resumes: a system that has finished ({@link isFinished})
-     * stays finished, since nothing is left to emit; {@link restart} plays it again from the start.
+     * Plays the system, like Unity's `Play`: a paused or stopped system resumes from where it is,
+     * and one that has finished ({@link isFinished}) starts over from the beginning, as
+     * {@link restart} does. A playing system that has not finished is left as it is. To undo a
+     * {@link pause} without replaying a system that had finished, use {@link resume}.
      */
     play(): void {
+        if (this.destroyed) {
+            return;
+        }
+        if (this.isFinished()) {
+            this.restart();
+        }
+        this.resume();
+    }
+
+    /**
+     * Undoes {@link pause}: the system goes on from where it is, and one that has finished stays
+     * finished. For a pause button over a whole scene, where {@link play} would replay the
+     * effects that had already ended.
+     */
+    resume(): void {
+        if (this.destroyed) {
+            return;
+        }
         this.paused = false;
         // A move made while paused is a placement, not motion to spread the next frame over.
         this.previousEmitterMatrix = undefined;
@@ -1327,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;
@@ -1406,16 +1547,12 @@ export class ParticleSystem implements IParticleSystem {
         // Bursts edited in place since the last play are put back in time order and in range.
         this.emissionBursts.forEach((burst) => Object.assign(burst, normalizeBurst(burst)));
         this.emissionBursts.sort((a, b) => a.time - b.time);
-        this.behaviors.forEach((behavior) => {
-            behavior.reset();
-            if (behavior instanceof EmitSubParticleSystem) {
-                behavior.clearEmissions();
-            }
-        });
+        this.behaviors.forEach((behavior) => behavior.reset());
         // A sweeping shape (Loop, PingPong) starts its arc over, so the replay is the same.
         this.emitterShape.reset?.();
         this.emitEnded = false;
         this.finishedEventFired = false;
+        this.stopActionPending = false;
         this.prewarmed = false;
         this.initSystemGenerators();
         this.previousEmitterPos = undefined;
@@ -1439,7 +1576,7 @@ export class ParticleSystem implements IParticleSystem {
      */
     update(delta: number, stepDeadline = Infinity, catchUpDeadline?: number) {
         if (this.paused || this.destroyed) return;
-        const speed = this.playbackSpeed;
+        const speed = this.playbackSpeed * this.timeDilationValue;
         delta = SimulationClock.frameSeconds(delta, speed);
 
         if (this.culled) {
@@ -1466,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
@@ -1647,9 +1787,9 @@ export class ParticleSystem implements IParticleSystem {
      * per-instance data, Unreal's user parameters). With {@link erosion},
      * alpha is the erosion level, so this wipes the shape in and out. The
      * particles' own colours are untouched, so clearing it restores them, and
-     * systems with different tints still batch together. Under additive
-     * (`ALPHA_ONEONE`) or premultiplied blending, which ignore alpha, fade
-     * with the colour instead, or with erosion on. Unset (the default): none.
+     * systems with different tints still batch together. Its alpha fades the
+     * particles in every blend mode that blends by coverage (see
+     * {@link blendCategory}). Unset (the default): none.
      * Not saved in the effect JSON; copied by {@link clone}.
      */
     tint?: Vector4;
@@ -1737,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);
@@ -1780,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,
@@ -1796,23 +1938,122 @@ 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();
 
+    /** The one `particleDied` event, filled in for each death so a death allocates nothing. */
+    private readonly particleDiedEvent: ParticleSystemEvent = {type: 'particleDied', particleSystem: this};
+
     /** Fires `particleDied` for a particle the step retired. */
     private readonly fireParticleDied = (particle: Particle): void => {
-        this.events.fire({type: 'particleDied', particleSystem: this, particle});
+        const event = this.particleDiedEvent;
+        event.particle = particle;
+        this.events.fire(event);
+        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();
         }
     }
@@ -1850,10 +2091,11 @@ export class ParticleSystem implements IParticleSystem {
     ): ParticleSystem {
         const ps = new ParticleSystem(particleSystemParametersFromJSON(json, meta, scene));
         ps.behaviors = (json.behaviors ?? [])
-            .map((behaviorJson) => {
-                const behavior = BehaviorFromJSON(behaviorJson, ps);
-                if (behavior && behavior.type === 'EmitSubParticleSystem') {
-                    dependencies[(behaviorJson as {subParticleSystem: string}).subParticleSystem] = behavior;
+            .map((behaviorJson, index) => {
+                const behavior = readFormatPart(`behaviors[${index}]`, () => BehaviorFromJSON(behaviorJson, ps));
+                const target = (behaviorJson as {subParticleSystem?: unknown}).subParticleSystem;
+                if (behavior && behavior.type === 'EmitSubParticleSystem' && typeof target === 'string') {
+                    dependencies[target] = behavior;
                 }
                 return behavior;
             })
@@ -1880,13 +2122,21 @@ export class ParticleSystem implements IParticleSystem {
      * Calls `callback` on each `event`: `'emitEnd'` when emission ends, `'finished'` when the last
      * particle of an ended system dies, `'particleDied'` per particle (with `event.particle`), and
      * `'destroy'` on dispose.
+     *
+     * A `'particleDied'` event and the particle on it are reused: read what you need inside the
+     * callback and keep neither, since the particle's slot goes to the next one spawned. In trail
+     * mode a particle dies when its trail is gone, so with a trail lifetime the event comes after
+     * the head stopped, once the last sample has faded.
+     *
+     * A callback added or removed while an event is firing takes effect from the next event; the
+     * callbacks of the one firing are all called.
      */
     addEventListener(event: ParticleSystemEventType, callback: (event: ParticleSystemEvent) => void): void {
         this.events.add(event, callback);
     }
 
-    /** Removes every callback registered for `event`. */
-    removeAllEventListeners(event: ParticleSystemEventType): void {
+    /** Removes every callback registered for `event`, or every callback of every event when it is left out. */
+    removeAllEventListeners(event?: ParticleSystemEventType): void {
         this.events.removeAll(event);
     }