babylon.quarks 0.28.0 → 0.29.0

package/src/shaders/chunks/imageProcessing.ts

@@ -0,0 +1,143 @@
+/**
+ * The scene's image processing for the particle shaders, in both shader languages.
+ *
+ * Babylon's own includes do the work (`imageProcessingDeclaration`, `helperFunctions`,
+ * `imageProcessingFunctions`), so the particles are tone mapped, graded and vignetted exactly as
+ * the scene's standard and PBR materials and its built-in particle systems are. The defines come
+ * from `ImageProcessingConfiguration.prepareDefines`, see `imageProcessingDefines` in
+ * `shaderProgram.ts`:
+ *
+ * - `IMAGEPROCESSING`: the material applies the configuration. The colour, authored in gamma
+ *   space, is brought to linear space and `applyImageProcessing` returns it to gamma space with
+ *   the configuration's effects on the way.
+ * - `IMAGEPROCESSINGPOSTPROCESS`: a post process applies it later, to the frame; the material only
+ *   leaves its colour in the linear space that post process expects.
+ *
+ * The step runs on the straight colour, after the fog and the soft fade and before the blend
+ * resolve (`blend.ts`), so the resolve's meaning of alpha survives it: a premultiplied colour is
+ * the processed colour times its coverage. Particles that multiply the frame (`BLEND_MULTIPLY`)
+ * are a factor, not light, so `shaderProgram` compiles no in-material processing for them, and
+ * under a post process their resolved factor is brought to linear space after the resolve: white,
+ * which leaves the frame as it is, stays white.
+ */
+
+import {ShaderStore} from '@babylonjs/core/Engines/shaderStore';
+import '@babylonjs/core/Shaders/ShadersInclude/helperFunctions';
+import '@babylonjs/core/Shaders/ShadersInclude/imageProcessingDeclaration';
+import '@babylonjs/core/Shaders/ShadersInclude/imageProcessingFunctions';
+import '@babylonjs/core/ShadersWGSL/ShadersInclude/helperFunctions';
+import '@babylonjs/core/ShadersWGSL/ShadersInclude/imageProcessingDeclaration';
+import '@babylonjs/core/ShadersWGSL/ShadersInclude/imageProcessingFunctions';
+
+/**
+ * Babylon's WGSL `imageProcessingFunctions` samples a 2D colour grading texture (a LUT laid out as
+ * slices) with a `textureSample` overload WGSL does not have, so it does not compile; its GLSL
+ * reads the slices through a `sampleTexture3D` polyfill. This is that polyfill in WGSL, and the
+ * include with the call routed through it, registered as `quarksImageProcessingFunctions`. When a
+ * Babylon release fixes the call, the include is registered as it comes.
+ */
+const SAMPLE_TEXTURE_3D_WGSL = /* wgsl */ `
+#if defined(COLORGRADING) && !defined(COLORGRADING3D)
+fn quarksSampleTexture3D(colorTransform: texture_2d<f32>, colorTransformSampler: sampler, colorIn: vec3f, sampler3dSetting: vec2f) -> vec3f {
+    let sliceSize = 2.0 * sampler3dSetting.x;
+#ifdef SAMPLER3DGREENDEPTH
+    let sliceContinuous = (colorIn.g - sampler3dSetting.x) * sampler3dSetting.y;
+    var sliceUV = colorIn.rb;
+#else
+    let sliceContinuous = (colorIn.b - sampler3dSetting.x) * sampler3dSetting.y;
+    var sliceUV = colorIn.rg;
+#endif
+    let sliceInteger = floor(sliceContinuous);
+    let sliceFraction = sliceContinuous - sliceInteger;
+    sliceUV.x = sliceUV.x * sliceSize + sliceInteger * sliceSize;
+    let slice0Color = textureSample(colorTransform, colorTransformSampler, clamp(sliceUV, vec2f(0.0), vec2f(1.0)));
+    let slice1Color = textureSample(colorTransform, colorTransformSampler, clamp(sliceUV + vec2f(sliceSize, 0.0), vec2f(0.0), vec2f(1.0)));
+    let result = mix(slice0Color.rgb, slice1Color.rgb, sliceFraction);
+#ifdef SAMPLER3DBGRMAP
+    return result.rgb;
+#else
+    return result.bgr;
+#endif
+}
+#endif
+`;
+
+const BROKEN_2D_SAMPLE =
+    'textureSample(txColorTransform,txColorTransformSampler,colorTransformInput,uniforms.colorTransformSettings.yz).rgb';
+
+const babylonFunctionsWGSL = ShaderStore.IncludesShadersStoreWGSL['imageProcessingFunctions'];
+
+/**
+ * Whether Babylon's WGSL include still has the broken call, and so is registered patched. The
+ * tests pin this for the Babylon version the library is built against, and the shader validation
+ * compiles 2D colour grading in WGSL, so a Babylon release that changes the include is noticed.
+ * @internal
+ */
+export const PATCHES_IMAGE_PROCESSING_WGSL = babylonFunctionsWGSL.includes(BROKEN_2D_SAMPLE);
+
+ShaderStore.IncludesShadersStoreWGSL['quarksImageProcessingFunctions'] = PATCHES_IMAGE_PROCESSING_WGSL
+    ? SAMPLE_TEXTURE_3D_WGSL +
+      babylonFunctionsWGSL.replace(
+          BROKEN_2D_SAMPLE,
+          'quarksSampleTexture3D(txColorTransform,txColorTransformSampler,colorTransformInput,uniforms.colorTransformSettings.yz)'
+      )
+    : babylonFunctionsWGSL;
+
+/** Fragment-side declaration, GLSL. */
+export const imageProcessingDeclarationGLSL = /* glsl */ `
+#if defined(IMAGEPROCESSING) || defined(IMAGEPROCESSINGPOSTPROCESS)
+#include<imageProcessingDeclaration>
+#include<helperFunctions>
+#include<imageProcessingFunctions>
+#endif
+`;
+
+/** Processes the straight vec4 lvalue `color`, before the blend resolve, GLSL. */
+export function imageProcessingFragmentGLSL(color: string): string {
+    return /* glsl */ `
+#if defined(IMAGEPROCESSINGPOSTPROCESS) && !defined(BLEND_MULTIPLY)
+    ${color}.rgb = toLinearSpace(${color}.rgb);
+#elif defined(IMAGEPROCESSING)
+    ${color}.rgb = toLinearSpace(${color}.rgb);
+    ${color} = applyImageProcessing(${color});
+#endif
+`;
+}
+
+/** Brings a resolved multiply factor in `color` to linear space for a post process, GLSL. */
+export function imageProcessingResolvedGLSL(color: string): string {
+    return /* glsl */ `
+#if defined(IMAGEPROCESSINGPOSTPROCESS) && defined(BLEND_MULTIPLY)
+    ${color}.rgb = toLinearSpace(${color}.rgb);
+#endif
+`;
+}
+
+/** Fragment-side declaration, WGSL. */
+export const imageProcessingDeclarationWGSL = /* wgsl */ `
+#if defined(IMAGEPROCESSING) || defined(IMAGEPROCESSINGPOSTPROCESS)
+#include<imageProcessingDeclaration>
+#include<helperFunctions>
+#include<quarksImageProcessingFunctions>
+#endif
+`;
+
+/** Processes the straight `var` vec4 `color`, before the blend resolve, WGSL. */
+export function imageProcessingFragmentWGSL(color: string): string {
+    return /* wgsl */ `
+#if defined(IMAGEPROCESSINGPOSTPROCESS) && !defined(BLEND_MULTIPLY)
+    ${color} = vec4f(toLinearSpaceVec3(${color}.rgb), ${color}.a);
+#elif defined(IMAGEPROCESSING)
+    ${color} = applyImageProcessing(vec4f(toLinearSpaceVec3(${color}.rgb), ${color}.a));
+#endif
+`;
+}
+
+/** Brings a resolved multiply factor in `color` to linear space for a post process, WGSL. */
+export function imageProcessingResolvedWGSL(color: string): string {
+    return /* wgsl */ `
+#if defined(IMAGEPROCESSINGPOSTPROCESS) && defined(BLEND_MULTIPLY)
+    ${color} = vec4f(toLinearSpaceVec3(${color}.rgb), ${color}.a);
+#endif
+`;
+}

