babylon.quarks 0.27.0 → 0.28.0

package/src/shaderProgram.ts

@@ -1,5 +1,6 @@
 import {Constants} from '@babylonjs/core/Engines/constants';
 import {hasSizeLimits, takesPivotAndSizeLimits, tilesSheet} from './batchKey';
+import {readsUV1, RenderMode, StoredBatchSettings} from './batchSettings';
 import local_particle_physics_vert from './shaders/local_particle_physics_vert.glsl';
 import local_particle_physics_vert_wgsl from './shaders/local_particle_physics_vert.wgsl';
 import particle_frag from './shaders/particle_frag.glsl';
@@ -15,7 +16,6 @@ import trail_frag from './shaders/trail_frag.glsl';
 import trail_frag_wgsl from './shaders/trail_frag.wgsl';
 import trail_vert from './shaders/trail_vert.glsl';
 import trail_vert_wgsl from './shaders/trail_vert.wgsl';
-import {readsUV1, RenderMode, StoredBatchSettings} from './VFXBatch';
 
 /**
  * The part of a batch's settings that decides its shader: the render mode, which textures and
@@ -111,12 +111,94 @@ export function samplesMap(settings: {renderMode: RenderMode; texture: unknown})
     return settings.texture !== null || settings.renderMode === RenderMode.Mesh;
 }
 
-/** Whether the blend mode adds to the frame, in which case fog and fade darken instead of mixing. */
-export function blendsAdditively(settings: {materialTransparent: boolean; materialBlendMode: number}): boolean {
-    return (
-        settings.materialTransparent &&
-        (settings.materialBlendMode === Constants.ALPHA_ADD || settings.materialBlendMode === Constants.ALPHA_ONEONE)
-    );
+/**
+ * How a particle's colour has to leave the fragment shader for its blend mode, so that its alpha
+ * means coverage: alpha 0 leaves the frame as it was, alpha 1 draws the colour in full, and the
+ * fades (soft particles, erosion, a rim fade, alpha over life) only lower alpha. Unity's particle
+ * shaders do the same for their Alpha, Premultiply, Additive and Multiply modes. Alpha has no
+ * such meaning for an opaque material, nor under `ALPHA_INTERPOLATE` (constant blend colour),
+ * `ALPHA_REPLACE_COLOR` (replaces the frame) and `ALPHA_DUAL_SRC0_ADD_SRC1xDST` (reads a second
+ * shader output the particle shaders do not write); these leave the colour as it is.
+ *
+ * - `'straight'`: the blend weighs the colour by its alpha itself (Babylon's `ALPHA_COMBINE`,
+ *   `ALPHA_ADD`, `ALPHA_LAYER_ACCUMULATE`, …) or does not blend; the colour leaves as it is.
+ * - `'premultiply'`: the blend takes the colour at full weight, or the frame by one minus the
+ *   colour (`ALPHA_PREMULTIPLIED`, `ALPHA_ONEONE`, `ALPHA_SCREENMODE`, `ALPHA_SUBTRACT`,
+ *   `ALPHA_MAXIMIZED`, `ALPHA_MAX`, …), so the shader multiplies it by its alpha: black, which
+ *   these modes leave the frame alone with, at alpha 0. Textures stay straight alpha, as in
+ *   Unity's Premultiply mode. The fade is linear in alpha except under `ALPHA_MAXIMIZED`, whose
+ *   blend weighs the colour by alpha once more, and `ALPHA_MAX`.
+ * - `'multiply'`: the blend multiplies the frame by the colour (`ALPHA_MULTIPLY`, `ALPHA_MIN`), so
+ *   the shader moves it toward white, which leaves the frame alone, as alpha falls. `ALPHA_MIN`
+ *   clamps a frame brighter than 1 (an HDR target) to 1 where a particle draws, even at alpha 0.
+ */
+export type BlendOutput = 'straight' | 'premultiply' | 'multiply';
+
+/**
+ * What the scene's fog turns a particle's colour into with distance: the fog colour where the
+ * particle covers the frame (`'color'`), black where it adds to it (`'black'`, or the fog would
+ * add itself to the whole screen), white where it multiplies it (`'white'`). Unity fogs its
+ * additive and multiply particles toward black and white for the same reason.
+ */
+export type FogTarget = 'color' | 'black' | 'white';
+
+/** The {@link BlendOutput} and {@link FogTarget} of a blend mode. */
+export interface BlendCategory {
+    /** How the colour leaves the shader. */
+    output: BlendOutput;
+    /** Where the fog takes the colour. */
+    fogTarget: FogTarget;
+}
+
+const PREMULTIPLY_MODES = new Set<number>([
+    Constants.ALPHA_SUBTRACT,
+    Constants.ALPHA_MAXIMIZED,
+    Constants.ALPHA_ONEONE,
+    Constants.ALPHA_PREMULTIPLIED,
+    Constants.ALPHA_PREMULTIPLIED_PORTERDUFF,
+    Constants.ALPHA_SCREENMODE,
+    Constants.ALPHA_ONEONE_ONEONE,
+    Constants.ALPHA_ALPHATOCOLOR,
+    Constants.ALPHA_REVERSEONEMINUS,
+    Constants.ALPHA_SRC_DSTONEMINUSSRCALPHA,
+    Constants.ALPHA_ONEONE_ONEZERO,
+    Constants.ALPHA_EXCLUSION,
+    Constants.ALPHA_MAX,
+]);
+const MULTIPLY_MODES = new Set<number>([Constants.ALPHA_MULTIPLY, Constants.ALPHA_MIN]);
+/** The modes whose fog is the fog colour: those that lay the colour over the frame or replace it. */
+const OVER_MODES = new Set<number>([
+    Constants.ALPHA_COMBINE,
+    Constants.ALPHA_PREMULTIPLIED,
+    Constants.ALPHA_PREMULTIPLIED_PORTERDUFF,
+    Constants.ALPHA_INTERPOLATE,
+    Constants.ALPHA_SRC_DSTONEMINUSSRCALPHA,
+    Constants.ALPHA_LAYER_ACCUMULATE,
+    Constants.ALPHA_REPLACE_COLOR,
+]);
+
+/**
+ * The {@link BlendCategory} of a material: an opaque one (`materialTransparent` false, or
+ * `ALPHA_DISABLE`) is straight and fogs toward the fog colour; a transparent one by its Babylon
+ * alpha mode. A mode this table does not know is straight and fogs toward the fog colour.
+ */
+export function blendCategory(settings: {materialTransparent: boolean; materialBlendMode: number}): BlendCategory {
+    const mode = settings.materialBlendMode;
+    if (!settings.materialTransparent || mode === Constants.ALPHA_DISABLE) {
+        return {output: 'straight', fogTarget: 'color'};
+    }
+    const output: BlendOutput = PREMULTIPLY_MODES.has(mode)
+        ? 'premultiply'
+        : MULTIPLY_MODES.has(mode)
+          ? 'multiply'
+          : 'straight';
+    const fogTarget: FogTarget =
+        output === 'multiply'
+            ? 'white'
+            : OVER_MODES.has(mode) || (output === 'straight' && mode !== Constants.ALPHA_ADD)
+              ? 'color'
+              : 'black';
+    return {output, fogTarget};
 }
 
 /** The shader program a batch with `settings` compiles, given what it knows about its textures. */
@@ -146,7 +228,7 @@ function spriteShaderProgram(settings: ShaderSettings, context: ShaderContext):
         fragment = {glsl: particle_frag, wgsl: particle_frag_wgsl};
     }
 
