babylon.quarks 0.26.0 → 0.27.0

package/src/system/integrate.ts

@@ -0,0 +1,428 @@
+import {
+    Behavior,
+    FusionStep,
+    Matrix4,
+    Particle,
+    ParticleStore,
+    RendererEmitterSettings,
+    TrailParticle,
+    TrailSettings,
+    Vector3,
+} from 'quarks.core';
+import type {VFXBatchSettings} from '../BatchedRenderer';
+import {trailLifetime, trailMinVertexDistance} from '../trailSettings';
+import type {BoundsTracker} from './BoundsTracker';
+import {SIMULATION_STEP} from './SimulationClock';
+
+// The passes of one simulation step after emission: the snapshot the renderer extrapolates
+// from, the behaviors, then the motion, ageing and removal of the sprite path (one pass over
+// the store's columns) or of the trail path (over the particle objects their history lives on).
+// Plain functions over the store and the particle array, so the hot loops stay monomorphic.
+
+/** Particle backed by a {@link ParticleStore} row, as a system always creates. */
+type StoreBackedParticle = Particle & {storeIndex: number; setStoreIndex(index: number): void};
+
+/** Called with each particle that died this step, when the system has `particleDied` listeners. */
+export type DeathListener = (particle: Particle) => void;
+
+/** Settings the bounds measurement reads, see {@link BoundsTracker.store}. */
+export interface BoundsSettings {
+    /** The render settings, for the particle size the bounds are padded by. */
+    rendererSettings: VFXBatchSettings;
+    /** The render mode's settings, for a stretched billboard's length. */
+    rendererEmitterSettings: RendererEmitterSettings;
+    /** Whether the positions are in world space already. */
+    worldSpace: boolean;
+}
+
+const tempV = new Vector3();
+
+/**
+ * Remembers where everything starts this step, so the renderer can carry the motion the step
+ * produces on into the part of the frame that comes after it. Size and colour are only
+ * snapshotted when some behavior can change them; otherwise the columns stay what spawn wrote
+ * and the renderer reads them as they are. Only stretched billboards draw from velocity, and only
+ * they pay for keeping the previous one; `rebind` is called when keeping it first allocates its
+ * column, since every particle then has to be re-pointed at the store.
+ */
+export function snapshotPreviousState(
+    store: ParticleStore,
+    particleCount: number,
+    snapshotSize: boolean,
+    snapshotColor: boolean,
+    keepVelocity: boolean,
+    rebind: () => void
+): void {
+    const vector3Rows = particleCount * 3;
+    store.useSizeSnapshot(snapshotSize);
+    store.useColorSnapshot(snapshotColor);
+    store.previousPosition.set(store.position.subarray(0, vector3Rows));
+    if (snapshotSize) {
+        store.previousSize.set(store.size.subarray(0, vector3Rows));
+    }
+    if (keepVelocity) {
+        if (store.keepPreviousVelocity()) {
+            rebind();
+        }
+        store.previousVelocity.set(store.velocity.subarray(0, vector3Rows));
+    }
+    if (snapshotColor) {
+        store.previousColor.set(store.color.subarray(0, particleCount * 4));
+    }
+}
+
+/** Runs the behaviors' frame updates and then each step of the plan over the live particles. */
+export function runBehaviorSteps(
+    steps: ReadonlyArray<FusionStep>,
+    behaviors: Behavior[],
+    particles: Particle[],
+    particleCount: number,
+    delta: number,
+    store: ParticleStore
+): void {
+    for (let s = 0; s < steps.length; s++) {
+        const step = steps[s];
+        const stepBehaviors = step.behaviors;
+        for (let j = 0; j < stepBehaviors.length; j++) {
+            stepBehaviors[j].frameUpdate(delta);
+        }
+        // Nothing to update: skip, matching what the per-particle loop did.
+        // A behavior may set up state before its loop that is only valid
+        // once it has seen a particle.
+        if (particleCount === 0) {
+            continue;
+        }
+        if (step.run !== undefined) {
+            step.run(behaviors, particles, particleCount, delta, store);
+            continue;
+        }
+        const behavior = stepBehaviors[0];
+        if (behavior.updateAll !== undefined) {
+            behavior.updateAll(particles, particleCount, delta);
+            continue;
+        }
+        for (let i = 0; i < particleCount; i++) {
+            const particle = particles[i];
+            // Inlined `died` — this runs once per behavior per particle.
+            if (particle.age < particle.life) {
+                behavior.update(particle, delta);
+            }
+        }
+    }
+}
+
+/**
+ * Moves a dead particle's slot and row to the end of the live range, so slot k always owns
+ * row k and the live particles stay one contiguous range the renderer copies as is. Returns
+ * the particle that died.
+ */
+function retire(particles: Particle[], store: ParticleStore, i: number, last: number): Particle {
+    const particle = particles[i];
+    const survivor = particles[last] as StoreBackedParticle;
+    particles[i] = survivor;
+    particles[last] = particle;
+    if (i !== last) {
+        store.swapRows(i, last);
+        survivor.setStoreIndex(i);
+        (particle as StoreBackedParticle).setStoreIndex(last);
+    }
+    return particle;
+}
+
+/**
+ * The sprite path's step after the behaviors, as one pass over the columns that does three
+ * things, none of which touches a particle object until a death. Returns the live count.
+ *
+ * Newborns were snapshotted with their spawn size and colour, before SizeOverLife and
+ * ColorOverLife ran. That false jump would be extrapolated by the renderer when the residual is
+ * negative (common with the rounded fixed step) and flash the start appearance at the emitter,
+ * so the snapshot is collapsed onto the curves' t=0 value. Age is still 0 at that point; the
+ * same iteration then ages it.
+ *
+ * Position is integrated along the velocity.
+ *
+ * A particle whose age reached its life is swapped with the last live one, rows included. The
+ * survivor moved into the slot has not been visited yet, so the slot is processed again.
+ *
+ * The bounds fall out of the same pass. Measuring every particle on every step costs about as
+ * much as the integration itself, so the full measurement runs every few steps; in between,
+ * newborns extend the last bounds and the fastest particle seen since pads them for the motion,
+ * which keeps them conservative.
+ */
+export function integrateSprites(
+    delta: number,
+    particles: Particle[],
+    store: ParticleStore,
+    liveParticleCount: number,
+    collapseSize: boolean,
+    collapseColor: boolean,
+    bounds: BoundsTracker,
+    settings: BoundsSettings,
+    onDied: DeathListener | undefined
+): number {
+    const scalars = store.scalars;
+    const stride = ParticleStore.SCALAR_STRIDE;
+    const positions = store.position;
+    const velocities = store.velocity;
+    const prevSize = store.previousSize;
+    const curSize = store.size;
+    const prevColor = store.previousColor;
+    const curColor = store.color;
+    const measure = bounds.due;
+    const carriedMin = bounds.min;
+    const carriedMax = bounds.max;
+    let minX = measure ? Infinity : carriedMin.x;
+    let minY = measure ? Infinity : carriedMin.y;
+    let minZ = measure ? Infinity : carriedMin.z;
+    let maxX = measure ? -Infinity : carriedMax.x;
+    let maxY = measure ? -Infinity : carriedMax.y;
+    let maxZ = measure ? -Infinity : carriedMax.z;
+    let maxSize = measure ? 0 : bounds.maxSize;
+    let maxSpeedSq = measure ? 0 : bounds.maxSpeedSq;
+    for (let i = 0; i < liveParticleCount; i++) {
+        const scalar = i * stride;
+        let age = scalars[scalar + ParticleStore.AGE];
+        const offset = i * 3;
+        const track = measure || age === 0;
+        if (age === 0) {
+            if (collapseSize) {
+                prevSize[offset] = curSize[offset];
+                prevSize[offset + 1] = curSize[offset + 1];
+                prevSize[offset + 2] = curSize[offset + 2];
+            }
+            if (collapseColor) {
+                const o4 = i * 4;
+                prevColor[o4] = curColor[o4];
+                prevColor[o4 + 1] = curColor[o4 + 1];
+                prevColor[o4 + 2] = curColor[o4 + 2];
+                prevColor[o4 + 3] = curColor[o4 + 3];
+            }
+        }
+        const step = delta * scalars[scalar + ParticleStore.SPEED_MODIFIER];
+        const vx = velocities[offset];
+        const vy = velocities[offset + 1];
+        const vz = velocities[offset + 2];
+        const x = positions[offset] + vx * step;
+        const y = positions[offset + 1] + vy * step;
+        const z = positions[offset + 2] + vz * step;
+        positions[offset] = x;
+        positions[offset + 1] = y;
+        positions[offset + 2] = z;
+        if (track) {
+            minX = Math.min(minX, x);
+            maxX = Math.max(maxX, x);
+            minY = Math.min(minY, y);
+            maxY = Math.max(maxY, y);
+            minZ = Math.min(minZ, z);
+            maxZ = Math.max(maxZ, z);
+            maxSize = Math.max(maxSize, Math.max(curSize[offset], Math.max(curSize[offset + 1], curSize[offset + 2])));
+        }
+        // Speed is tracked every step: it bounds how far the particles
+        // can have moved since the last measurement.
+        maxSpeedSq = Math.max(maxSpeedSq, vx * vx + vy * vy + vz * vz);
+        age += delta;
+        scalars[scalar + ParticleStore.AGE] = age;
+        if (age >= scalars[scalar + ParticleStore.LIFE]) {
+            const particle = retire(particles, store, i, liveParticleCount - 1);
+            liveParticleCount--;
+            i--;
+            if (onDied !== undefined) {
+                onDied(particle);
+            }
+        }
+    }
+    bounds.store(
+        liveParticleCount,
+        measure,
+        minX,
+        minY,
+        minZ,
+        maxX,
+        maxY,
+        maxZ,
+        maxSize,
+        maxSpeedSq,
+        settings.rendererSettings,
+        settings.rendererEmitterSettings,
+        settings.worldSpace,
+        SIMULATION_STEP
+    );
+    return liveParticleCount;
+}
+
+/** The newborn collapse of the trail path, see {@link integrateSprites}; trails keep their history on the objects, so it is its own pass. */
+export function collapseTrailNewborns(
+    store: ParticleStore,
+    particleCount: number,
+    snapshotSize: boolean,
+    snapshotColor: boolean
+): void {
+    const scalars = store.scalars;
+    const stride = ParticleStore.SCALAR_STRIDE;
+    const prevSize = store.previousSize;
+    const curSize = store.size;
+    const prevColor = store.previousColor;
+    const curColor = store.color;
+    for (let i = 0, o3 = 0, o4 = 0, s = 0; i < particleCount; i++, o3 += 3, o4 += 4, s += stride) {
+        if (scalars[s + ParticleStore.AGE] !== 0) {
+            continue;
+        }
+        if (snapshotSize) {
+            prevSize[o3] = curSize[o3];
+            prevSize[o3 + 1] = curSize[o3 + 1];
+            prevSize[o3 + 2] = curSize[o3 + 2];
+        }
+        if (snapshotColor) {
+            prevColor[o4] = curColor[o4];
+            prevColor[o4 + 1] = curColor[o4 + 1];
+            prevColor[o4 + 2] = curColor[o4 + 2];
+            prevColor[o4 + 3] = curColor[o4 + 3];
+        }
+    }
+}
+
+/**
+ * Moves and ages the trail particles: a trail that follows its local origin is placed by its
+ * emitter (or parent) matrix every step, any other along its velocity.
+ */
+export function moveTrails(
+    delta: number,
+    particles: Particle[],
+    store: ParticleStore,
+    particleCount: number,
+    followLocalOrigin: boolean,
+    emitterMatrix: Matrix4
+): void {
+    if (followLocalOrigin) {
+        for (let i = 0; i < particleCount; i++) {
+            const particle = particles[i];
+            if ((particle as TrailParticle).localPosition) {
+                particle.position.copy((particle as TrailParticle).localPosition!);
+                particle.position.applyMatrix4(particle.parentMatrix ?? emitterMatrix);
+            } else {
+                particle.position.addScaledVector(particle.velocity, delta * particle.speedModifier);
+            }
+            particle.age += delta;
+        }
+        return;
+    }
+    const scalars = store.scalars;
+    const stride = ParticleStore.SCALAR_STRIDE;
+    const positions = store.position;
+    const velocities = store.velocity;
+    for (let i = 0, offset = 0, scalar = 0; i < particleCount; i++, offset += 3, scalar += stride) {
+        const step = delta * scalars[scalar + ParticleStore.SPEED_MODIFIER];
+        positions[offset] += velocities[offset] * step;
+        positions[offset + 1] += velocities[offset + 1] * step;
+        positions[offset + 2] += velocities[offset + 2] * step;
+        scalars[scalar + ParticleStore.AGE] += delta;
+    }
+}
+
+/**
+ * Records this step's sample into each trail's history: its position (in world space when the
+ * trail asks for it and the system is not already there) and, for a swept trail, the side axis
+ * as the emitter holds it, in the space the positions are recorded in. With a minimum vertex
+ * distance the newest sample follows the particle until it is that far from the sample before;
+ * samples older than the trail's lifetime are dropped from the tail. A trail that dies with its
+ * particle has its history emptied instead, so the removal pass takes it this same step.
+ */
+export function recordTrailHistory(
+    particles: Particle[],
+    particleCount: number,
+    trailSettings: TrailSettings,
+    worldSpace: boolean,
+    emitterMatrix: Matrix4
+): void {
+    const dieWithParticle = trailSettings.dieWithParticle;
+    // A world-space system records world positions already.
+    const recordWorldSpace = trailSettings.recordWorldSpace && !worldSpace;
+    const sideAxis = trailSettings.sideAxis;
+    const sidesInWorld = worldSpace || Boolean(trailSettings.recordWorldSpace);
+    const minDistance = trailMinVertexDistance(trailSettings);
+    const lifetime = trailLifetime(trailSettings);
+    for (let i = 0; i < particleCount; i++) {
+        const trail = particles[i] as TrailParticle;
+        // A particle at the end of its life is dead: it records nothing more and its trail fades.
+        const alive = trail.age < trail.life;
+        if (dieWithParticle && !alive) {
+            trail.resetHistory();
+            continue;
+        }
+        // The newest sample follows the particle until it is the minimum distance from the sample
+        // before it; then it is fixed where it is and this step's sample starts a new one.
+        let replaceHead = false;
+        if (minDistance > 0 && alive && trail.historyCount > 1) {
+            const distances = trail.historyDistances;
+            const count = trail.historyCount;
+            replaceHead =
+                distances[trail.getHistoryIndex(count - 1)] - distances[trail.getHistoryIndex(count - 2)] < minDistance;
+        }
+        trail.update(replaceHead, !recordWorldSpace);
+        // update() wrote a sample only while the particle is alive.
+        if (recordWorldSpace && alive) {
+            const offset = ((trail.historyHead + trail.historyCapacity - 1) % trail.historyCapacity) * 3;
+            const positions = trail.historyPositions;
+            tempV.set(positions[offset], positions[offset + 1], positions[offset + 2]);
+            tempV.applyMatrix4(trail.parentMatrix ?? emitterMatrix);
+            positions[offset] = tempV.x;
+            positions[offset + 1] = tempV.y;
+            positions[offset + 2] = tempV.z;
+            trail.measureHeadDistance();
+        }
+        if (lifetime !== Infinity) {
+            const ages = trail.historyAges;
+            const age = trail.age;
+            while (trail.historyCount > 0 && age - ages[trail.getHistoryIndex(0)] > lifetime) {
+                trail.dropOldest();
+            }
+        }
+        if (sideAxis && alive) {
+            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;
+        }
+    }
+}
+
+/**
+ * Retires each trail particle that has died and whose ribbon has faded out (an empty history),
+ * the same swap as the sprite path. Returns the live count.
+ */
+export function removeDeadTrails(
+    particles: Particle[],
+    store: ParticleStore,
+    liveParticleCount: number,
+    onDied: DeathListener | undefined
+): number {
+    const scalars = store.scalars;
+    const stride = ParticleStore.SCALAR_STRIDE;
+    for (let i = 0; i < liveParticleCount; i++) {
+        const particle = particles[i] as TrailParticle;
+        const scalar = i * stride;
+        const dead = scalars[scalar + ParticleStore.AGE] >= scalars[scalar + ParticleStore.LIFE];
+        if (dead && particle.historyCount === 0) {
+            retire(particles, store, i, liveParticleCount - 1);
+            liveParticleCount--;
+            i--;
+            if (onDied !== undefined) {
+                onDied(particle);
+            }
+        }
+    }
+    return liveParticleCount;
+}