package/src/shaders/particle_frag.glsl.ts

@@ -1,5 +1,6 @@
 import {blendFragmentGLSL} from './chunks/blend';
 import {fogFragmentDeclarationGLSL, fogFragmentGLSL} from './chunks/fog';
+import {imageProcessingDeclarationGLSL} from './chunks/imageProcessing';
 import {softFragmentDeclarationGLSL, softFragmentGLSL} from './chunks/soft';
 import {surfaceColorGLSL, surfaceFragmentDeclarationGLSL} from './chunks/surface';
 
@@ -25,6 +26,7 @@ uniform float alphaTest;
 #endif
 
 ${fogFragmentDeclarationGLSL}
+${imageProcessingDeclarationGLSL}
 ${softFragmentDeclarationGLSL}
 ${surfaceFragmentDeclarationGLSL}
 void main() {

package/src/shaders/particle_frag.wgsl.ts

@@ -1,5 +1,6 @@
 import {blendFragmentWGSL} from './chunks/blend';
 import {fogFragmentDeclarationWGSL, fogFragmentWGSL} from './chunks/fog';
+import {imageProcessingDeclarationWGSL} from './chunks/imageProcessing';
 import {softFragmentDeclarationWGSL, softFragmentWGSL} from './chunks/soft';
 import {surfaceColorWGSL, surfaceFragmentDeclarationWGSL} from './chunks/surface';
 
@@ -26,6 +27,7 @@ uniform alphaTest: f32;
 #endif
 
 ${fogFragmentDeclarationWGSL}
+${imageProcessingDeclarationWGSL}
 ${softFragmentDeclarationWGSL}
 ${surfaceFragmentDeclarationWGSL}
 @fragment

package/src/shaders/particle_physics_frag.glsl.ts

@@ -1,5 +1,6 @@
 import {blendFragmentGLSL} from './chunks/blend';
 import {fogFragmentDeclarationGLSL, fogFragmentGLSL} from './chunks/fog';
+import {imageProcessingDeclarationGLSL} from './chunks/imageProcessing';
 import {softFragmentDeclarationGLSL, softFragmentGLSL} from './chunks/soft';
 import {surfaceColorGLSL, surfaceFragmentDeclarationGLSL} from './chunks/surface';
 
@@ -87,6 +88,7 @@ uniform float alphaTest;
 #endif
 
 ${fogFragmentDeclarationGLSL}
+${imageProcessingDeclarationGLSL}
 ${softFragmentDeclarationGLSL}
 ${surfaceFragmentDeclarationGLSL}
 void main() {

package/src/shaders/particle_physics_frag.wgsl.ts

@@ -1,5 +1,6 @@
 import {blendFragmentWGSL} from './chunks/blend';
 import {fogFragmentDeclarationWGSL, fogFragmentWGSL} from './chunks/fog';
+import {imageProcessingDeclarationWGSL} from './chunks/imageProcessing';
 import {softFragmentDeclarationWGSL, softFragmentWGSL} from './chunks/soft';
 import {surfaceColorWGSL, surfaceFragmentDeclarationWGSL} from './chunks/surface';
 
@@ -86,6 +87,7 @@ uniform alphaTest: f32;
 #endif
 
 ${fogFragmentDeclarationWGSL}
+${imageProcessingDeclarationWGSL}
 ${softFragmentDeclarationWGSL}
 ${surfaceFragmentDeclarationWGSL}
 @fragment

package/src/shaders/trail_frag.glsl.ts

@@ -1,5 +1,6 @@
 import {blendFragmentGLSL} from './chunks/blend';
 import {fogFragmentDeclarationGLSL, fogFragmentGLSL} from './chunks/fog';
+import {imageProcessingDeclarationGLSL} from './chunks/imageProcessing';
 import {softFragmentDeclarationGLSL, softFragmentGLSL} from './chunks/soft';
 import {surfaceColorGLSL, surfaceFragmentDeclarationGLSL} from './chunks/surface';
 
@@ -19,6 +20,7 @@ uniform float alphaTest;
 #endif
 
 ${fogFragmentDeclarationGLSL}
+${imageProcessingDeclarationGLSL}
 ${softFragmentDeclarationGLSL}
 ${surfaceFragmentDeclarationGLSL}
 void main() {

package/src/shaders/trail_frag.wgsl.ts

@@ -1,5 +1,6 @@
 import {blendFragmentWGSL} from './chunks/blend';
 import {fogFragmentDeclarationWGSL, fogFragmentWGSL} from './chunks/fog';
+import {imageProcessingDeclarationWGSL} from './chunks/imageProcessing';
 import {softFragmentDeclarationWGSL, softFragmentWGSL} from './chunks/soft';
 import {surfaceColorWGSL, surfaceFragmentDeclarationWGSL} from './chunks/surface';
 
@@ -20,6 +21,7 @@ uniform alphaTest: f32;
 #endif
 
 ${fogFragmentDeclarationWGSL}
+${imageProcessingDeclarationWGSL}
 ${softFragmentDeclarationWGSL}
 ${surfaceFragmentDeclarationWGSL}
 @fragment

package/src/system/EmissionController.ts

@@ -5,6 +5,7 @@ import {
     Matrix4,
     PiecewiseBezier,
     random,
+    RandomBetweenCurves,
     ValueGenerator,
     Vector3,
 } from 'quarks.core';
@@ -65,19 +66,24 @@ export class EmissionController {
         return delay;
     }
 
-    /** Whether continuous or queued emission can still spawn particles before the system is done. */
-    hasPendingEmission(): boolean {
+    /**
+     * Whether continuous or queued emission can still spawn particles before the system is done:
+     * its own, or with `state` the emission a sub emitter runs into it for one parent particle.
+     */
+    hasPendingEmission(state?: EmissionState): boolean {
         const system = this.system;
-        if (system.isEmitEnded) {
-            return false;
-        }
-        if (system.looping) {
-            return true;
-        }
-        if (system.onlyUsedByOther) {
-            return false;
+        if (state === undefined || state === system.emissionState) {
+            if (system.isEmitEnded) {
+                return false;
+            }
+            if (system.looping) {
+                return true;
+            }
+            if (system.onlyUsedByOther) {
+                return false;
+            }
+            state = system.emissionState;
         }
-        const state = system.emissionState;
         if (state.waitEmiting > 0) {
             return true;
         }
@@ -108,6 +114,10 @@ export class EmissionController {
         if (rate.type !== 'function') {
             return false;
         }
+        if (rate instanceof RandomBetweenCurves) {
+            // Every mix lies between the two curves, so it emits later if either does.
+            return this.emitsFrom(rate.curve1, timeRatio) || this.emitsFrom(rate.curve2, timeRatio);
+        }
         if (rate instanceof PiecewiseBezier) {
             // A Bezier stays within its control points, so this is exact however short a pulse.
             for (let i = 0; i < rate.functions.length; i++) {
@@ -176,11 +186,6 @@ export class EmissionController {
             }
         }
 
-        // Only spawns in world space consume the normal matrix, and computing it
-        // inverts a 4x4 — skip it for local-space systems.
-        if (system.worldSpace) {
-            this.spawner.normalMatrix.getNormalMatrix(emitterMatrix);
-        }
         const qualityFactor = system.emissionFactor();
 
         if (system.emissionBursts.length > 0 && !endedBefore) {

package/src/system/ParticleSpawner.ts

@@ -18,13 +18,14 @@ import type {ParticleSystem} from '../ParticleSystem';
 import {RenderMode} from '../VFXBatch';
 
 /** Particle backed by a `ParticleStore` row, as a system always creates. */
-type StoreBackedParticle = Particle & {storeIndex: number};
+type StoreBackedParticle = Particle & {storeIndex: number; setStoreIndex(index: number): void};
 
 const UP = new Vector3(0, 0, 1);
 const IDENTITY_QUATERNION = new Quaternion();
 const tempQ = new Quaternion();
 const tempV = new Vector3();
 const tempV2 = new Vector3();
+const tempM3 = new Matrix3();
 
 /**
  * Gives a system its newborn particles: grows the pool and the store they live in, rolls each
@@ -33,13 +34,64 @@ const tempV2 = new Vector3();
  * spawn and when, this decides what each one starts as.
  */
 export class ParticleSpawner {
+    constructor(private readonly system: ParticleSystem) {}
+
     /**
-     * The emitter matrix's normal matrix, for turning a world-space newborn's velocity. The
-     * emission controller refreshes it before it spawns from a world-space system.
+     * The row a full ring buffer replaces next, the oldest. Particles of a ring buffer never die,
+     * so they stay in the order they were born: the oldest is row 0 when the system fills up, and
+     * the cursor walks on from there.
      */
-    readonly normalMatrix = new Matrix3();
+    private ringCursor = 0;
 
-    constructor(private readonly system: ParticleSystem) {}
+    /** Swaps rows `a` and `b`: the particle objects and their store rows. */
+    private swapRows(a: number, b: number): void {
+        const particles = this.system.particles;
+        const first = particles[a] as StoreBackedParticle;
+        const second = particles[b] as StoreBackedParticle;
+        particles[a] = second;
+        particles[b] = first;
+        this.system.store.swapRows(a, b);
+        second.setStoreIndex(a);
+        first.setStoreIndex(b);
+    }
+
+    /** Reverses rows `from` to `to`, inclusive. */
+    private reverseRows(from: number, to: number): void {
+        for (; from < to; from++, to--) {
+            this.swapRows(from, to);
+        }
+    }
+
+    /** Moves the first `by` of the `count` live rows to the end, keeping the order of both parts. */
+    private rotateRows(by: number, count: number): void {
+        if (by <= 0 || by >= count) {
+            return;
+        }
+        this.reverseRows(0, by - 1);
+        this.reverseRows(by, count - 1);
+        this.reverseRows(0, count - 1);
+    }
+
+    /**
+     * Keeps a ring buffer within `maxParticles` once it was lowered: its particles never die, so
+     * the oldest over the limit are dropped, and the rest stay in birth order from row 0. Called
+     * at the start of every step; costs nothing while the system is within its limit.
+     */
+    fitRing(): void {
+        const system = this.system;
+        const max = system.maxParticles;
+        const count = system.particleNum;
+        if (max === undefined || count <= max || system.ringBufferMode === 'disabled') {
+            return;
+        }
+        if (system.rendererSettings.renderMode === RenderMode.Trail) {
+            return;
+        }
+        // Oldest first from the cursor: the survivors start `count - max` rows after it.
+        this.rotateRows((this.ringCursor + count - max) % count, count);
+        system.particleNum = max;
+        this.ringCursor = 0;
+    }
 
     /** Points every particle at the store's columns again, after any were replaced. */
     rebind(): void {
@@ -75,6 +127,7 @@ export class ParticleSpawner {
         const scale = tempV2;
         // decompose writes tempQ, so no separate setFromRotationMatrix is needed.
         matrix.decompose(translation, tempQ, scale);
+        const linear = tempM3.setFromMatrix4(matrix);
         const behaviors = system.behaviors;
         const behaviorCount = behaviors.length;
         const renderMode = system.rendererSettings.renderMode;
@@ -89,20 +142,43 @@ export class ParticleSpawner {
         const trailSettings = isTrailMode ? (system.rendererEmitterSettings as TrailSettings) : undefined;
         const followLocalOrigin = Boolean(trailSettings?.followLocalOrigin);
         const worldSpace = system.worldSpace;
-        const hierarchy = system.scalingMode === 'hierarchy';
+        // The emitter's matrix carries the scale the scaling mode applies (see
+        // `ParticleEmitter.matrixWorld`); 'shape' scales the shape alone, here.
+        const shapeScale = system.scalingMode === 'shape' ? system.emitter.shapeScale : undefined;
         const particles = system.particles;
-        if (system.maxParticles !== undefined) {
-            // Like Unity, a full system skips the particles it has no room for rather than queueing them.
-            count = Math.min(count, Math.max(0, system.maxParticles - system.particleNum));
+        const maxParticles = system.maxParticles;
+        // A ring buffer replaces the oldest particles of a full system (see `ringBufferMode`).
+        const ring = maxParticles !== undefined && system.ringBufferMode !== 'disabled' && !isTrailMode;
+        if (maxParticles !== undefined) {
+            // Like Unity, a full system skips the particles it has no room for rather than
+            // queueing them; a ring buffer replaces at most every particle once.
+            count = ring
+                ? Math.min(count, maxParticles)
+                : Math.min(count, Math.max(0, maxParticles - system.particleNum));
         }
 
         for (let i = 0; i < count; i++) {
             emissionState.burstParticleIndex = i;
-            system.particleNum++;
-            if (particles.length < system.particleNum) {
-                this.grow(isTrailMode);
+            let particle: Particle;
+            if (ring && system.particleNum >= maxParticles) {
+                if (this.ringCursor >= system.particleNum) {
+                    this.ringCursor = 0;
+                }
+                particle = particles[this.ringCursor];
+                this.ringCursor = (this.ringCursor + 1) % system.particleNum;
+            } else {
+                if (ring && this.ringCursor !== 0) {
+                    // A ring that wrapped and was given room (a higher limit): put its oldest at
+                    // row 0 again, so the newborn appended after the newest stays in birth order.
+                    this.rotateRows(this.ringCursor, system.particleNum);
+                    this.ringCursor = 0;
+                }
+                system.particleNum++;
+                if (particles.length < system.particleNum) {
+                    this.grow(isTrailMode);
+                }
+                particle = particles[system.particleNum - 1];
             }
-            const particle = particles[system.particleNum - 1];
             particle.reset();
             particle.serial = (particle.serial ?? 0) + 1;
             particle.speedModifier = 1;
@@ -178,6 +254,9 @@ export class ParticleSpawner {
             }
 
             system.emitterShape.initialize(particle, emissionState);
+            if (shapeScale !== undefined) {
+                particle.position.multiply(shapeScale);
+            }
 
             if (system.alignToDirection && isSpriteMode) {
                 alignParticleToDirection(particle as SpriteParticle, isMeshMode);
@@ -201,12 +280,10 @@ export class ParticleSpawner {
                 particle.position.applyMatrix4(matrix);
                 particle.startSize.multiply(scale).abs();
                 particle.size.copy(particle.startSize);
-                if (hierarchy) {
-                    // Scaled per axis by the emitter's world scale, then turned: the speed scales with it.
-                    particle.velocity.multiply(system.hierarchyScale).applyQuaternion(tempQ);
-                } else {
-                    particle.velocity.multiply(scale).applyMatrix3(this.normalMatrix);
-                }
+                // Through the matrix's own axes, as the position is: scaled, turned and mirrored
+                // with it. For a sub emission that is the parent particle's frame, the same one
+                // its start size takes.
+                particle.velocity.applyMatrix3(linear);
                 if (particle.rotation && particle.rotation instanceof Quaternion) {
                     particle.rotation.multiplyQuaternions(tempQ, particle.rotation);
                 }

package/src/system/integrate.ts

@@ -129,6 +129,34 @@ function retire(particles: Particle[], store: ParticleStore, i: number, last: nu
     return particle;
 }
 
+/**
+ * What a ring buffer does to a particle at the end of its life (see `RingBufferMode`): `pause`
+ * holds it frozen at its end, else it goes back to `loopStart` (a fraction of its life) once it
+ * reaches `loopEnd`.
+ */
+export interface RingBufferStep {
+    /** Freeze at the end of life rather than loop. */
+    pause: boolean;
+    /** Where a looping particle goes back to, a fraction of its life, 0 to 1. */
+    loopStart: number;
+    /**
+     * Where a looping particle goes back from, a fraction of its life, `loopStart` to 1. Equal to
+     * `loopStart`, the particle is held there.
+     */
+    loopEnd: number;
+}
+
+/** The least age a held particle keeps, as a fraction of its life: past 0, a newborn's age. */
+const HELD_AGE = 1e-6;
+
+/**
+ * The age a looping ring particle is held at, or Infinity when it loops: a loop range of no
+ * length holds it at that point of its life, as a pause does at the end.
+ */
+function holdAge(ring: RingBufferStep, life: number): number {
+    return ring.loopEnd > ring.loopStart ? Infinity : Math.max(ring.loopEnd, HELD_AGE) * life;
+}
+
 /**
  * The sprite path's step after the behaviors, as one pass over the columns that does three
  * things, none of which touches a particle object until a death. Returns the live count.
@@ -142,7 +170,8 @@ function retire(particles: Particle[], store: ParticleStore, i: number, last: nu
  * Position is integrated along the velocity.
  *
  * A particle whose age reached its life is swapped with the last live one, rows included. The
- * survivor moved into the slot has not been visited yet, so the slot is processed again.
+ * survivor moved into the slot has not been visited yet, so the slot is processed again. With a
+ * `ring` buffer no particle dies: it is frozen at the end of its life, or sent back into it.
  *
  * The bounds fall out of the same pass. Measuring every particle on every step costs about as
  * much as the integration itself, so the full measurement runs every few steps; in between,
@@ -158,9 +187,11 @@ export function integrateSprites(
     collapseColor: boolean,
     bounds: BoundsTracker,
     settings: BoundsSettings,
-    onDied: DeathListener | undefined
+    onDied: DeathListener | undefined,
+    ring?: RingBufferStep
 ): number {
     const scalars = store.scalars;
+    const pause = ring !== undefined && ring.pause;
     const stride = ParticleStore.SCALAR_STRIDE;
     const positions = store.position;
     const velocities = store.velocity;
@@ -198,7 +229,12 @@ export function integrateSprites(
                 prevColor[o4 + 3] = curColor[o4 + 3];
             }
         }
-        const step = delta * scalars[scalar + ParticleStore.SPEED_MODIFIER];
+        const life = scalars[scalar + ParticleStore.LIFE];
+        // Frozen until a newborn replaces it, no motion and no ageing: at the end of its life when
+        // paused, or at a loop range of no length, held a hair past 0 so Birth fires only once.
+        const hold = ring === undefined ? Infinity : pause ? life : holdAge(ring, life);
+        const frozen = age >= hold;
+        const step = frozen ? 0 : delta * scalars[scalar + ParticleStore.SPEED_MODIFIER];
         const vx = velocities[offset];
         const vy = velocities[offset + 1];
         const vz = velocities[offset + 2];
@@ -219,10 +255,31 @@ export function integrateSprites(
         }
         // Speed is tracked every step: it bounds how far the particles
         // can have moved since the last measurement.
+        if (frozen) {
+            continue;
+        }
         maxSpeedSq = Math.max(maxSpeedSq, vx * vx + vy * vy + vz * vz);
         age += delta;
         scalars[scalar + ParticleStore.AGE] = age;
-        if (age >= scalars[scalar + ParticleStore.LIFE]) {
+        if (ring !== undefined) {
+            if (age > hold) {
+                scalars[scalar + ParticleStore.AGE] = hold;
+            } else if (!pause && hold === Infinity && age >= ring.loopEnd * life) {
+                const loopStart = ring.loopStart * life;
+                const wrapped = loopStart + ((age - ring.loopEnd * life) % ((ring.loopEnd - ring.loopStart) * life));
+                // Never exactly 0, which is a newborn's age: Birth sub emitters would fire again.
+                scalars[scalar + ParticleStore.AGE] = wrapped > 0 ? wrapped : HELD_AGE * life;
+                // The jump back is not motion: the renderer must not extrapolate size or colour across it.
+                prevSize[offset] = curSize[offset];
+                prevSize[offset + 1] = curSize[offset + 1];
+                prevSize[offset + 2] = curSize[offset + 2];
+                const o4 = i * 4;
+                prevColor[o4] = curColor[o4];
+                prevColor[o4 + 1] = curColor[o4 + 1];
+                prevColor[o4 + 2] = curColor[o4 + 2];
+                prevColor[o4 + 3] = curColor[o4 + 3];
+            }
+        } else if (age >= life) {
             const particle = retire(particles, store, i, liveParticleCount - 1);
             liveParticleCount--;
             i--;

package/src/system/normalize.ts

@@ -1,6 +1,6 @@
 import {ConstantValue, FunctionValueGenerator, ValueGenerator, Vector2, Vector3} from 'quarks.core';
 import type {MeshLighting, RenderFace, SortMode} from '../batchSettings';
-import type {BurstParameters, CullingMode} from './types';
+import type {BurstParameters, CullingMode, RingBufferMode, ScalingMode, StopAction} from './types';
 
 // Normalisers shared by the ParticleSystem constructor, its setters and its JSON reader, so a
 // value read from a file and one set in code end up the same.
@@ -25,6 +25,33 @@ export function validCullingMode(mode: unknown): CullingMode {
     return mode === 'pause' || mode === 'pauseAndCatchUp' ? mode : 'always';
 }
 
+/** `action` if it is one of the stop actions, else `'none'`. */
+export function validStopAction(action: unknown): StopAction {
+    return action === 'disable' || action === 'destroy' ? action : 'none';
+}
+
+/** `mode` if it is one of the ring buffer modes, else `'disabled'`. */
+export function validRingBufferMode(mode: unknown): RingBufferMode {
+    return mode === 'pauseUntilReplaced' || mode === 'loopUntilReplaced' ? mode : 'disabled';
+}
+
+/**
+ * A ring buffer loop range within 0..1, start no later than end; a missing or non-finite bound
+ * takes its default (0 or 1).
+ */
+export function validLoopRange(range: {x: number; y: number} | undefined): Vector2 {
+    const clamp = (value: number | undefined, fallback: number) =>
+        typeof value === 'number' && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : fallback;
+    const start = clamp(range?.x, 0);
+    const end = clamp(range?.y, 1);
+    return new Vector2(Math.min(start, end), Math.max(start, end));
+}
+
+/** `mode` if it is one of the scaling modes, else `'local'`. */
+export function validScalingMode(mode: unknown): ScalingMode {
+    return mode === 'hierarchy' || mode === 'shape' ? mode : 'local';
+}
+
 /** `count` as a whole number of particles, or undefined (no limit) when it is unset, NaN or negative. */
 export function validMaxParticles(count: unknown): number | undefined {
     return typeof count === 'number' && count >= 0 && count < Infinity ? Math.floor(count) : undefined;