babylon.quarks 0.26.0 → 0.28.0

package/src/system/SimulationClock.ts

@@ -0,0 +1,130 @@
+/** Length of one simulation step, in seconds: the simulation runs at a fixed 60 Hz. */
+export const SIMULATION_STEP = 1 / 60;
+
+/** Most steps one host frame runs at playback speed 1; a faster speed raises the cap in proportion. */
+export const MAX_STEPS_PER_FRAME = 8;
+
+/** Most host time one frame simulates, in seconds, so a stall or a tab in the background is not replayed. */
+export const MAX_FRAME_SECONDS = 0.1;
+
+/** Most off-screen time a `'pauseAndCatchUp'` system replays on coming back into view, in seconds. */
+export const MAX_CATCH_UP_SECONDS = 2;
+
+/**
+ * Math.round() breaks an exact tie (the accumulator sitting at precisely half a step) by rounding
+ * up. At exactly 120 Hz that tie is not a corner case, it is every frame, and rounding it up would
+ * run a step on every one of them instead of every other one. Nudging the tie down costs nothing on
+ * a real display (real frame times essentially never land on the tie exactly) and keeps the
+ * well-tested "half a step is no step yet" behaviour.
+ */
+const ROUND_TIE_BIAS = 1e-9;
+
+/**
+ * The fixed-step clock of a particle system: turns the host's uneven frames into whole 60 Hz
+ * steps, and keeps the start delay and the time a culled system still owes. Pure numbers, so the
+ * frame-rate rules can be tested without a scene.
+ *
+ * The steps a frame runs are chosen by *rounding* the accumulated time to the nearest step, not
+ * flooring it. Flooring always leaves the accumulator positive, and when the real frame rate sits
+ * very close to 60 Hz (as most displays do) that leftover creeps toward a full step for many frames
+ * before tipping over into a frame that runs two steps at once and resets it to near zero: a
+ * visible lurch, every particle at once, with a perfectly steady frame rate. Rounding lets the
+ * leftover go negative instead, which keeps it centred near zero. The renderer closes the gap by
+ * drawing each particle advanced along its velocity by {@link residual}.
+ */
+export class SimulationClock {
+    /** Simulated time not yet covered by a whole step, in seconds; negative when a step ran early. */
+    private accumulator = 0;
+    /** Off-screen time a `'pauseAndCatchUp'` system has not simulated yet, in seconds. */
+    private pendingCatchUp = 0;
+    /** Start delay still to wait out, in seconds. */
+    private delayLeft = 0;
+
+    /** Back to the start of a play: nothing accumulated, nothing owed. The start delay is set apart. */
+    reset(): void {
+        this.accumulator = 0;
+        this.pendingCatchUp = 0;
+    }
+
+    /** Sets the start delay to wait out before the first step; a negative or NaN delay is none. */
+    setStartDelay(seconds: number): void {
+        this.delayLeft = seconds > 0 ? seconds : 0;
+    }
+
+    /** Whether a start delay is still being waited out. */
+    get delaying(): boolean {
+        return this.delayLeft > 0;
+    }
+
+    /**
+     * The simulated seconds a host frame of `hostDelta` seconds stands for at `playbackSpeed`. The
+     * host time is clamped to {@link MAX_FRAME_SECONDS} first, so a fast playback speed advances
+     * its full share of a normal frame (speed 10 at 60 fps simulates 10 seconds per second) while a
+     * stalled frame is still not replayed. A negative or NaN frame is no time at all.
+     */
+    static frameSeconds(hostDelta: number, playbackSpeed: number): number {
+        if (!(hostDelta > 0)) return 0;
+        const clamped = hostDelta > MAX_FRAME_SECONDS ? MAX_FRAME_SECONDS : hostDelta;
+        return clamped * playbackSpeed;
+    }
+
+    /**
+     * Takes `delta` seconds off the start delay and returns what is left over for the simulation:
+     * 0 while the delay runs, the remainder of the frame that ends it (at most one frame's worth, so
+     * a long frame does not burst the first steps), and `delta` itself once there is no delay.
+     */
+    consumeStartDelay(delta: number): number {
+        if (this.delayLeft <= 0) {
+            return delta;
+        }
+        this.delayLeft -= delta;
+        if (this.delayLeft >= 0) {
+            return 0;
+        }
+        const left = Math.min(-this.delayLeft, MAX_FRAME_SECONDS);
+        this.delayLeft = 0;
+        return left;
+    }
+
+    /**
+     * Adds `delta` simulated seconds and returns how many whole steps to run for them, at most
+     * {@link MAX_STEPS_PER_FRAME} scaled by `playbackSpeed` above 1. The steps' time is taken off
+     * the accumulator whether or not the caller runs them all, so a frame that cannot afford its
+     * steps drops their time rather than carrying it into the next frame.
+     */
+    accrue(delta: number, playbackSpeed = 1): number {
+        this.accumulator += delta;
+        const cap = playbackSpeed > 1 ? Math.ceil(MAX_STEPS_PER_FRAME * playbackSpeed) : MAX_STEPS_PER_FRAME;
+        const steps = Math.min(cap, Math.max(0, Math.round(this.accumulator / SIMULATION_STEP - ROUND_TIE_BIAS)));
+        this.accumulator -= steps * SIMULATION_STEP;
+        return steps;
+    }
+
+    /**
+     * Time the display is ahead of the simulation (positive) or behind it (negative, the simulation
+     * ran a hair early), in seconds. Its magnitude never exceeds one step, even when the per-frame
+     * step cap left more than that accumulated.
+     */
+    get residual(): number {
+        if (this.accumulator > SIMULATION_STEP) return SIMULATION_STEP;
+        if (this.accumulator < -SIMULATION_STEP) return -SIMULATION_STEP;
+        return this.accumulator;
+    }
+
+    /** Remembers `delta` simulated seconds a culled system missed, up to {@link MAX_CATCH_UP_SECONDS}. */
+    deferCatchUp(delta: number): void {
+        this.pendingCatchUp = Math.min(MAX_CATCH_UP_SECONDS, this.pendingCatchUp + delta);
+    }
+
+    /** Whether a culled system still owes steps. */
+    get owesCatchUp(): boolean {
+        return this.pendingCatchUp > 0;
+    }
+
+    /** The whole steps a system owes from its time off screen, and forgets them. */
+    takeCatchUpSteps(): number {
+        const steps = Math.floor(this.pendingCatchUp / SIMULATION_STEP);
+        this.pendingCatchUp = 0;
+        return steps;
+    }
+}