-    const defines = fogDefines(settings);
+    const defines = blendDefines(settings);
     const attributes = [...SPRITE_ATTRIBUTES];
     const uniforms = ['world', 'view', 'projection', ...FOG_UNIFORMS];
     const samplers: string[] = [];
@@ -225,7 +307,7 @@ function spriteShaderProgram(settings: ShaderSettings, context: ShaderContext):
 
 /** The program of a trail batch. */
 function trailShaderProgram(settings: ShaderSettings, context: ShaderContext): ShaderProgram {
-    const defines = fogDefines(settings);
+    const defines = blendDefines(settings);
     const attributes = [...TRAIL_ATTRIBUTES];
     const uniforms = ['view', 'projection', ...FOG_UNIFORMS];
     const samplers: string[] = [];
@@ -251,15 +333,27 @@ function trailShaderProgram(settings: ShaderSettings, context: ShaderContext): S
 }
 
 /**
- * The fog defines: `FOG` when the settings apply the scene's fog, and `FOG_ADDITIVE` when the
- * particles add to the frame, so that they fade toward black instead of the fog colour, which
- * would fog the whole screen (what Unity does for additive materials).
+ * The blend defines: `BLEND_PREMULTIPLY` or `BLEND_MULTIPLY` for how the colour leaves the shader,
+ * and with `FOG` (when the settings apply the scene's fog) `FOG_ADDITIVE` or `FOG_MULTIPLY` for a
+ * fog toward black or white. See {@link blendCategory}.
  */
