babylon.quarks 0.26.0 → 0.28.0

package/src/system/EmissionController.ts

@@ -0,0 +1,358 @@
+import {
+    EmissionState,
+    FunctionValueGenerator,
+    GeneratorMemory,
+    Matrix4,
+    PiecewiseBezier,
+    random,
+    ValueGenerator,
+    Vector3,
+} from 'quarks.core';
+import type {ParticleSystem} from '../ParticleSystem';
+import type {ParticleSpawner} from './ParticleSpawner';
+import type {BurstParameters} from './types';
+
+/** Points sampled over the rest of the cycle when a non-Bezier rate curve is 0 now, to see if it rises later. */
+const RATE_LOOKAHEAD_SAMPLES = 64;
+
+/** Waves a burst fires per loop: its `cycle`, and never fewer than one. */
+export function burstWaveCount(burst: BurstParameters): number {
+    return burst.cycle >= 1 ? Math.floor(burst.cycle) : 1;
+}
+
+/** Seconds between a burst's waves; a missing or negative interval fires them all at once. */
+export function burstInterval(burst: BurstParameters): number {
+    return burst.interval > 0 ? burst.interval : 0;
+}
+
+/**
+ * Decides how many particles a system owes each step and where: the rate over time, the rate
+ * over the distance the emitter moved, and the bursts with their repeated waves. It keeps the
+ * memory the system-level generators roll into, and hands the spawning to the `ParticleSpawner`.
+ * One per system; a sub emission runs through the same controller with the parent particle's
+ * `EmissionState`.
+ */
+export class EmissionController {
+    /**
+     * The memory the system-level generators (rates, burst counts, start delay) roll into. Emptied
+     * on every restart, and rolled again by {@link rollGenerators}.
+     */
+    readonly memory: GeneratorMemory = [];
+
+    /** Emitter matrix moved along the step's path, see {@link spawnAlongPath}. */
+    private readonly pathMatrix = new Matrix4();
+    private readonly temp = new Vector3();
+
+    constructor(
+        private readonly system: ParticleSystem,
+        private readonly spawner: ParticleSpawner
+    ) {}
+
+    /**
+     * Rolls the system-level generators into the memory and returns the start delay they gave.
+     * A generator that keeps a slot index into the memory, such as `IntervalValue`, would
+     * otherwise read past the end of an emptied one and return NaN. The caller sets the random
+     * source first, so a seeded system replays the same rates, counts and delay.
+     */
+    rollGenerators(): number {
+        const system = this.system;
+        const memory = this.memory;
+        system.emissionBursts.forEach((burst) => burst.count.startGen(memory));
+        system.emissionOverDistance.startGen(memory);
+        system.startDelay.startGen(memory);
+        const delay = system.startDelay.genValue(memory, 0);
+        system.emissionOverTime.startGen(memory);
+        return delay;
+    }
+
+    /** Whether continuous or queued emission can still spawn particles before the system is done. */
+    hasPendingEmission(): boolean {
+        const system = this.system;
+        if (system.isEmitEnded) {
+            return false;
+        }
+        if (system.looping) {
+            return true;
+        }
+        if (system.onlyUsedByOther) {
+            return false;
+        }
+        const state = system.emissionState;
+        if (state.waitEmiting > 0) {
+            return true;
+        }
+        if (state.burstIndex < system.emissionBursts.length) {
+            return true;
+        }
+        if (this.hasPendingBurstWaves(state)) {
+            return true;
+        }
+        if (state.time >= system.duration) {
+            return false;
+        }
+        const timeRatio = state.time / system.duration;
+        return (
+            this.emitsFrom(system.emissionOverTime, timeRatio) || this.emitsFrom(system.emissionOverDistance, timeRatio)
+        );
+    }
+
+    /**
+     * Whether a rate is above 0 now or anywhere later in the cycle, so a curve that fades in from 0
+     * still counts as pending. A Bezier curve is checked exactly from its control points; another
+     * kind of curve is sampled, which only runs while the rate is 0.
+     */
+    private emitsFrom(rate: ValueGenerator | FunctionValueGenerator, timeRatio: number): boolean {
+        if (rate.genValue(this.memory, timeRatio) > 0) {
+            return true;
+        }
+        if (rate.type !== 'function') {
+            return false;
+        }
+        if (rate instanceof PiecewiseBezier) {
+            // A Bezier stays within its control points, so this is exact however short a pulse.
+            for (let i = 0; i < rate.functions.length; i++) {
+                if (rate.getEndX(i) > timeRatio && rate.functions[i][0].p.some((value) => value > 0)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        const samples = RATE_LOOKAHEAD_SAMPLES;
+        for (let i = 1; i <= samples; i++) {
+            if (rate.genValue(this.memory, timeRatio + ((1 - timeRatio) * i) / samples) > 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** True while a burst that has started still has a wave due within the duration. */
+    private hasPendingBurstWaves(state: EmissionState): boolean {
+        const waves = state.burstWaves;
+        if (waves === undefined) {
+            return false;
+        }
+        const bursts = this.system.emissionBursts;
+        const duration = this.system.duration;
+        for (let b = 0; b < state.burstIndex && b < bursts.length; b++) {
+            const burst = bursts[b];
+            const wave = waves[b] ?? 0;
+            if (wave < burstWaveCount(burst) && (wave === 0 || burst.time + wave * burstInterval(burst) <= duration)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Spawns what this step's emission calls for. Called by the simulation step, and by
+     * `EmitSubParticleSystem` on a sub emitter target with the parent particle's state and matrix.
+     */
+    emit(delta: number, emissionState: EmissionState, emitterMatrix: Matrix4): void {
+        const system = this.system;
+        if (system.isDisposed) {
+            return;
+        }
+        const duration = system.duration;
+        // 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 = system.isEmitEnded && emissionState === system.emissionState;
+        if (emissionState.time > duration) {
+            if (system.looping) {
+                emissionState.time -= duration;
+                emissionState.burstIndex = 0;
+                if (emissionState.burstWaves !== undefined) {
+                    emissionState.burstWaves.length = 0;
+                }
+                // Behaviors carry on across the loop (a noise field keeps scrolling, sub emissions
+                // of live particles keep going); they reset only when the system restarts.
+            } else {
+                if (!system.isEmitEnded && !system.onlyUsedByOther) {
+                    system.endEmit();
+                }
+            }
+        }
+
+        // Only spawns in world space consume the normal matrix, and computing it
+        // inverts a 4x4 — skip it for local-space systems.
+        if (system.worldSpace) {
+            this.spawner.normalMatrix.getNormalMatrix(emitterMatrix);
+        }
+        const qualityFactor = system.emissionFactor();
+
+        if (system.emissionBursts.length > 0 && !endedBefore) {
+            this.emitBursts(emissionState, emitterMatrix);
+        }
+
+        // Particles owed to the distance travelled this step, spawned along it.
+        let pathSpawn = 0;
+        let pathSpacing = 0;
+        let pathCarried = 0;
+        let pathLength = 0;
+        const previousWorldPos = emissionState.previousWorldPos;
+        if (!system.isEmitEnded) {
+            const timeRatio = emissionState.time / duration;
+            emissionState.waitEmiting +=
+                delta * system.emissionOverTime.genValue(this.memory, timeRatio) * qualityFactor;
+
+            if (previousWorldPos !== undefined) {
+                this.temp.set(emitterMatrix.elements[12], emitterMatrix.elements[13], emitterMatrix.elements[14]);
+                pathLength = previousWorldPos.distanceTo(this.temp);
+                const emitPerMeter = system.emissionOverDistance.genValue(this.memory, timeRatio) * qualityFactor;
+                if (emitPerMeter > 0) {
+                    pathCarried = emissionState.travelDistance;
+                    emissionState.travelDistance += pathLength;
+                    const count = Math.floor(emissionState.travelDistance * emitPerMeter);
+                    if (count > 0) {
+                        emissionState.travelDistance -= count / emitPerMeter;
+                        // A world-space particle stays where it is born, so it is born
+                        // where the emitter passed its mark. A local-space one moves
+                        // with the emitter and has no path to be spread along.
+                        if (system.worldSpace && pathLength > 0) {
+                            pathSpawn = count;
+                            pathSpacing = 1 / emitPerMeter;
+                        } else {
+                            emissionState.waitEmiting += count;
+                        }
+                    }
+                } else {
+                    // Distance covered while the rate is 0 is not owed later: a rate curve
+                    // that rises, or a rate switched on, must not spawn a line at once.
+                    emissionState.travelDistance = 0;
+                }
+            }
+        }
+
+        // Accrue before spawning so replacement particles can appear on the same
+        // frame an old one dies (rate * lifetime ≈ 1 would otherwise flicker).
+        const totalSpawn = Math.floor(emissionState.waitEmiting);
+        if (totalSpawn > 0) {
+            this.spawner.spawn(totalSpawn, emissionState, emitterMatrix);
+            emissionState.waitEmiting -= totalSpawn;
+        }
+        if (pathSpawn > 0) {
+            this.spawnAlongPath(
+                pathSpawn,
+                emissionState,
+                emitterMatrix,
+                previousWorldPos!,
+                pathCarried,
+                pathSpacing,
+                pathLength
+            );
+        }
+
+        if (emissionState.previousWorldPos === undefined) emissionState.previousWorldPos = new Vector3();
+        emissionState.previousWorldPos.set(
+            emitterMatrix.elements[12],
+            emitterMatrix.elements[13],
+            emitterMatrix.elements[14]
+        );
+        emissionState.time += delta;
+    }
+
+    /**
+     * Fires the burst waves that are due by `emissionState.time`.
+     *
+     * Wave `w` of a burst is due at `burst.time + w * burst.interval`, and the
+     * burst fires `cycle` of them, each rolling `probability` on its own — the
+     * way Unity repeats a burst. Bursts start in time order, as they always
+     * have; their repeats are tracked per burst so a burst that is still
+     * repeating never holds back a later one. Repeats falling past the
+     * system's duration are dropped (a looping system starts them over on its
+     * next loop), matching Unity, which never emits a burst cycle beyond the
+     * end of the duration.
+     */
+    private emitBursts(emissionState: EmissionState, emitterMatrix: Matrix4): void {
+        const bursts = this.system.emissionBursts;
+        const duration = this.system.duration;
+        const burstCount = bursts.length;
+        const time = emissionState.time;
+        const waves = (emissionState.burstWaves ??= []);
+        while (emissionState.burstIndex < burstCount && bursts[emissionState.burstIndex].time <= time) {
+            waves[emissionState.burstIndex] = 0;
+            emissionState.burstIndex++;
+        }
+        const started = emissionState.burstIndex;
+        for (let b = 0; b < started; b++) {
+            const burst = bursts[b];
+            const cycles = burstWaveCount(burst);
+            let wave = waves[b] ?? 0;
+            if (wave >= cycles) {
+                continue;
+            }
+            const interval = burstInterval(burst);
+            while (wave < cycles) {
+                const waveTime = burst.time + wave * interval;
+                if (wave > 0 && waveTime > duration) {
+                    wave = cycles;
+                    break;
+                }
+                if (waveTime > time) {
+                    break;
+                }
+                emissionState.burstWaveIndex = wave;
+                this.fireBurstWave(burst, emissionState, emitterMatrix);
+                wave++;
+            }
+            waves[b] = wave;
+        }
+    }
+
+    /** Spawns one wave of `burst`, if its probability roll passes. */
+    private fireBurstWave(burst: BurstParameters, emissionState: EmissionState, emitterMatrix: Matrix4): void {
+        if (random() >= burst.probability) {
+            return;
+        }
+        // The count curve runs over the cycle like every other start curve, on the state that is
+        // emitting (a sub emission samples the parent particle's time, not the system's).
+        const rawCount = burst.count.genValue(this.memory, emissionState.time / this.system.duration);
+        const factor = this.system.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.spawner.spawn(count, emissionState, emitterMatrix);
+        emissionState.isBursting = false;
+    }
+
+    /**
+     * Spawns `count` particles owed to emission over distance, each where the
+     * emitter crossed its metre mark on the way from `from` to where
+     * `emitterMatrix` has it now, rather than all of them at the end of the
+     * path: a fast emitter then leaves a continuous trail instead of one clump
+     * per step.
+     *
+     * `carried` is how far the emitter had already gone past its last mark
+     * before this step, so the marks keep their spacing across steps. Only the
+     * position is interpolated; the emitter's current rotation and scale are
+     * used for every particle.
+     */
+    private spawnAlongPath(
+        count: number,
+        emissionState: EmissionState,
+        emitterMatrix: Matrix4,
+        from: Vector3,
+        carried: number,
+        spacing: number,
+        length: number
+    ): void {
+        const matrix = this.pathMatrix.copy(emitterMatrix);
+        const target = emitterMatrix.elements;
+        const elements = matrix.elements;
+        const tx = target[12];
+        const ty = target[13];
+        const tz = target[14];
+        for (let k = 1; k <= count; k++) {
+            const travelled = k * spacing - carried;
+            const f = travelled <= 0 ? 0 : travelled >= length ? 1 : travelled / length;
+            elements[12] = from.x + (tx - from.x) * f;
+            elements[13] = from.y + (ty - from.y) * f;
+            elements[14] = from.z + (tz - from.z) * f;
+            this.spawner.spawn(1, emissionState, matrix);
+        }
+    }
+}

package/src/system/EventDispatcher.ts

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

package/src/system/ParticleSpawner.ts

@@ -0,0 +1,274 @@
+import {
+    EmissionState,
+    FunctionValueGenerator,
+    Matrix3,
+    Matrix4,
+    Particle,
+    Quaternion,
+    random,
+    RotationGenerator,
+    SpriteParticle,
+    SubEmitterInheritMask,
+    TrailParticle,
+    TrailSettings,
+    Vector3,
+    Vector3Generator,
+} from 'quarks.core';
+import type {ParticleSystem} from '../ParticleSystem';
+import {RenderMode} from '../VFXBatch';
+
+/** Particle backed by a `ParticleStore` row, as a system always creates. */
+type StoreBackedParticle = Particle & {storeIndex: number};
+
+const UP = new Vector3(0, 0, 1);
+const IDENTITY_QUATERNION = new Quaternion();
+const tempQ = new Quaternion();
+const tempV = new Vector3();
+const tempV2 = new Vector3();
+
+/**
+ * Gives a system its newborn particles: grows the pool and the store they live in, rolls each
+ * particle's start values on the system's generators, places it with the emitter shape and lets
+ * the behaviors claim their slots. One per system; `EmissionController` decides how many to
+ * spawn and when, this decides what each one starts as.
+ */
+export class ParticleSpawner {
+    /**
+     * The emitter matrix's normal matrix, for turning a world-space newborn's velocity. The
+     * emission controller refreshes it before it spawns from a world-space system.
+     */
+    readonly normalMatrix = new Matrix3();
+
+    constructor(private readonly system: ParticleSystem) {}
+
+    /** Points every particle at the store's columns again, after any were replaced. */
+    rebind(): void {
+        const particles = this.system.particles;
+        for (let i = 0; i < particles.length; i++) {
+            (particles[i] as SpriteParticle | TrailParticle).rebind();
+        }
+    }
+
+    /**
+     * Appends one particle to the pool, giving it the next row of the store. Growing the store
+     * replaces its arrays, so every particle already bound to it is re-pointed at the new ones.
+     */
+    private grow(isTrailMode: boolean): void {
+        const system = this.system;
+        const index = system.particles.length;
+        if (system.store.ensureCapacity(index + 1)) {
+            this.rebind();
+        }
+        system.particles.push(
+            isTrailMode ? new TrailParticle(system.store, index) : new SpriteParticle(system.store, index)
+        );
+    }
+
+    /**
+     * Spawns `count` particles at `matrix` (the emitter's, or a parent particle's for a sub
+     * emission), each rolled on the system's start generators at `emissionState`'s normalised
+     * time. A full system (see `maxParticles`) spawns only what it has room for.
+     */
+    spawn(count: number, emissionState: EmissionState, matrix: Matrix4): void {
+        const system = this.system;
+        const translation = tempV;
+        const scale = tempV2;
+        // decompose writes tempQ, so no separate setFromRotationMatrix is needed.
+        matrix.decompose(translation, tempQ, scale);
+        const behaviors = system.behaviors;
+        const behaviorCount = behaviors.length;
+        const renderMode = system.rendererSettings.renderMode;
+        const isTrailMode = renderMode === RenderMode.Trail;
+        const isSpriteMode = !isTrailMode;
+        const isMeshMode = renderMode === RenderMode.Mesh;
+        const startRotation = system.startRotation;
+        const startSize = system.startSize;
+        const startRotationIsRotation = startRotation.type === 'rotation';
+        const startSizeIsVector3 = startSize.type === 'vec3function';
+        const timeRatio = emissionState.time / system.duration;
+        const trailSettings = isTrailMode ? (system.rendererEmitterSettings as TrailSettings) : undefined;
+        const followLocalOrigin = Boolean(trailSettings?.followLocalOrigin);
+        const worldSpace = system.worldSpace;
+        const hierarchy = system.scalingMode === 'hierarchy';
+        const particles = system.particles;
+        if (system.maxParticles !== undefined) {
+            // Like Unity, a full system skips the particles it has no room for rather than queueing them.
+            count = Math.min(count, Math.max(0, system.maxParticles - system.particleNum));
+        }
+
+        for (let i = 0; i < count; i++) {
+            emissionState.burstParticleIndex = i;
+            system.particleNum++;
+            if (particles.length < system.particleNum) {
+                this.grow(isTrailMode);
+            }
+            const particle = particles[system.particleNum - 1];
+            particle.reset();
+            particle.serial = (particle.serial ?? 0) + 1;
+            particle.speedModifier = 1;
+            // Parent EmitSub can refill an onlyUsedByOther system after it had
+            // already finished empty; clear the flag so update does not treat it
+            // as done while it has live particles again.
+            system.finishedEventFired = false;
+            system.startColor.startGen(particle.memory);
+            system.startColor.genColor(particle.memory, particle.startColor, timeRatio);
+            particle.color.copy(particle.startColor);
+            system.startSpeed.startGen(particle.memory);
+            particle.startSpeed = system.startSpeed.genValue(particle.memory, timeRatio);
+            system.startLife.startGen(particle.memory);
+            particle.life = system.startLife.genValue(particle.memory, timeRatio);
+            particle.age = 0;
+            startSize.startGen(particle.memory);
+            if (startSizeIsVector3) {
+                (startSize as Vector3Generator).genValue(particle.memory, particle.startSize, timeRatio);
+            } else {
+                const size = (startSize as FunctionValueGenerator).genValue(particle.memory, timeRatio);
+                particle.startSize.set(size, size, size);
+            }
+            system.startTileIndex.startGen(particle.memory);
+            particle.uvTile = system.startTileIndex.genValue(particle.memory);
+            particle.size.copy(particle.startSize);
+
+            if (isSpriteMode) {
+                const sprite = particle as SpriteParticle;
+                startRotation.startGen(particle.memory);
+                if (isMeshMode) {
+                    if (!(sprite.rotation instanceof Quaternion)) {
+                        // Assigning a quaternion gives the particle a row in the
+                        // store's quaternion column; the value is overwritten below.
+                        sprite.rotation = IDENTITY_QUATERNION;
+                    }
+                    // A recycled particle can still carry the turn of whatever
+                    // it was last time; the renderer would draw a fraction of it
+                    // before any behavior has had a chance to say otherwise.
+                    if (sprite.angularVelocity instanceof Quaternion) {
+                        sprite.angularVelocity.set(0, 0, 0, 1);
+                    }
+                    if (startRotationIsRotation) {
+                        (startRotation as RotationGenerator).genValue(
+                            particle.memory,
+                            sprite.rotation as Quaternion,
+                            1,
+                            timeRatio
+                        );
+                    } else {
+                        (sprite.rotation as Quaternion).setFromAxisAngle(
+                            UP,
+                            (startRotation as FunctionValueGenerator).genValue(sprite.memory, timeRatio)
+                        );
+                    }
+                } else {
+                    if (startRotationIsRotation) {
+                        sprite.rotation = 0;
+                    } else {
+                        sprite.rotation = (startRotation as FunctionValueGenerator).genValue(sprite.memory, timeRatio);
+                    }
+                    // Set until a turning behavior says otherwise, so the
+                    // renderer never carries a recycled particle's old spin.
+                    sprite.angularVelocity = 0;
+                    const flip = system.flip;
+                    sprite.flip = flip === undefined ? 0 : (random() < flip.x ? 1 : 0) | (random() < flip.y ? 2 : 0);
+                }
+            } else if (trailSettings) {
+                const trail = particle as TrailParticle;
+                trailSettings.startLength.startGen(trail.memory);
+                trail.length = trailSettings.startLength.genValue(trail.memory, timeRatio);
+                trail.ensureHistoryCapacity(Math.max(1, Math.ceil(trail.length)));
+                trail.resetHistory();
+            }
+
+            system.emitterShape.initialize(particle, emissionState);
+
+            if (system.alignToDirection && isSpriteMode) {
+                alignParticleToDirection(particle as SpriteParticle, isMeshMode);
+            }
+
+            const parent = emissionState.particle;
+            const inherit = emissionState.inherit;
+            if (parent !== undefined && inherit !== undefined && inherit !== 0) {
+                inheritFromParent(particle, parent, inherit, isSpriteMode);
+            }
+
+            if (isTrailMode && followLocalOrigin) {
+                const trail = particle as TrailParticle;
+                if (!trail.localPosition) {
+                    trail.localPosition = new Vector3();
+                }
+                trail.localPosition.copy(trail.position);
+            }
+
+            if (worldSpace) {
+                particle.position.applyMatrix4(matrix);
+                particle.startSize.multiply(scale).abs();
+                particle.size.copy(particle.startSize);
+                if (hierarchy) {
+                    // Scaled per axis by the emitter's world scale, then turned: the speed scales with it.
+                    particle.velocity.multiply(system.hierarchyScale).applyQuaternion(tempQ);
+                } else {
+                    particle.velocity.multiply(scale).applyMatrix3(this.normalMatrix);
+                }
+                if (particle.rotation && particle.rotation instanceof Quaternion) {
+                    particle.rotation.multiplyQuaternions(tempQ, particle.rotation);
+                }
+            } else {
+                if (system.onlyUsedByOther) {
+                    particle.parentMatrix = matrix;
+                }
+            }
+
+            for (let j = 0; j < behaviorCount; j++) {
+                behaviors[j].initialize(particle, system);
+            }
+            // Every generator has claimed its slot by now; give the compiled
+            // behavior passes a column copy of the samples.
+            system.store.recordMemory((particle as StoreBackedParticle).storeIndex, particle.memory);
+        }
+    }
+}
+
+/** Turns a newborn so that it faces the way its shape sent it; see `ParticleSystem.alignToDirection`. */
+function alignParticleToDirection(sprite: SpriteParticle, isMeshMode: boolean): void {
+    const velocity = sprite.velocity;
+    const speedSq = velocity.x * velocity.x + velocity.y * velocity.y + velocity.z * velocity.z;
+    if (speedSq === 0) {
+        return;
+    }
+    if (isMeshMode) {
+        // +Z along the velocity, with the start rotation applied first.
+        const rotation = sprite.rotation as Quaternion;
+        tempV.copy(velocity).divideScalar(Math.sqrt(speedSq));
+        tempQ.setFromUnitVectors(UP, tempV);
+        rotation.multiplyQuaternions(tempQ, rotation);
+    } else {
+        // The quad's top (its +Y) toward the velocity in the emitter's XY plane.
+        if (velocity.x !== 0 || velocity.y !== 0) {
+            sprite.rotation = (sprite.rotation as number) + Math.atan2(-velocity.x, velocity.y);
+        }
+    }
+}
+
+/** Applies the parent particle's inherited properties to a sub emitted newborn; see `EmitSubParticleSystem.inherit`. */
+function inheritFromParent(particle: Particle, parent: Particle, inherit: number, isSpriteMode: boolean): void {
+    if (inherit & SubEmitterInheritMask.color) {
+        particle.startColor.multiply(parent.color);
+        particle.color.copy(particle.startColor);
+    }
+    if (inherit & SubEmitterInheritMask.size) {
+        particle.startSize.multiply(parent.size);
+        particle.size.copy(particle.startSize);
+    }
+    if (inherit & SubEmitterInheritMask.rotation && isSpriteMode) {
+        const sprite = particle as SpriteParticle;
+        const parentRotation = parent.rotation;
+        if (typeof sprite.rotation === 'number') {
+            if (typeof parentRotation === 'number') {
+                sprite.rotation += parentRotation;
+            }
+        } else if (parentRotation instanceof Quaternion) {
+            (sprite.rotation as Quaternion).multiplyQuaternions(parentRotation, sprite.rotation as Quaternion);
+        }
+    }
+    if (inherit & SubEmitterInheritMask.lifetime && parent.life > 0) {
+        particle.life *= Math.max(0, 1 - parent.age / parent.life);
+    }
+}