package/src/system/geometry.ts

@@ -0,0 +1,104 @@
+import type {BufferGeometryDataJSON, GeometryArrays, GeometryEntry} from '../effectDocumentJSON';
+import {ensureTriangleIndices} from '../geometryUtil';
+
+/** Positions of the unit quad billboards are drawn with, and the default mesh. */
+export const DEFAULT_POSITIONS = new Float32Array([-0.5, -0.5, 0, 0.5, -0.5, 0, 0.5, 0.5, 0, -0.5, 0.5, 0]);
+/** UVs of the default quad. */
+export const DEFAULT_UVS = new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]);
+/** Indices of the default quad's two triangles. */
+export const DEFAULT_INDICES = new Uint32Array([0, 1, 2, 0, 2, 3]);
+
+/** 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.
+ */
+export function fallbackUVsForPositions(positions: Float32Array): Float32Array {
+    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;
+}
+
+/** Whether `uvs` are the ones {@link fallbackUVsForPositions} made for `positions`. */
+export function isFallbackUVs(uvs: Float32Array | undefined, positions: Float32Array): boolean {
+    return uvs !== undefined && uvs === fallbackUVs.get(positions);
+}
+
+/** Normals facing +Z, one array per geometry so systems sharing it still batch together. */
+export function fallbackNormalsForPositions(positions: Float32Array): Float32Array {
+    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;
+}
+
+/** Whether `normals` are the ones {@link fallbackNormalsForPositions} made for `positions`. */
+export function isFallbackNormals(normals: Float32Array | undefined, positions: Float32Array): boolean {
+    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 or its `data`. Anything else gives the
+ * default quad.
+ */
+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
+                : entry.indices
+                  ? new Uint32Array(entry.indices)
+                  : undefined;
+        return {
+            positions,
+            indices: ensureTriangleIndices(positions, rawIndices),
+            uvs: floats(entry.uvs),
+            uvs2: floats(entry.uvs2),
+            normals: floats(entry.normals),
+        };
+    }
+
+    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;
+            indices = new indexType(data.index.array);
+        }
+        return {
+            positions,
+            indices: ensureTriangleIndices(positions, indices),
+            uvs: floats(attributes.uv?.array),
+            // three.js names the second set `uv1` (r151 on), `uv2` before.
+            uvs2: floats((attributes.uv1 ?? attributes.uv2)?.array),
+            normals: floats(attributes.normal?.array),
+        };
+    }
+
+    return {
+        positions: DEFAULT_POSITIONS,
+        indices: DEFAULT_INDICES,
+        uvs: DEFAULT_UVS,
+    };
+}

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