-function fogDefines(settings: ShaderSettings): string[] {
-    if (!settings.applyFog) {
-        return [];
+function blendDefines(settings: ShaderSettings): string[] {
+    const {output, fogTarget} = blendCategory(settings);
+    const defines: string[] = [];
+    if (output === 'premultiply') {
+        defines.push('BLEND_PREMULTIPLY');
+    } else if (output === 'multiply') {
+        defines.push('BLEND_MULTIPLY');
+    }
+    if (settings.applyFog) {
+        defines.push('FOG');
+        if (fogTarget === 'black') {
+            defines.push('FOG_ADDITIVE');
+        } else if (fogTarget === 'white') {
+            defines.push('FOG_MULTIPLY');
+        }
     }
-    return blendsAdditively(settings) ? ['FOG', 'FOG_ADDITIVE'] : ['FOG'];
+    return defines;
 }
 
 /** Soft particles, when on and a depth texture is there to read, and the alpha test. */

package/src/shaderVariants.ts

@@ -123,6 +123,21 @@ const FOG: Axis[] = [
     {name: 'fog additive', settings: {applyFog: true, materialBlendMode: Constants.ALPHA_ADD}},
 ];
 
+/** The blend resolves (see `blendCategory`), with and without the fog each one takes. */
+const BLEND: Axis[] = [
+    {name: 'premultiplied', settings: {materialBlendMode: Constants.ALPHA_PREMULTIPLIED}},
+    {name: 'premultiplied fog', settings: {materialBlendMode: Constants.ALPHA_PREMULTIPLIED, applyFog: true}},
+    {name: 'one-one', settings: {materialBlendMode: Constants.ALPHA_ONEONE}},
+    {name: 'one-one fog', settings: {materialBlendMode: Constants.ALPHA_ONEONE, applyFog: true}},
+    {name: 'multiply', settings: {materialBlendMode: Constants.ALPHA_MULTIPLY}},
+    {name: 'multiply fog', settings: {materialBlendMode: Constants.ALPHA_MULTIPLY, applyFog: true}},
+    {
+        name: 'multiply fog alpha test',
+        settings: {materialBlendMode: Constants.ALPHA_MULTIPLY, applyFog: true, materialAlphaTest: 0.5},
+    },
+    {name: 'opaque', settings: {materialTransparent: false}},
+];
+
 /** Texture effects (`chunks/surface.ts`), alone and together, on both UV channels. */
 const SURFACE: Axis[] = (() => {
     const uv0 = normalizeMapUV({tiling: [2, 2]});
@@ -174,15 +189,16 @@ const MESH_UV2: Axis = {name: 'uv2', context: {meshUV2: true}};
 
 /** Soft, alpha-tested and fogged at once, to try the effects with the rest of the fragment. */
 const EVERYTHING_ELSE: Axis = {
-    name: 'soft packed alpha test fog additive',
-    settings: {softParticles: true, materialAlphaTest: 0.5, applyFog: true, materialBlendMode: Constants.ALPHA_ADD},
+    name: 'soft packed alpha test fog one-one',
+    settings: {softParticles: true, materialAlphaTest: 0.5, applyFog: true, materialBlendMode: Constants.ALPHA_ONEONE},
     context: {depth: {packed: true}},
 };
 
 /**
  * Every shader program the library can compile, one per distinct set of defines: every render
- * mode with every combination of sheet, map, soft particles, alpha test and fog, and the texture
- * effects alone and together on each shader family. What a shader validator compiles, and what
+ * mode with every combination of sheet, map, soft particles, alpha test and fog, every blend
+ * resolve with and without fog and soft particles, and the texture effects alone and together on
+ * each shader family. What a shader validator compiles, and what
  * an application can warm the shader cache with before its first frame (Unity's
  * ShaderVariantCollection). Built by {@link shaderProgram}, so a variant here is a material a
  * batch would build.
@@ -215,6 +231,10 @@ export function shaderVariants(): ShaderVariant[] {
                         for (const alphaTest of ALPHA_TEST)
                             for (const fog of FOG) add([target, quad, tile, map, soft, alphaTest, fog]);
 
+    for (const target of TARGETS)
+        for (const blend of BLEND)
+            for (const soft of SOFT.slice(0, 2)) for (const map of MAP) add([target, blend, soft, map]);
+
     for (const target of TARGETS.filter((t) => SURFACE_TARGETS.includes(t.name)))
         for (const uv2 of target.settings?.renderMode === RenderMode.Mesh ? [NONE, MESH_UV2] : [NONE])
             for (const surface of SURFACE)

package/src/shaders/chunks/blend.ts

@@ -0,0 +1,31 @@
+/**
+ * The blend resolve for the particle shaders, in both shader languages.
+ *
+ * Every fade in the shaders (soft particles, erosion, a rim fade, alpha over life) lowers alpha
+ * only, so that alpha means coverage. Blend modes that take the colour at full weight
+ * (`BLEND_PREMULTIPLY`: one-one, premultiplied, screen, subtract, …) would ignore it, so the
+ * resolve multiplies the colour by its alpha; modes that multiply the frame (`BLEND_MULTIPLY`)
+ * move it toward white instead. It runs last, after fog and the soft fade. See `blendCategory`.
+ */
+
+/** Resolves the vec4 lvalue `color` for the blend mode, GLSL. */
+export function blendFragmentGLSL(color: string): string {
+    return /* glsl */ `
+#if defined(BLEND_PREMULTIPLY)
+    ${color}.rgb *= ${color}.a;
+#elif defined(BLEND_MULTIPLY)
+    ${color}.rgb = mix(vec3(1.0), ${color}.rgb, ${color}.a);
+#endif
+`;
+}
+
+/** Resolves the `var` vec4 `color` for the blend mode, WGSL. */
+export function blendFragmentWGSL(color: string): string {
+    return /* wgsl */ `
+#if defined(BLEND_PREMULTIPLY)
+    ${color} = vec4f(${color}.rgb * ${color}.a, ${color}.a);
+#elif defined(BLEND_MULTIPLY)
+    ${color} = vec4f(mix(vec3f(1.0), ${color}.rgb, ${color}.a), ${color}.a);
+#endif
+`;
+}

package/src/shaders/chunks/fog.ts

@@ -11,7 +11,8 @@
  *
  * Additive particles cannot fade toward a fog colour (that would add fog to
  * the whole screen), so under `FOG_ADDITIVE` they fade toward black instead,
- * which is what Unity does for additive materials.
+ * and multiplying particles (`FOG_MULTIPLY`) toward white, which leaves the
+ * frame as it is: what Unity does for additive and multiply materials.
  */
 
 /** Vertex-side declaration, GLSL. */
@@ -62,8 +63,10 @@ export function fogFragmentGLSL(rgb: string): string {
 #ifdef FOG
     {
         float fogFactor = quarksFogFactor();
-#ifdef FOG_ADDITIVE
+#if defined(FOG_ADDITIVE)
         ${rgb} *= fogFactor;
+#elif defined(FOG_MULTIPLY)
+        ${rgb} = mix(vec3(1.0), ${rgb}, fogFactor);
 #else
         ${rgb} = mix(vFogColor, ${rgb}, fogFactor);
 #endif
@@ -110,8 +113,10 @@ fn quarksFog(rgb: vec3f, fogDistanceVector: vec3f) -> vec3f {
         fogCoeff = exp(-fogDistance * fogDistance * fogDensity * fogDensity);
     }
     let fogFactor = clamp(fogCoeff, 0.0, 1.0);
-#ifdef FOG_ADDITIVE
+#if defined(FOG_ADDITIVE)
     return rgb * fogFactor;
+#elif defined(FOG_MULTIPLY)
+    return mix(vec3f(1.0), rgb, fogFactor);
 #else
     return mix(uniforms.vFogColor, rgb, fogFactor);
 #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,3 +1,4 @@
+import {blendFragmentGLSL} from './chunks/blend';
 import {fogFragmentDeclarationGLSL, fogFragmentGLSL} from './chunks/fog';
 import {softFragmentDeclarationGLSL, softFragmentGLSL} from './chunks/soft';
 import {surfaceColorGLSL, surfaceFragmentDeclarationGLSL} from './chunks/surface';
@@ -35,7 +36,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,3 +1,4 @@
+import {blendFragmentWGSL} from './chunks/blend';
 import {fogFragmentDeclarationWGSL, fogFragmentWGSL} from './chunks/fog';
 import {softFragmentDeclarationWGSL, softFragmentWGSL} from './chunks/soft';
 import {surfaceColorWGSL, surfaceFragmentDeclarationWGSL} from './chunks/surface';
@@ -38,6 +39,7 @@ ${surfaceColorWGSL(true)}
 
 ${fogFragmentWGSL('baseColor')}
 ${softFragmentWGSL('baseColor')}
+${blendFragmentWGSL('baseColor')}
     fragmentOutputs.color = baseColor;
 }
 `;

package/src/shaders/particle_physics_frag.glsl.ts

@@ -1,3 +1,4 @@
+import {blendFragmentGLSL} from './chunks/blend';
 import {fogFragmentDeclarationGLSL, fogFragmentGLSL} from './chunks/fog';
 import {softFragmentDeclarationGLSL, softFragmentGLSL} from './chunks/soft';
 import {surfaceColorGLSL, surfaceFragmentDeclarationGLSL} from './chunks/surface';
@@ -130,7 +131,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,3 +1,4 @@
+import {blendFragmentWGSL} from './chunks/blend';
 import {fogFragmentDeclarationWGSL, fogFragmentWGSL} from './chunks/fog';
 import {softFragmentDeclarationWGSL, softFragmentWGSL} from './chunks/soft';
 import {surfaceColorWGSL, surfaceFragmentDeclarationWGSL} from './chunks/surface';
@@ -133,6 +134,7 @@ ${surfaceColorWGSL(true)}
 
 ${fogFragmentWGSL('finalColor')}
 ${softFragmentWGSL('finalColor')}
+${blendFragmentWGSL('finalColor')}
     fragmentOutputs.color = finalColor;
 }
 `;

package/src/shaders/trail_frag.glsl.ts

@@ -1,3 +1,4 @@
+import {blendFragmentGLSL} from './chunks/blend';
 import {fogFragmentDeclarationGLSL, fogFragmentGLSL} from './chunks/fog';
 import {softFragmentDeclarationGLSL, softFragmentGLSL} from './chunks/soft';
 import {surfaceColorGLSL, surfaceFragmentDeclarationGLSL} from './chunks/surface';
@@ -29,6 +30,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,3 +1,4 @@
+import {blendFragmentWGSL} from './chunks/blend';
 import {fogFragmentDeclarationWGSL, fogFragmentWGSL} from './chunks/fog';
 import {softFragmentDeclarationWGSL, softFragmentWGSL} from './chunks/soft';
 import {surfaceColorWGSL, surfaceFragmentDeclarationWGSL} from './chunks/surface';
@@ -32,6 +33,7 @@ ${surfaceColorWGSL(false)}
 
 ${fogFragmentWGSL('baseColor')}
 ${softFragmentWGSL('baseColor')}
+${blendFragmentWGSL('baseColor')}
     fragmentOutputs.color = baseColor;
 }
 `;

package/src/system/EmissionController.ts

@@ -167,10 +167,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();

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/geometry.ts

@@ -1,3 +1,4 @@
+import type {BufferGeometryDataJSON, GeometryArrays, GeometryEntry} from '../effectDocumentJSON';
 import {ensureTriangleIndices} from '../geometryUtil';
 
 /** Positions of the unit quad billboards are drawn with, and the default mesh. */
@@ -47,19 +48,19 @@ export function isFallbackNormals(normals: Float32Array | undefined, positions:
     return normals !== undefined && normals === fallbackNormals.get(positions);
 }
 
+/** `values` as a Float32Array: itself when it is one, else a copy. */
+function floats(values: number[] | Float32Array | undefined): Float32Array | undefined {
+    return values ? (values instanceof Float32Array ? values : new Float32Array(values)) : undefined;
+}
+
 /**
  * Typed arrays from a geometry entry of an effect document: quarks' own `{positions, indices, uvs,
- * uvs2, normals}`, or a three.js `BufferGeometry` JSON. Anything else gives the default quad.
+ * uvs2, normals}`, or a three.js `BufferGeometry` JSON or its `data`. Anything else gives the
+ * default quad.
  */
-export function resolveGeometryData(entry: any): {
-    positions: Float32Array;
-    indices: Uint32Array | Uint16Array;
-    uvs?: Float32Array;
-    uvs2?: Float32Array;
-    normals?: Float32Array;
-} {
-    if (entry?.positions) {
-        const positions = entry.positions instanceof Float32Array ? entry.positions : new Float32Array(entry.positions);
+export function resolveGeometryData(entry: GeometryEntry | BufferGeometryDataJSON | undefined): GeometryArrays {
+    if (entry && 'positions' in entry && entry.positions) {
+        const positions = floats(entry.positions)!;
         const rawIndices =
             entry.indices instanceof Uint16Array || entry.indices instanceof Uint32Array
                 ? entry.indices
@@ -69,23 +70,17 @@ export function resolveGeometryData(entry: any): {
         return {
             positions,
             indices: ensureTriangleIndices(positions, rawIndices),
-            uvs: entry.uvs ? (entry.uvs instanceof Float32Array ? entry.uvs : new Float32Array(entry.uvs)) : undefined,
-            uvs2: entry.uvs2
-                ? entry.uvs2 instanceof Float32Array
-                    ? entry.uvs2
-                    : new Float32Array(entry.uvs2)
-                : undefined,
-            normals: entry.normals
-                ? entry.normals instanceof Float32Array
-                    ? entry.normals
-                    : new Float32Array(entry.normals)
-                : undefined,
+            uvs: floats(entry.uvs),
+            uvs2: floats(entry.uvs2),
+            normals: floats(entry.normals),
         };
     }
 
-    const data = entry?.data ?? entry;
-    if (data?.attributes?.position?.array) {
-        const positions = new Float32Array(data.attributes.position.array);
+    const data = entry && 'data' in entry ? entry.data : entry;
+    const attributes = data && 'attributes' in data ? data.attributes : undefined;
+    const position = attributes?.position?.array;
+    if (data && 'attributes' in data && attributes && position) {
+        const positions = new Float32Array(position);
         let indices: Uint32Array | Uint16Array | undefined;
         if (data.index?.array) {
             const indexType = data.index.type === 'Uint16Array' ? Uint16Array : Uint32Array;
@@ -94,12 +89,10 @@ export function resolveGeometryData(entry: any): {
         return {
             positions,
             indices: ensureTriangleIndices(positions, indices),
-            uvs: data.attributes.uv?.array ? new Float32Array(data.attributes.uv.array) : undefined,
+            uvs: floats(attributes.uv?.array),
             // three.js names the second set `uv1` (r151 on), `uv2` before.
-            uvs2: (data.attributes.uv1 ?? data.attributes.uv2)?.array
-                ? new Float32Array((data.attributes.uv1 ?? data.attributes.uv2).array)
-                : undefined,
-            normals: data.attributes.normal?.array ? new Float32Array(data.attributes.normal.array) : undefined,
+            uvs2: floats((attributes.uv1 ?? attributes.uv2)?.array),
+            normals: floats(attributes.normal?.array),
         };
     }