package/src/system/materialResolve.ts

@@ -0,0 +1,116 @@
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {Texture} from '@babylonjs/core/Materials/Textures/texture';
+import type {VFXBatchSettings} from '../BatchedRenderer';
+
+/** Settings given next to a material, which win over what is read from it. */
+export interface MaterialOverrides {
+    blendMode?: number;
+    transparent?: boolean;
+    depthTest?: boolean;
+    depthWrite?: boolean;
+    alphaTest?: number;
+    texture?: Texture | null;
+    reflectionAtlas?: BaseTexture | null;
+    layerMask?: number;
+}
+
+/** The draw settings a {@link ParticleSystem} takes from a material, before the env atlas is built. */
+export interface ResolvedMaterialSettings {
+    texture: Texture | null;
+    reflectionTexture: BaseTexture | null;
+    reflectionLevel: number;
+    /** A live atlas the material, the overrides or the current settings already have; null if none. */
+    reflectionAtlas: BaseTexture | null;
+    blendMode: number;
+    transparent: boolean;
+    depthTest: boolean;
+    depthWrite: boolean;
+    alphaTest: number;
+}
+
+/** `atlas` unless it has been disposed (it no longer has a scene). */
+export function liveAtlas<T extends BaseTexture>(atlas: T | null | undefined): T | null {
+    return atlas?.getScene() ? atlas : null;
+}
+
+/**
+ * Reads the draw settings from a Babylon material, or from the material record of a loaded file:
+ * its texture, reflection, alpha mode, depth flags and alpha test. `overrides` win; a setting the
+ * material does not have keeps its `current` value.
+ */
+export function resolveMaterialSettings(
+    material: any,
+    overrides: MaterialOverrides,
+    current: VFXBatchSettings
+): ResolvedMaterialSettings {
+    const texture =
+        overrides.texture !== undefined
+            ? overrides.texture
+            : (material?.albedoTexture ??
+              material?.diffuseTexture ??
+              material?.emissiveTexture ??
+              material?.opacityTexture ??
+              material?.baseTexture ??
+              current.texture ??
+              null);
+    const reflectionTexture =
+        material?.reflectionTexture ?? material?.environmentTexture ?? current.reflectionTexture ?? null;
+    const reflectionTextureLevel = typeof reflectionTexture?.level === 'number' ? reflectionTexture.level : 1;
+    const blendMode =
+        overrides.blendMode ??
+        (typeof material?.alphaMode === 'number' ? material.alphaMode : current.materialBlendMode);
+    const transparent =
+        overrides.transparent ??
+        (typeof material?.needAlphaBlending === 'function'
+            ? material.needAlphaBlending()
+            : typeof material?.alpha === 'number'
+              ? material.alpha < 1
+              : current.materialTransparent);
+    const depthTest =
+        overrides.depthTest ??
+        (typeof material?.disableDepthTest === 'boolean' ? !material.disableDepthTest : current.materialDepthTest);
+    const depthWrite =
+        overrides.depthWrite ??
+        (typeof material?.disableDepthWrite === 'boolean'
+            ? !material.disableDepthWrite
+            : typeof material?.forceDepthWrite === 'boolean'
+              ? material.forceDepthWrite
+              : current.materialDepthWrite);
+    const alphaTest =
+        overrides.alphaTest ??
+        (() => {
+            // StandardMaterial always has alphaCutOff (default 0.4). Only treat it as
+            // particle alpha-test when the material is actually in an alpha-test mode —
+            // otherwise Mesh Material demos wrongly enable USE_ALPHATEST.
+            const mode = material?.transparencyMode;
+            const alphaTestMode = mode === 1 || mode === 3;
+            if (alphaTestMode && typeof material?.alphaCutOff === 'number') {
+                return material.alphaCutOff;
+            }
+            if (alphaTestMode && typeof material?.alphaCutOffValue === 'number') {
+                return material.alphaCutOffValue;
+            }
+            if (material) {
+                return 0;
+            }
+            return current.materialAlphaTest;
+        })();
+    return {
+        texture,
+        reflectionTexture,
+        reflectionLevel:
+            typeof material?.reflectionLevel === 'number' ? material.reflectionLevel : reflectionTextureLevel,
+        // A disposed atlas (its cube was disposed, or disposeEnvAtlas ran) is skipped, so a new one is built.
+        reflectionAtlas:
+            liveAtlas(material?.reflectionAtlas) ??
+            liveAtlas(overrides.reflectionAtlas) ??
+            liveAtlas(current.reflectionAtlas),
+        // Do not expand cube files into six face textures anymore — that path
+        // still trips GL_INVALID_OPERATION on iOS. Prefer a single atlas.
+        blendMode,
+        transparent,
+        depthTest,
+        depthWrite,
+        alphaTest,
+    };
+}

