babylon.quarks 0.27.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/chunks/soft.ts

@@ -4,7 +4,8 @@
  * The fragment reads the scene depth behind it from `depthTexture`, turns it into view depth with
  * the coefficients in `projParams` (see `softDepthParams`), and fades out over the distance in
  * `softParams` as it nears the scene, as Unity's soft particles and Unreal's Depth Fade do. The
- * fade runs last, after fog, so both languages produce the same colour.
+ * fade lowers alpha only and runs after fog and before the blend resolve (`blend.ts`), so it reads
+ * as coverage in every blend mode and both languages produce the same colour.
  *
  * `SOFT_DEPTH_PACKED` reads a depth packed into four 8-bit channels, as a Babylon
  * `DepthRenderer` of type `UNSIGNED_BYTE` writes it.
@@ -33,14 +34,14 @@ float quarksSceneDepth(vec4 texel) {
 #endif
 `;
 
-/** Fades `target` as the fragment nears the scene behind it, GLSL. */
+/** Fades the alpha of the vec4 lvalue `target` as the fragment nears the scene behind it, GLSL. */
 export function softFragmentGLSL(target: string): string {
     return /* glsl */ `
 #ifdef SOFT_PARTICLES
     {
         vec2 softUV = 0.5 * (projPosition.xy / projPosition.w) + 0.5;
         float sceneDepth = quarksSceneDepth(texture2D(depthTexture, softUV));
-        ${target} *= clamp(softParams.y * ((sceneDepth - softParams.x) - linearDepth), 0.0, 1.0);
+        ${target}.a *= clamp(softParams.y * ((sceneDepth - softParams.x) - linearDepth), 0.0, 1.0);
     }
 #endif
 `;
@@ -70,14 +71,14 @@ fn quarksSceneDepth(texel: vec4f) -> f32 {
 #endif
 `;
 
-/** Fades `target` as the fragment nears the scene behind it, WGSL. */
+/** Fades the alpha of the `var` vec4 `target` as the fragment nears the scene behind it, WGSL. */
 export function softFragmentWGSL(target: string): string {
     return /* wgsl */ `
 #ifdef SOFT_PARTICLES
     {
         let softUV = 0.5 * (fragmentInputs.projPosition.xy / fragmentInputs.projPosition.w) + 0.5;
         let sceneDepth = quarksSceneDepth(textureSample(depthTexture, depthTextureSampler, softUV));
-        ${target} *= clamp(uniforms.softParams.y * ((sceneDepth - uniforms.softParams.x) - fragmentInputs.linearDepth), 0.0, 1.0);
+        ${target}.a *= clamp(uniforms.softParams.y * ((sceneDepth - uniforms.softParams.x) - fragmentInputs.linearDepth), 0.0, 1.0);
     }
 #endif
 `;

package/src/shaders/chunks/surface.ts

@@ -35,8 +35,8 @@
  *   on the way down the shape eats away from its lowest mask values first — a
  *   noise mask dissolves it, a gradient mask wipes it. `erosionParams` is
  *   (softness, edge width); the edge band just above the cut glows in
- *   `erosionEdgeColor`. Erosion only changes alpha, so blend modes that
- *   ignore alpha (one-one, premultiplied) show a hard cut.
+ *   `erosionEdgeColor`. Erosion only changes alpha, which the blend resolve
+ *   (`blend.ts`) turns into coverage in every blend mode.
  */
 
 /** Fragment-side declarations, GLSL. */

package/src/shaders/particle_frag.glsl.ts

@@ -1,4 +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';
 
@@ -24,6 +26,7 @@ uniform float alphaTest;
 #endif
 
 ${fogFragmentDeclarationGLSL}
+${imageProcessingDeclarationGLSL}
 ${softFragmentDeclarationGLSL}
 ${surfaceFragmentDeclarationGLSL}
 void main() {
@@ -35,7 +38,8 @@ ${surfaceColorGLSL(true)}
 #endif
 
 ${fogFragmentGLSL('baseColor.rgb')}
+${softFragmentGLSL('baseColor')}
+${blendFragmentGLSL('baseColor')}
     gl_FragColor = baseColor;
-${softFragmentGLSL('gl_FragColor')}
 }
 `;

package/src/shaders/particle_frag.wgsl.ts

@@ -1,4 +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';
 
@@ -25,6 +27,7 @@ uniform alphaTest: f32;
 #endif
 
 ${fogFragmentDeclarationWGSL}
+${imageProcessingDeclarationWGSL}
 ${softFragmentDeclarationWGSL}
 ${surfaceFragmentDeclarationWGSL}
 @fragment
@@ -38,6 +41,7 @@ ${surfaceColorWGSL(true)}
 
 ${fogFragmentWGSL('baseColor')}
 ${softFragmentWGSL('baseColor')}
+${blendFragmentWGSL('baseColor')}
     fragmentOutputs.color = baseColor;
 }
 `;

package/src/shaders/particle_physics_frag.glsl.ts

@@ -1,4 +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';
 
@@ -86,6 +88,7 @@ uniform float alphaTest;
 #endif
 
 ${fogFragmentDeclarationGLSL}
+${imageProcessingDeclarationGLSL}
 ${softFragmentDeclarationGLSL}
 ${surfaceFragmentDeclarationGLSL}
 void main() {
@@ -130,7 +133,9 @@ ${surfaceColorGLSL(true)}
 #endif
 
 ${fogFragmentGLSL('color')}
-    gl_FragColor = vec4(color, baseColor.a);
-${softFragmentGLSL('gl_FragColor')}
+    vec4 finalColor = vec4(color, baseColor.a);
+${softFragmentGLSL('finalColor')}
+${blendFragmentGLSL('finalColor')}
+    gl_FragColor = finalColor;
 }
 `;

package/src/shaders/particle_physics_frag.wgsl.ts

@@ -1,4 +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';
 
@@ -85,6 +87,7 @@ uniform alphaTest: f32;
 #endif
 
 ${fogFragmentDeclarationWGSL}
+${imageProcessingDeclarationWGSL}
 ${softFragmentDeclarationWGSL}
 ${surfaceFragmentDeclarationWGSL}
 @fragment
@@ -133,6 +136,7 @@ ${surfaceColorWGSL(true)}
 
 ${fogFragmentWGSL('finalColor')}
 ${softFragmentWGSL('finalColor')}
+${blendFragmentWGSL('finalColor')}
     fragmentOutputs.color = finalColor;
 }
 `;

package/src/shaders/trail_frag.glsl.ts

@@ -1,4 +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';
 
@@ -18,6 +20,7 @@ uniform float alphaTest;
 #endif
 
 ${fogFragmentDeclarationGLSL}
+${imageProcessingDeclarationGLSL}
 ${softFragmentDeclarationGLSL}
 ${surfaceFragmentDeclarationGLSL}
 void main() {
@@ -29,6 +32,8 @@ ${surfaceColorGLSL(false)}
 #endif
 
 ${fogFragmentGLSL('baseColor.rgb')}
+${softFragmentGLSL('baseColor')}
+${blendFragmentGLSL('baseColor')}
     gl_FragColor = baseColor;
-${softFragmentGLSL('gl_FragColor')}}
+}
 `;

package/src/shaders/trail_frag.wgsl.ts

@@ -1,4 +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';
 
@@ -19,6 +21,7 @@ uniform alphaTest: f32;
 #endif
 
 ${fogFragmentDeclarationWGSL}
+${imageProcessingDeclarationWGSL}
 ${softFragmentDeclarationWGSL}
 ${surfaceFragmentDeclarationWGSL}
 @fragment
@@ -32,6 +35,7 @@ ${surfaceColorWGSL(false)}
 
 ${fogFragmentWGSL('baseColor')}
 ${softFragmentWGSL('baseColor')}
+${blendFragmentWGSL('baseColor')}
     fragmentOutputs.color = baseColor;
 }
 `;

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++) {
@@ -167,10 +177,8 @@ export class EmissionController {
                 if (emissionState.burstWaves !== undefined) {
                     emissionState.burstWaves.length = 0;
                 }
-                const behaviors = system.behaviors;
-                for (let i = 0; i < behaviors.length; i++) {
-                    behaviors[i].reset();
-                }
+                // Behaviors carry on across the loop (a noise field keeps scrolling, sub emissions
+                // of live particles keep going); they reset only when the system restarts.
             } else {
                 if (!system.isEmitEnded && !system.onlyUsedByOther) {
                     system.endEmit();
@@ -178,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/EventDispatcher.ts

@@ -2,26 +2,41 @@ import type {ParticleSystemEvent, ParticleSystemEventType} from 'quarks.core';
 
 type Listener = (event: ParticleSystemEvent) => void;
 
-/** The callbacks registered on a {@link ParticleSystem}, by event type. */
+/**
+ * The callbacks registered on a {@link ParticleSystem}, by event type.
+ *
+ * The lists are copied on write, not on fire: adding or removing a callback while an event is
+ * being fired (a listener removing itself, say) changes the next firing and never the one in
+ * progress, so every callback registered when the event fired is called once.
+ */
 export class EventDispatcher {
-    private readonly listeners: {[event: string]: Listener[]} = {};
+    private readonly listeners: {[event: string]: readonly Listener[]} = {};
 
     /** Registers `callback` for `event`. */
     add(event: ParticleSystemEventType, callback: Listener): void {
-        if (!this.listeners[event]) this.listeners[event] = [];
-        this.listeners[event].push(callback);
+        this.listeners[event] = [...(this.listeners[event] ?? []), callback];
     }
 
-    /** Drops every callback for `event`. */
-    removeAll(event: ParticleSystemEventType): void {
-        if (this.listeners[event]) this.listeners[event] = [];
+    /** Drops every callback for `event`, or for every event when it is left out. */
+    removeAll(event?: ParticleSystemEventType): void {
+        if (event === undefined) {
+            for (const key of Object.keys(this.listeners)) {
+                delete this.listeners[key];
+            }
+            return;
+        }
+        delete this.listeners[event];
     }
 
     /** Drops one callback for `event`. */
     remove(event: ParticleSystemEventType, callback: Listener): void {
-        if (this.listeners[event]) {
-            const index = this.listeners[event].indexOf(callback);
-            if (index !== -1) this.listeners[event].splice(index, 1);
+        const callbacks = this.listeners[event];
+        if (callbacks === undefined) {
+            return;
+        }
+        const index = callbacks.indexOf(callback);
+        if (index !== -1) {
+            this.listeners[event] = callbacks.filter((_, i) => i !== index);
         }
     }
 
@@ -33,6 +48,7 @@ export class EventDispatcher {
 
     /** Calls the callbacks registered for the event's type, in the order they were added. */
     fire(event: ParticleSystemEvent): void {
+        // The list as it is now: a callback added or removed by a listener does not shift it.
         const callbacks = this.listeners[event.type];
         if (callbacks === undefined) {
             return;

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);
                 }