babylon.quarks 0.26.0 → 0.27.0

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

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,111 @@
+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);
+}
+
+/**
+ * Typed arrays from a geometry entry of an effect document: quarks' own `{positions, indices, uvs,
+ * uvs2, normals}`, or a three.js `BufferGeometry` JSON. Anything else gives the default quad.
+ */
+export function resolveGeometryData(entry: any): {
+    positions: Float32Array;
+    indices: Uint32Array | Uint16Array;
+    uvs?: Float32Array;
+    uvs2?: Float32Array;
+    normals?: Float32Array;
+} {
+    if (entry?.positions) {
+        const positions = entry.positions instanceof Float32Array ? entry.positions : new Float32Array(entry.positions);
+        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: entry.uvs ? (entry.uvs instanceof Float32Array ? entry.uvs : new Float32Array(entry.uvs)) : undefined,
+            uvs2: entry.uvs2
+                ? entry.uvs2 instanceof Float32Array
+                    ? entry.uvs2
+                    : new Float32Array(entry.uvs2)
+                : undefined,
+            normals: entry.normals
+                ? entry.normals instanceof Float32Array
+                    ? entry.normals
+                    : new Float32Array(entry.normals)
+                : undefined,
+        };
+    }
+
+    const data = entry?.data ?? entry;
+    if (data?.attributes?.position?.array) {
+        const positions = new Float32Array(data.attributes.position.array);
+        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: 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,
+        };
+    }
+
+    return {
+        positions: DEFAULT_POSITIONS,
+        indices: DEFAULT_INDICES,
+        uvs: DEFAULT_UVS,
+    };
+}