package/src/system/normalize.ts

@@ -0,0 +1,95 @@
+import {ConstantValue, FunctionValueGenerator, ValueGenerator, Vector2, Vector3} from 'quarks.core';
+import type {MeshLighting, SortMode} from '../VFXBatch';
+import type {BurstParameters, CullingMode} from './types';
+
+// Normalisers shared by the ParticleSystem constructor, its setters and its JSON reader, so a
+// value read from a file and one set in code end up the same.
+
+/** `lighting` if it is one of the modes, else the default. */
+export function validLighting(lighting: unknown): MeshLighting {
+    return lighting === 'unlit' || lighting === 'scene' ? lighting : 'fixed';
+}
+
+/** `mode` if it is one of the sort modes, else `'none'`. */
+export function validSortMode(mode: unknown): SortMode {
+    return mode === 'distance' || mode === 'oldestInFront' || mode === 'youngestInFront' ? mode : 'none';
+}
+
+/** `mode` if it is one of the culling modes, else `'always'`. */
+export function validCullingMode(mode: unknown): CullingMode {
+    return mode === 'pause' || mode === 'pauseAndCatchUp' ? mode : 'always';
+}
+
+/** `count` as a whole number of particles, or undefined (no limit) when it is unset, NaN or negative. */
+export function validMaxParticles(count: unknown): number | undefined {
+    return typeof count === 'number' && count >= 0 && count < Infinity ? Math.floor(count) : undefined;
+}
+
+/** A copy of `v`, or undefined when it is unset or zero, which is the same as no pivot. */
+export function nonZeroPivot(v: Vector3 | undefined): Vector3 | undefined {
+    return v && (v.x !== 0 || v.y !== 0 || v.z !== 0) ? v.clone() : undefined;
+}
+
+/** A copy of `v`, or undefined when neither axis flips. */
+export function nonZeroFlip(v: Vector2 | undefined): Vector2 | undefined {
+    return v && (v.x > 0 || v.y > 0) ? v.clone() : undefined;
+}
+
+/** `cutoff` kept to 0…1, or 0 (no alpha test) when it is unset, NaN or negative. */
+export function validAlphaTest(cutoff: unknown): number {
+    return typeof cutoff === 'number' && cutoff > 0 ? Math.min(cutoff, 1) : 0;
+}
+
+/** A flipbook's columns or rows: a whole number of cells, at least 1; anything else is 1. */
+export function validTileCount(count: unknown): number {
+    return typeof count === 'number' && Number.isFinite(count) && count >= 1 ? Math.floor(count) : 1;
+}
+
+/** World units in front of the scene over which a soft particle is fully faded by default. */
+export const DEFAULT_SOFT_FAR_FADE = 1;
+
+/** A soft-particle fade distance: finite and at least 0, else `fallback`. */
+export function validSoftFade(distance: unknown, fallback: number): number {
+    return typeof distance === 'number' && Number.isFinite(distance) && distance >= 0 ? distance : fallback;
+}
+
+/** Seconds between a burst's waves when a burst leaves `interval` out, in code and in a file. */
+export const DEFAULT_BURST_INTERVAL = 0.1;
+
+/**
+ * A burst with every field present and in range: a `time` that is a finite number of seconds
+ * (else 0), a `count` generator (a number becomes a constant, nothing becomes 0), `cycle` at least
+ * 1, `interval` {@link DEFAULT_BURST_INTERVAL} when left out and never negative, `probability`
+ * within 0..1 (1 when left out). The same rules apply to a burst given to the constructor and one
+ * read from a file, so both fire alike.
+ */
+export function normalizeBurst(burst: Partial<BurstParameters> & {count?: unknown}): BurstParameters {
+    const count = burst.count;
+    const time = typeof burst.time === 'number' && Number.isFinite(burst.time) && burst.time > 0 ? burst.time : 0;
+    const cycle = typeof burst.cycle === 'number' && Number.isFinite(burst.cycle) && burst.cycle >= 1 ? burst.cycle : 1;
+    const interval =
+        typeof burst.interval === 'number' && Number.isFinite(burst.interval)
+            ? Math.max(0, burst.interval)
+            : DEFAULT_BURST_INTERVAL;
+    const probability =
+        typeof burst.probability === 'number' && Number.isFinite(burst.probability)
+            ? Math.min(1, Math.max(0, burst.probability))
+            : 1;
+    return {
+        time,
+        count:
+            typeof count === 'number'
+                ? new ConstantValue(count)
+                : count !== undefined && count !== null
+                  ? (count as ValueGenerator | FunctionValueGenerator)
+                  : new ConstantValue(0),
+        cycle,
+        interval,
+        probability,
+    };
+}
+
+/** The bursts normalised (see {@link normalizeBurst}) and in time order, which emission relies on. */
+export function normalizeBursts(bursts: ReadonlyArray<Partial<BurstParameters>> | undefined): BurstParameters[] {
+    return (bursts ?? []).map(normalizeBurst).sort((a, b) => a.time - b.time);
+}