babylon.quarks 0.24.1 → 0.26.0

package/src/ParticleSystem.ts

@@ -53,7 +53,25 @@ import {BatchedRenderer, VFXBatchSettings} from './BatchedRenderer';
 import {ensureEnvAtlasFromCube, getCachedEnvAtlas} from './envAtlas';
 import {ensureTriangleIndices} from './geometryUtil';
 import {ParticleEmitter} from './ParticleEmitter';
-import {MeshLighting, MeshRim, normalizeMeshRim, RenderMode, SortMode} from './VFXBatch';
+import {
+    MeshLighting,
+    MeshRim,
+    normalizeErosion,
+    normalizeGradientMap,
+    normalizeMapUV,
+    normalizeMeshRim,
+    normalizeUVDistortion,
+    ParticleErosion,
+    ParticleErosionOptions,
+    ParticleGradientMap,
+    ParticleUVDistortion,
+    ParticleUVDistortionOptions,
+    RenderMode,
+    SortMode,
+    TextureUV,
+    textureUVToJSON,
+    UV_DISTORTION_DEFAULT_UV,
+} from './VFXBatch';
 
 export interface BurstParameters {
     time: number;
@@ -81,6 +99,27 @@ export interface BurstParameters {
  */
 export type CullingMode = 'always' | 'pause' | 'pauseAndCatchUp';
 
+/**
+ * What the emitter's world scale does to a world-space system (Unity's
+ * Scaling Mode, as far as it differs here). A local-space system lives in its
+ * emitter's space, so its scale reaches everything either way.
+ *
+ * - `'shape'` (default): the scale sizes the emission shape and the
+ *   particles; speeds, forces and speed limits stay in world units, so a
+ *   scaled-down effect moves as far as the full-size one.
+ * - `'hierarchy'`: the scale also multiplies start speeds (per axis),
+ *   `ForceOverLife` and `LimitSpeedOverLife` (by the mean of the axes), so the
+ *   whole effect, motion included, scales like a model would.
+ */
+export type ScalingMode = 'shape' | 'hierarchy';
+
+/**
+ * Where a {@link RenderMode.Beam} system's quads end: a point in world space,
+ * or anything with a world position, such as a Babylon `TransformNode`, read
+ * every frame.
+ */
+export type BeamEnd = {x: number; y: number; z: number} | {getAbsolutePosition(): {x: number; y: number; z: number}};
+
 /** Particle backed by a {@link ParticleStore} row, as this system always creates. */
 type StoreBackedParticle = Particle & {storeIndex: number; setStoreIndex(index: number): void};
 
@@ -132,8 +171,19 @@ const DEFAULT_POSITIONS = new Float32Array([-0.5, -0.5, 0, 0.5, -0.5, 0, 0.5, 0.
 const DEFAULT_UVS = new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]);
 
 /** Zero UVs sized to a position buffer — missing/mismatched uv attrs → GL_INVALID_OPERATION on iOS. */
+const fallbackUVs = new WeakMap<Float32Array, Float32Array>();
+const fallbackNormals = new WeakMap<Float32Array, Float32Array>();
+/**
+ * Zero UVs for a geometry given without any, one array per geometry: batches
+ * are keyed by the UV array too, so systems sharing a geometry share it.
+ */
 function fallbackUVsForPositions(positions: Float32Array): Float32Array {
-    return new Float32Array((positions.length / 3) * 2);
+    let uvs = fallbackUVs.get(positions);
+    if (uvs === undefined || uvs.length !== (positions.length / 3) * 2) {
+        uvs = new Float32Array((positions.length / 3) * 2);
+        fallbackUVs.set(positions, uvs);
+    }
+    return uvs;
 }
 const DEFAULT_INDICES = new Uint32Array([0, 1, 2, 0, 2, 3]);
 
@@ -147,6 +197,24 @@ function trailFlags(settings: TrailSettings | undefined): Partial<TrailSettings>
     return flags;
 }
 
+/** A trail's side axis as JSON `[x, y, z]`, or nothing when unset. */
+function trailSideAxisJSON(settings: TrailSettings | undefined): {sideAxis?: number[]} {
+    const axis = settings?.sideAxis;
+    return axis ? {sideAxis: [axis.x, axis.y, axis.z]} : {};
+}
+
+/** A trail's side axis from JSON `[x, y, z]` (or an object with x, y, z), or nothing. */
+function trailSideAxisFromJSON(value: unknown): {sideAxis?: Vector3} {
+    if (Array.isArray(value)) {
+        return {sideAxis: new Vector3(Number(value[0]) || 0, Number(value[1]) || 0, Number(value[2]) || 0)};
+    }
+    if (value && typeof value === 'object') {
+        const v = value as {x?: number; y?: number; z?: number};
+        return {sideAxis: new Vector3(v.x ?? 0, v.y ?? 0, v.z ?? 0)};
+    }
+    return {};
+}
+
 export interface ParticleSystemParameters {
     autoDestroy?: boolean;
     looping?: boolean;
@@ -170,6 +238,12 @@ export interface ParticleSystemParameters {
     instancingGeometry?: Float32Array;
     instancingIndices?: Uint32Array | Uint16Array;
     instancingUVs?: Float32Array;
+    /**
+     * A second UV set for the mesh (glTF `TEXCOORD_1`, Unity's `uv2`), what
+     * textures on UV channel 1 read on a mesh particle; see `UVChannel`.
+     * Default none: channel 1 reads the first set.
+     */
+    instancingUVs2?: Float32Array;
     instancingNormals?: Float32Array;
     renderMode?: RenderMode;
     rendererEmitterSettings?: RendererEmitterSettings;
@@ -199,10 +273,20 @@ export interface ParticleSystemParameters {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles, see {@link ParticleSystem.rim}. Default none. */
     rim?: Partial<MeshRim>;
+    /** The main map's layout, see {@link ParticleSystem.mapUV}. Default as drawn. */
+    mapUV?: Partial<TextureUV>;
+    /** Colour ramp for the map, see {@link ParticleSystem.gradientMap}. Default none. */
+    gradientMap?: Partial<ParticleGradientMap>;
+    /** Alpha erosion, see {@link ParticleSystem.erosion}. Default none. */
+    erosion?: ParticleErosionOptions;
+    /** Map UV distortion, see {@link ParticleSystem.uvDistortion}. Default none. */
+    uvDistortion?: ParticleUVDistortionOptions;
     /** Multiplier on the time the system is advanced by, see {@link ParticleSystem.playbackSpeed}. Default 1. */
     playbackSpeed?: number;
     /** What the system does while off screen, see {@link CullingMode}. Default `'always'`. */
     cullingMode?: CullingMode;
+    /** What the emitter's scale does to a world-space system, see {@link ScalingMode}. Default `'shape'`. */
+    scalingMode?: ScalingMode;
     /** Seed for this system's own random generator, see {@link ParticleSystem.seed}. Default none. */
     seed?: number;
     /** Draw order within the batch, see {@link ParticleSystem.sortMode}. Default `'none'`. */
@@ -258,6 +342,8 @@ export interface ParticleSystemJSONParameters {
     playbackSpeed?: number;
     /** Written only when not `'always'`. */
     cullingMode?: CullingMode;
+    /** Written only when not `'shape'`. */
+    scalingMode?: ScalingMode;
     /** Written only when set. */
     seed?: number;
     /** Written only when not `'none'`. */
@@ -587,6 +673,99 @@ export class ParticleSystem implements IParticleSystem {
         this.neededToUpdateRender = true;
     }
 
+    /**
+     * How the main map is laid over the particle, see {@link TextureUV}: its
+     * UV channel, tiling and offset (Unity's Tiling / Offset) and a scroll on
+     * the renderer's clock (Unreal's Panner), for flowing energy, lava or a
+     * smear running along a mesh. A scrolled or tiled map should repeat. On a
+     * sprite sheet (UV channel 0) the layout applies to the sheet's UV, so a
+     * scroll or tiling there runs into the neighbouring cells. Undefined (the
+     * default), or the identity: the map as drawn. Fields left out take their
+     * defaults; assign a new object to change it. Saved with the material in
+     * the effect JSON.
+     */
+    get mapUV(): TextureUV | undefined {
+        return this.rendererSettings.mapUV;
+    }
+
+    set mapUV(uv: Partial<TextureUV> | undefined) {
+        this.rendererSettings.mapUV = normalizeMapUV(uv);
+        this.neededToUpdateRender = true;
+    }
+
+    /**
+     * Colour ramp the map is recoloured through (a gradient map), see
+     * {@link ParticleGradientMap}: a channel of the map, or its luminance,
+     * picks a colour along U of the ramp; the particle colour still tints the
+     * result. One greyscale or channel-packed texture then serves every
+     * palette. Undefined (the default), or without a ramp: none. Assign a new
+     * object to change it. Saved with the material in the effect JSON.
+     */
+    get gradientMap(): ParticleGradientMap | undefined {
+        return this.rendererSettings.gradientMap;
+    }
+
+    set gradientMap(gradientMap: Partial<ParticleGradientMap> | undefined) {
+        this.rendererSettings.gradientMap = normalizeGradientMap(gradientMap);
+        this.neededToUpdateRender = true;
+    }
+
+    /**
+     * Alpha erosion, see {@link ParticleErosion}: the particle's alpha decides
+     * how much of the shape is left rather than how transparent it is, so a
+     * `ColorOverLife` alpha curve dissolves the shape through a noise mask or
+     * wipes it through a gradient one — and an effect told to stop can fade
+     * out that way. Undefined (the default): alpha is plain transparency.
+     * Fields left out take their defaults; assign a new object to change it.
+     * Saved with the material in the effect JSON.
+     */
+    get erosion(): ParticleErosion | undefined {
+        return this.rendererSettings.erosion;
+    }
+
+    set erosion(erosion: ParticleErosionOptions | undefined) {
+        this.rendererSettings.erosion = normalizeErosion(erosion);
+        this.neededToUpdateRender = true;
+    }
+
+    /**
+     * Map UV distortion, see {@link ParticleUVDistortion}: a scrolling noise
+     * texture pushes the map's UV about, for heat shimmer and licking,
+     * breathing shapes. Undefined (the default), or without a map: none.
+     * Fields left out take their defaults; assign a new object to change it.
+     * Saved with the material in the effect JSON.
+     */
+    get uvDistortion(): ParticleUVDistortion | undefined {
+        return this.rendererSettings.uvDistortion;
+    }
+
+    set uvDistortion(distortion: ParticleUVDistortionOptions | undefined) {
+        this.rendererSettings.uvDistortion = normalizeUVDistortion(distortion);
+        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.
+     */
+    private readonly hierarchyScale = new Vector3(1, 1, 1);
+
+    /** The mean world scale of the emitter for a world-space `'hierarchy'` system, else 1. */
+    private measureMotionScale(): number {
+        if (this.scalingMode !== 'hierarchy' || !this.worldSpace) {
+            this.hierarchyScale.set(1, 1, 1);
+            return 1;
+        }
+        const e = this.emitter.matrixWorld.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;
+    }
+
     /** `lighting` if it is one of the modes, else the default. */
     private static validLighting(lighting: unknown): MeshLighting {
         return lighting === 'unlit' || lighting === 'scene' ? lighting : 'fixed';
@@ -630,10 +809,53 @@ export class ParticleSystem implements IParticleSystem {
         return this.rendererSettings.instancingGeometry;
     }
 
+    /**
+     * The mesh particles' positions. A new geometry with a different vertex
+     * count drops UV sets and normals that no longer fit it: the first UV set
+     * falls back to zeros, the second to none, the normals to +Z. Assign {@link instancingUVs} and
+     * {@link instancingUVs2} after it.
+     */
     set instancingGeometry(geometry: Float32Array) {
         this.restart();
         this.particles.length = 0;
-        this.rendererSettings.instancingGeometry = geometry;
+        const settings = this.rendererSettings;
+        const uvLength = (geometry.length / 3) * 2;
+        const previous = settings.instancingGeometry;
+        settings.instancingGeometry = geometry;
+        // Sets that no longer fit, or that were the old geometry's fallbacks, move to the new one's.
+        if (settings.instancingUVs?.length !== uvLength || settings.instancingUVs === fallbackUVs.get(previous)) {
+            settings.instancingUVs = fallbackUVsForPositions(geometry);
+        }
+        if (
+            settings.instancingNormals &&
+            (settings.instancingNormals.length !== geometry.length ||
+                settings.instancingNormals === fallbackNormals.get(previous))
+        ) {
+            settings.instancingNormals = ParticleSystem.createFallbackNormals(geometry);
+        }
+        if (settings.instancingUVs2 && settings.instancingUVs2.length !== uvLength) {
+            settings.instancingUVs2 = undefined;
+        }
+        this.neededToUpdateRender = true;
+    }
+
+    /** The mesh particles' first UV set, two values per vertex. */
+    get instancingUVs(): Float32Array {
+        return this.rendererSettings.instancingUVs ?? fallbackUVsForPositions(this.rendererSettings.instancingGeometry);
+    }
+
+    set instancingUVs(uvs: Float32Array) {
+        this.rendererSettings.instancingUVs = uvs;
+        this.neededToUpdateRender = true;
+    }
+
+    /** The mesh particles' second UV set, read by textures on UV channel 1; see `UVChannel`. */
+    get instancingUVs2(): Float32Array | undefined {
+        return this.rendererSettings.instancingUVs2;
+    }
+
+    set instancingUVs2(uvs: Float32Array | undefined) {
+        this.rendererSettings.instancingUVs2 = uvs;
         this.neededToUpdateRender = true;
     }
 
@@ -674,6 +896,7 @@ export class ParticleSystem implements IParticleSystem {
                 case RenderMode.BillBoard:
                 case RenderMode.VerticalBillBoard:
                 case RenderMode.HorizontalBillBoard:
+                case RenderMode.Beam:
                     this.rendererEmitterSettings = {};
                     break;
             }
@@ -730,9 +953,28 @@ export class ParticleSystem implements IParticleSystem {
      */
     playbackSpeed = 1;
 
+    /**
+     * Runtime multiplier on how many particles the system emits: bursts,
+     * emission over time and over distance alike. Unlike
+     * {@link setQualityFactor}, which only ever thins an effect, it may go
+     * above 1 to make a stronger version of the same effect. The two multiply.
+     * 1 by default; not saved in the effect JSON.
+     */
+    emissionMultiplier = 1;
+
     /** 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 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.
+     */
+    motionScale = 1;
+
     /**
      * Whether each particle starts turned along the direction its shape sends
      * it (Unity's Align To Direction): a mesh particle's +Z is pointed along
@@ -852,6 +1094,7 @@ export class ParticleSystem implements IParticleSystem {
             instancingUVs:
                 parameters.instancingUVs ??
                 (parameters.instancingGeometry ? fallbackUVsForPositions(parameters.instancingGeometry) : DEFAULT_UVS),
+            instancingUVs2: parameters.instancingUVs2,
             instancingNormals: parameters.instancingNormals,
             renderMode: parameters.renderMode ?? RenderMode.BillBoard,
             renderOrder: parameters.renderOrder ?? 0,
@@ -880,10 +1123,15 @@ export class ParticleSystem implements IParticleSystem {
             applyFog: parameters.applyFog ?? true,
             lighting: ParticleSystem.validLighting(parameters.lighting),
             rim: normalizeMeshRim(parameters.rim),
+            mapUV: normalizeMapUV(parameters.mapUV),
+            gradientMap: normalizeGradientMap(parameters.gradientMap),
+            erosion: normalizeErosion(parameters.erosion),
+            uvDistortion: normalizeUVDistortion(parameters.uvDistortion),
         };
         this.flip = ParticleSystem.nonZeroFlip(parameters.flip);
         this.playbackSpeed = parameters.playbackSpeed ?? 1;
         this.cullingMode = parameters.cullingMode ?? 'always';
+        this.scalingMode = parameters.scalingMode === 'hierarchy' ? 'hierarchy' : 'shape';
         this.alignToDirection = parameters.alignToDirection === true;
         this.seed = parameters.seed;
         if (this.rendererSettings.renderMode === RenderMode.Mesh && !this.rendererSettings.instancingNormals) {
@@ -1062,6 +1310,12 @@ export class ParticleSystem implements IParticleSystem {
         this.qualityFactor = Math.max(0.1, Math.min(1, qualityFactor));
     }
 
+    /** Quality factor times {@link emissionMultiplier}: what emission counts are scaled by. */
+    private emissionFactor(): number {
+        const multiplier = this.emissionMultiplier;
+        return multiplier >= 0 ? this.qualityFactor * multiplier : this.qualityFactor;
+    }
+
     /**
      * Appends one particle to the pool, giving it the next row of the store.
      *
@@ -1212,7 +1466,12 @@ export class ParticleSystem implements IParticleSystem {
                 particle.position.applyMatrix4(matrix);
                 particle.startSize.multiply(scale).abs();
                 particle.size.copy(particle.startSize);
-                particle.velocity.multiply(scale).applyMatrix3(this.normalMatrix);
+                if (this.scalingMode === 'hierarchy') {
+                    // Scaled per axis by the emitter's world scale, then turned: the speed scales with it.
+                    particle.velocity.multiply(this.hierarchyScale).applyQuaternion(tempQ);
+                } else {
+                    particle.velocity.multiply(scale).applyMatrix3(this.normalMatrix);
+                }
                 if (particle.rotation && particle.rotation instanceof Quaternion) {
                     particle.rotation.multiplyQuaternions(tempQ, particle.rotation);
                 }
@@ -1514,6 +1773,76 @@ export class ParticleSystem implements IParticleSystem {
      * frame behind the display.
      */
     getWorldBounds(min: Vector3, max: Vector3): boolean {
+        if (!this.measureWorldBounds(min, max)) {
+            return false;
+        }
+        if (this.rendererSettings.renderMode === RenderMode.Beam) {
+            // The quads reach the beam's end, which moves on its own. Without
+            // one a beam draws nothing beyond its particles.
+            const end = this.beamEndScratch;
+            if (!this.getBeamEnd(end)) {
+                return true;
+            }
+            const pad = this.boundsInWorld ? this.boundsPadding : this.boundsPadding * this.emitterMaxScale();
+            min.set(Math.min(min.x, end.x - pad), Math.min(min.y, end.y - pad), Math.min(min.z, end.z - pad));
+            max.set(Math.max(max.x, end.x + pad), Math.max(max.y, end.y + pad), Math.max(max.z, end.z + pad));
+        }
+        return true;
+    }
+
+    /**
+     * Where a {@link RenderMode.Beam} system's quads end, see {@link BeamEnd}.
+     * Unset (the default), a beam has no length and draws nothing. Not saved
+     * in the effect JSON: it is where this instance is aimed at runtime.
+     */
+    beamEnd?: BeamEnd;
+
+    /**
+     * Multiplies every particle's colour, alpha included, as it is drawn:
+     * a colour or a fade driven from code for this instance (Unity's custom
+     * 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.
+     * Not saved in the effect JSON; copied by {@link clone}.
+     */
+    tint?: Vector4;
+
+    private readonly beamEndScratch = new Vector3();
+
+    /** The world position of {@link beamEnd} into `out`; false when it is unset. */
+    getBeamEnd(out: Vector3): boolean {
+        const end = this.beamEnd;
+        if (end === undefined) {
+            return false;
+        }
+        const node = end as {getAbsolutePosition?: () => {x: number; y: number; z: number}};
+        if (typeof node.getAbsolutePosition === 'function') {
+            const position = node.getAbsolutePosition();
+            out.set(position.x, position.y, position.z);
+        } else {
+            // Any point: quarks' Vector3, or a Babylon one passed from plain JavaScript.
+            const point = end as {x: number; y: number; z: number};
+            out.set(point.x, point.y, point.z);
+        }
+        return true;
+    }
+
+    /** The largest axis of the emitter's world scale. */
+    private emitterMaxScale(): number {
+        const e = this.emitter.matrixWorld.elements;
+        return Math.sqrt(
+            Math.max(
+                e[0] * e[0] + e[1] * e[1] + e[2] * e[2],
+                e[4] * e[4] + e[5] * e[5] + e[6] * e[6],
+                e[8] * e[8] + e[9] * e[9] + e[10] * e[10]
+            )
+        );
+    }
+
+    private measureWorldBounds(min: Vector3, max: Vector3): boolean {
         if (!this.boundsValid) {
             return false;
         }
@@ -1689,6 +2018,7 @@ export class ParticleSystem implements IParticleSystem {
     }
 
     private stepOnce(delta: number): void {
+        this.motionScale = this.measureMotionScale();
         if (!this.onlyUsedByOther) {
             this.emit(delta, this.emissionState, this.emitter.matrixWorld);
         }
@@ -1936,6 +2266,10 @@ export class ParticleSystem implements IParticleSystem {
             // A world-space system records world positions already.
             const recordWorldSpace = trailSettings.recordWorldSpace && !this.worldSpace;
             const emitterMatrix = this.emitter.matrixWorld;
+            // A swept trail records its side as the emitter holds it, in the
+            // space its positions are recorded in.
+            const sideAxis = trailSettings.sideAxis;
+            const sidesInWorld = this.worldSpace || Boolean(trailSettings.recordWorldSpace);
             for (let i = 0; i < particleCount; i++) {
                 const trail = particles[i] as TrailParticle;
                 // Emptying the history lets the removal pass below take the
@@ -1955,6 +2289,25 @@ export class ParticleSystem implements IParticleSystem {
                     positions[offset + 1] = tempV.y;
                     positions[offset + 2] = tempV.z;
                 }
+                if (sideAxis && trail.age <= trail.life) {
+                    trail.ensureSideHistory();
+                    const offset = ((trail.historyHead + trail.historyCapacity - 1) % trail.historyCapacity) * 3;
+                    const sides = trail.historySides;
+                    let x = sideAxis.x;
+                    let y = sideAxis.y;
+                    let z = sideAxis.z;
+                    if (sidesInWorld) {
+                        const m = (trail.parentMatrix ?? emitterMatrix).elements;
+                        const tx = m[0] * x + m[4] * y + m[8] * z;
+                        const ty = m[1] * x + m[5] * y + m[9] * z;
+                        z = m[2] * x + m[6] * y + m[10] * z;
+                        x = tx;
+                        y = ty;
+                    }
+                    sides[offset] = x;
+                    sides[offset + 1] = y;
+                    sides[offset + 2] = z;
+                }
             }
         }
 
@@ -2060,8 +2413,9 @@ export class ParticleSystem implements IParticleSystem {
             return;
         }
         const rawCount = burst.count.genValue(this.memory, this.time);
-        const qualityFactor = this.qualityFactor;
-        const count = qualityFactor >= 0.999 ? rawCount : Math.floor(rawCount * qualityFactor);
+        const factor = this.emissionFactor();
+        // Rounded at random, so a fraction is not always lost: three at 1.5 is four or five, on average 4.5.
+        const count = Math.abs(factor - 1) < 0.001 ? rawCount : Math.floor(rawCount * factor + random());
         emissionState.isBursting = true;
         emissionState.burstParticleCount = count;
         this.spawn(count, emissionState, emitterMatrix);
@@ -2126,6 +2480,12 @@ export class ParticleSystem implements IParticleSystem {
     }
 
     emit(delta: number, emissionState: EmissionState, emitterMatrix: Matrix4) {
+        // Ended before this step (endEmit, or a past step's end of duration):
+        // no more bursts either. A looping system would otherwise keep firing
+        // them every loop after endEmit and never finish. Only the system's
+        // own emission: a sub emitter's bursts belong to its parent particles,
+        // which still go off as they die after the effect was told to end.
+        const endedBefore = this.emitEnded && emissionState === this.emissionState;
         if (emissionState.time > this.duration) {
             if (this.looping) {
                 emissionState.time -= this.duration;
@@ -2149,9 +2509,9 @@ export class ParticleSystem implements IParticleSystem {
             this.normalMatrix.getNormalMatrix(emitterMatrix);
         }
         const emissionBurstCount = this.emissionBursts.length;
-        const qualityFactor = this.qualityFactor;
+        const qualityFactor = this.emissionFactor();
 
-        if (emissionBurstCount > 0) {
+        if (emissionBurstCount > 0 && !endedBefore) {
             this.emitBursts(emissionState, emitterMatrix);
         }
 
@@ -2265,6 +2625,7 @@ export class ParticleSystem implements IParticleSystem {
             ...(this.applyFog ? {} : {applyFog: false}),
             ...(this.playbackSpeed !== 1 ? {playbackSpeed: this.playbackSpeed} : {}),
             ...(this.cullingMode !== 'always' ? {cullingMode: this.cullingMode} : {}),
+            ...(this.scalingMode !== 'shape' ? {scalingMode: this.scalingMode} : {}),
             ...(this.seedValue !== undefined ? {seed: this.seedValue} : {}),
             ...(this.sortMode !== 'none' ? {sortMode: this.sortMode} : {}),
             ...(this.alignToDirection ? {alignToDirection: true} : {}),
@@ -2309,6 +2670,7 @@ export class ParticleSystem implements IParticleSystem {
                         : new ConstantValue(30),
                 followLocalOrigin: trailSettings?.followLocalOrigin ?? false,
                 ...trailFlags(trailSettings),
+                ...trailSideAxisFromJSON((trailSettings as {sideAxis?: unknown} | undefined)?.sideAxis),
             };
         } else if (json.renderMode === RenderMode.StretchedBillBoard) {
             rendererEmitterSettings = {...(json.rendererEmitterSettings ?? {})};
@@ -2325,6 +2687,12 @@ export class ParticleSystem implements IParticleSystem {
             typeof materialTextureRef === 'string'
                 ? (meta.textures?.[materialTextureRef] ?? null)
                 : (materialTextureRef ?? null);
+        // Texture effects reference textures by uuid in a serialised meta, or hold them once a loader resolved them.
+        const resolveTexture = (ref: unknown): BaseTexture | null =>
+            typeof ref === 'string' ? (meta.textures?.[ref] ?? null) : ((ref as BaseTexture | null) ?? null);
+        const erosionMeta = materialMeta?.erosion;
+        const gradientMeta = materialMeta?.gradientMap;
+        const distortionMeta = materialMeta?.uvDistortion;
         const resolvedGeometryEntry =
             typeof json.instancingGeometry === 'string'
                 ? meta.geometries?.[json.instancingGeometry]
@@ -2364,6 +2732,7 @@ export class ParticleSystem implements IParticleSystem {
             instancingGeometry: resolvedGeometry.positions,
             instancingIndices: resolvedGeometry.indices,
             instancingUVs: resolvedGeometry.uvs,
+            instancingUVs2: resolvedGeometry.uvs2,
             instancingNormals: resolvedGeometry.normals,
             renderMode: json.renderMode,
             rendererEmitterSettings,
@@ -2372,6 +2741,7 @@ export class ParticleSystem implements IParticleSystem {
             applyFog: json.applyFog !== false,
             playbackSpeed: typeof json.playbackSpeed === 'number' ? json.playbackSpeed : undefined,
             cullingMode: ParticleSystem.validCullingMode(json.cullingMode),
+            scalingMode: json.scalingMode === 'hierarchy' ? 'hierarchy' : 'shape',
             seed: typeof json.seed === 'number' ? json.seed : undefined,
             sortMode: ParticleSystem.validSortMode(json.sortMode),
             alignToDirection: json.alignToDirection === true,
@@ -2401,6 +2771,19 @@ export class ParticleSystem implements IParticleSystem {
             flip: json.flip ? new Vector2(json.flip[0] ?? 0, json.flip[1] ?? 0) : undefined,
             lighting: materialMeta?.lighting,
             rim: materialMeta?.rim,
+            mapUV: materialMeta?.mapUV,
+            gradientMap:
+                gradientMeta && typeof gradientMeta === 'object'
+                    ? {...gradientMeta, ramp: resolveTexture(gradientMeta.ramp)}
+                    : undefined,
+            erosion:
+                erosionMeta && typeof erosionMeta === 'object'
+                    ? {...erosionMeta, mask: resolveTexture(erosionMeta.mask)}
+                    : undefined,
+            uvDistortion:
+                distortionMeta && typeof distortionMeta === 'object'
+                    ? {...distortionMeta, map: resolveTexture(distortionMeta.map)}
+                    : undefined,
         });
         ps.behaviors = (json.behaviors ?? [])
             .map((behaviorJson) => {
@@ -2419,12 +2802,15 @@ export class ParticleSystem implements IParticleSystem {
         return `${prefix}_${ParticleSystem.serializationCounter}`;
     }
 
+    /** Normals facing +Z, one array per geometry so systems sharing it still batch together. */
     private static createFallbackNormals(positions: Float32Array): Float32Array {
-        const normals = new Float32Array(positions.length);
-        for (let i = 0; i < normals.length; i += 3) {
-            normals[i] = 0;
-            normals[i + 1] = 0;
-            normals[i + 2] = 1;
+        let normals = fallbackNormals.get(positions);
+        if (!normals) {
+            normals = new Float32Array(positions.length);
+            for (let i = 2; i < normals.length; i += 3) {
+                normals[i] = 1;
+            }
+            fallbackNormals.set(positions, normals);
         }
         return normals;
     }
@@ -2435,6 +2821,7 @@ export class ParticleSystem implements IParticleSystem {
                 startLength: (this.rendererEmitterSettings as TrailSettings).startLength.toJSON(),
                 followLocalOrigin: (this.rendererEmitterSettings as TrailSettings).followLocalOrigin,
                 ...trailFlags(this.rendererEmitterSettings as TrailSettings),
+                ...(trailSideAxisJSON(this.rendererEmitterSettings as TrailSettings) as {sideAxis?: any}),
             };
         }
         if (this.renderMode === RenderMode.StretchedBillBoard) {
@@ -2454,6 +2841,7 @@ export class ParticleSystem implements IParticleSystem {
             positions: Array.from(this.rendererSettings.instancingGeometry),
             indices: Array.from(this.rendererSettings.instancingIndices),
             uvs: this.rendererSettings.instancingUVs ? Array.from(this.rendererSettings.instancingUVs) : undefined,
+            ...(this.rendererSettings.instancingUVs2 ? {uvs2: Array.from(this.rendererSettings.instancingUVs2)} : {}),
             normals: this.rendererSettings.instancingNormals
                 ? Array.from(this.rendererSettings.instancingNormals)
                 : undefined,
@@ -2476,6 +2864,19 @@ export class ParticleSystem implements IParticleSystem {
             meta.textures[reflectionAtlasUUID] = reflectionAtlas;
         }
 
+        const textureRef = (value: BaseTexture | null | undefined): string | undefined => {
+            if (!(value instanceof Texture)) {
+                return undefined;
+            }
+            const uuid = ParticleSystem.nextSerializationId('quarks_texture');
+            meta.textures[uuid] = value;
+            return uuid;
+        };
+        const erosion = this.erosion;
+        const distortion = this.uvDistortion;
+        const gradientMap = this.gradientMap;
+        const optional = <T>(key: string, value: T | undefined) => (value !== undefined ? {[key]: value} : {});
+
         const materialUUID = ParticleSystem.nextSerializationId('quarks_material');
         meta.materials[materialUUID] = {
             uuid: materialUUID,
@@ -2491,6 +2892,35 @@ export class ParticleSystem implements IParticleSystem {
             // Written only when not the default, so existing effects serialise as before.
             ...(this.lighting !== 'fixed' ? {lighting: this.lighting} : {}),
             ...(this.rim ? {rim: {...this.rim, color: [...this.rim.color]}} : {}),
+            ...optional('mapUV', this.mapUV ? textureUVToJSON(this.mapUV) : undefined),
+            ...(gradientMap
+                ? {
+                      gradientMap: {
+                          ramp: textureRef(gradientMap.ramp),
+                          ...(gradientMap.channel !== 'r' ? {channel: gradientMap.channel} : {}),
+                      },
+                  }
+                : {}),
+            ...(erosion
+                ? {
+                      erosion: {
+                          mask: textureRef(erosion.mask),
+                          ...optional('maskUV', textureUVToJSON(erosion.maskUV)),
+                          softness: erosion.softness,
+                          edgeWidth: erosion.edgeWidth,
+                          edgeColor: [...erosion.edgeColor],
+                      },
+                  }
+                : {}),
+            ...(distortion
+                ? {
+                      uvDistortion: {
+                          map: textureRef(distortion.map),
+                          ...optional('mapUV', textureUVToJSON(distortion.mapUV, UV_DISTORTION_DEFAULT_UV)),
+                          strength: distortion.strength,
+                      },
+                  }
+                : {}),
             sourceMaterial: this.materialRef ?? undefined,
         };
         return materialUUID;
@@ -2500,6 +2930,7 @@ export class ParticleSystem implements IParticleSystem {
         positions: Float32Array;
         indices: Uint32Array | Uint16Array;
         uvs?: Float32Array;
+        uvs2?: Float32Array;
         normals?: Float32Array;
     } {
         if (entry?.positions) {
@@ -2519,6 +2950,11 @@ export class ParticleSystem implements IParticleSystem {
                         ? 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
@@ -2539,6 +2975,10 @@ export class ParticleSystem implements IParticleSystem {
                 positions,
                 indices: ensureTriangleIndices(positions, indices),
                 uvs: data.attributes.uv?.array ? new Float32Array(data.attributes.uv.array) : undefined,
+                // 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,
             };
         }
@@ -2601,6 +3041,9 @@ export class ParticleSystem implements IParticleSystem {
                 startLength: (this.rendererEmitterSettings as TrailSettings).startLength.clone(),
                 followLocalOrigin: (this.rendererEmitterSettings as TrailSettings).followLocalOrigin,
                 ...trailFlags(this.rendererEmitterSettings as TrailSettings),
+                ...((this.rendererEmitterSettings as TrailSettings).sideAxis
+                    ? {sideAxis: (this.rendererEmitterSettings as TrailSettings).sideAxis!.clone()}
+                    : {}),
             };
         } else if (this.renderMode === RenderMode.StretchedBillBoard) {
             rendererEmitterSettings = {
@@ -2631,6 +3074,7 @@ export class ParticleSystem implements IParticleSystem {
             instancingGeometry: this.rendererSettings.instancingGeometry,
             instancingIndices: this.rendererSettings.instancingIndices,
             instancingUVs: this.rendererSettings.instancingUVs,
+            instancingUVs2: this.rendererSettings.instancingUVs2,
             instancingNormals: this.rendererSettings.instancingNormals,
             renderMode: this.renderMode,
             renderOrder: this.renderOrder,
@@ -2638,6 +3082,7 @@ export class ParticleSystem implements IParticleSystem {
             applyFog: this.applyFog,
             playbackSpeed: this.playbackSpeed,
             cullingMode: this.cullingMode,
+            scalingMode: this.scalingMode,
             seed: this.seedValue,
             sortMode: this.sortMode,
             alignToDirection: this.alignToDirection,
@@ -2665,6 +3110,10 @@ export class ParticleSystem implements IParticleSystem {
             flip: this.flip,
             lighting: this.lighting,
             rim: this.rim,
+            mapUV: this.mapUV,
+            gradientMap: this.gradientMap,
+            erosion: this.erosion,
+            uvDistortion: this.uvDistortion,
             scene: this.emitter.getScene(),
         });
         // A sub emitter behavior transforms by its parent system's emitter;
@@ -2674,6 +3123,9 @@ export class ParticleSystem implements IParticleSystem {
                 behavior.particleSystem = copy;
             }
         }
+        if (this.tint) {
+            copy.tint = this.tint.clone();
+        }
         return copy;
     }
 }