sparcoon 0.7.2 → 0.9.0

package/dist/effect/FXEffect.js

@@ -0,0 +1,454 @@
+import { Group, Mesh, Quaternion, Vector3, } from "three";
+import { FXEmitter } from "../emitter/FXEmitter.js";
+import { FXObjectMotionTracker } from "../emitter/FXObjectMotion.Internal.js";
+import { resolveGeometrySource } from "../instancedParticle/primitiveGeometry.js";
+import { FXMeshMaterial } from "../render/FXMeshMaterial.js";
+import { FXWorld } from "../world/FXWorld.js";
+import { frameOfTime, normalizeQuaternion, sampleTracks, sampleTransform, timeOfFrame, } from "./FXEffectSampling.Internal.js";
+const VECTOR_COMPONENTS = ["x", "y", "z", "w"];
+const PARAMETER_UNIFORM_PREFIX = "u_param_";
+const PARAMETER_BINDING_PREFIX = "b_param_";
+/**
+ * Writes `transform` onto `object`, skipping any channel in `liveChannels` - a "fake" channel the
+ * editor excludes from the exported keyframe data, left for the consumer to drive directly through
+ * the returned runtime object's own `position`/`quaternion`/`scale`.
+ */
+function applyTransform(object, transform, liveChannels) {
+    if (liveChannels?.includes("position") !== true) {
+        object.position.set(transform.position[0], transform.position[1], transform.position[2]);
+    }
+    if (liveChannels?.includes("rotation") !== true) {
+        const quaternion = normalizeQuaternion(transform.rotation);
+        object.quaternion.set(quaternion[0], quaternion[1], quaternion[2], quaternion[3]);
+    }
+    if (liveChannels?.includes("scale") !== true) {
+        object.scale.set(transform.scale[0], transform.scale[1], transform.scale[2]);
+    }
+}
+/** Materializes a possibly-readonly keyframe value into the mutable shape the value writers expect. */
+function materializeValue(value) {
+    return typeof value === "number" ? value : [...value];
+}
+// Duck-typed, not `instanceof`: the app's `three` and this package's peer-dep `three` can be two
+// separate module instances (e.g. hoisted differently across a workspace), which would make
+// `instanceof Texture`/`instanceof BufferGeometry` false for a perfectly good asset. Every `three`
+// object of these kinds carries this own-property flag regardless of which module instance built it.
+function isTexture(asset) {
+    return asset.isTexture === true;
+}
+function isBufferGeometry(asset) {
+    return asset.isBufferGeometry === true;
+}
+function texturesForSlots(slots, assets) {
+    const textures = {};
+    for (const name of slots) {
+        const asset = assets[name];
+        if (isTexture(asset)) {
+            textures[PARAMETER_UNIFORM_PREFIX + name] = asset;
+        }
+    }
+    return textures;
+}
+/** Every `BufferGeometry`-typed entry in `assets`, for {@link resolveGeometrySource}'s lookup - a
+ *  custom geometry slot is a single name, not a per-shader-uniform slot list like textures. */
+function geometriesFromAssets(assets) {
+    const geometries = {};
+    for (const name in assets) {
+        const asset = assets[name];
+        if (isBufferGeometry(asset)) {
+            geometries[name] = asset;
+        }
+    }
+    return geometries;
+}
+/** Writes one parameter's sampled value into whichever render uniform / behavior bindings it declares. */
+function writeParameterSlots(render, behavior, name, value, uniforms, bindings) {
+    const uniformKey = PARAMETER_UNIFORM_PREFIX + name;
+    if (uniformKey in render.uniforms) {
+        uniforms[uniformKey] = value;
+    }
+    const bindingKey = PARAMETER_BINDING_PREFIX + name;
+    if (bindingKey in behavior.bindings) {
+        bindings[bindingKey] = typeof value === "number" ? value : (value[0] ?? 0);
+        return;
+    }
+    const vector = typeof value === "number" ? [value] : value;
+    for (let i = 0; i < VECTOR_COMPONENTS.length; i += 1) {
+        const key = bindingKey + "_" + VECTOR_COMPONENTS[i];
+        if (key in behavior.bindings) {
+            bindings[key] = vector[i] ?? 0;
+        }
+    }
+}
+/** Restores one parameter's baked baseline (a parameter that stopped being driven this frame). */
+function writeParameterBaseline(render, behavior, name, uniforms, bindings) {
+    const uniformKey = PARAMETER_UNIFORM_PREFIX + name;
+    const uniform = render.uniforms[uniformKey];
+    // Types say `value` is defined once `"value" in uniform`, but guard the runtime
+    // `{ external, value: undefined }` case so we never bake an undefined baseline.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (uniform !== undefined && "value" in uniform && uniform.value !== undefined) {
+        uniforms[uniformKey] = uniform.value;
+    }
+    const bindingKey = PARAMETER_BINDING_PREFIX + name;
+    for (const key in behavior.bindings) {
+        if (key === bindingKey || key.startsWith(bindingKey + "_")) {
+            bindings[key] = behavior.bindings[key].value;
+        }
+    }
+}
+// A VFX mesh has no behavior, so its value drive addresses render uniforms only; this stand-in
+// makes the shared slot writer a no-op on the binding side.
+const NO_BEHAVIOR_BINDINGS = { bindings: {} };
+/**
+ * Runtime for a whole exported Sparcoon project: a `Group` that builds every emitter + VFX mesh
+ * from precompiled artifacts and drives the shared timeline. Add it to your scene, call `play()`,
+ * and `update(deltaSeconds)` each frame. Lit graphs read the scene's lights, so a lit effect needs
+ * a light probe + directional light in the host scene (studio lighting is not part of the export).
+ * An editor-emitted module supplies only the data (`FXEffectSpec` + a scene name) and a thin named
+ * subclass; this base class is identical for every export.
+ *
+ * The timeline drive mirrors the editor's own transport: burst/play events fire across the
+ * continuous swept interval, while value + transform tracks are frame-stepped onto the `fps` grid.
+ */
+export class FXEffect extends Group {
+    constructor(specification, assets, options = {}) {
+        super();
+        this.emitters = [];
+        this.meshMaterials = [];
+        this.meshes = [];
+        // World-space velocity/angular-velocity tracker per mesh, parallel to `meshes`.
+        this.meshMotionTrackers = [];
+        this.emitterDriven = [];
+        this.meshDriven = [];
+        // Name -> index, for the live-update API (getEmitter/getMesh/setEmitterParam/setMeshParam). A
+        // name the editor duplicated across entities resolves to the last one built (Map.set overwrites).
+        this.emitterIndexByName = new Map();
+        this.meshIndexByName = new Map();
+        this.time = 0;
+        this.lastTime = 0;
+        this.lastFrame = -1;
+        this.meshClock = 0;
+        this.playing = false;
+        this.disposed = false;
+        // Reused decompose scratch for the per-mesh motion diff (avoids a per-tick allocation); scale
+        // is discarded.
+        this.meshPositionScratch = new Vector3();
+        this.meshQuaternionScratch = new Quaternion();
+        this.meshScaleScratch = new Vector3();
+        this.specification = specification;
+        this.world = options.world ?? FXWorld.getDefault();
+        applyTransform(this, specification.transform);
+        const geometries = geometriesFromAssets(assets);
+        for (const emitterSpec of specification.emitters) {
+            const textures = texturesForSlots(emitterSpec.externalSlots, assets);
+            const emitter = FXEmitter.fromArtifacts(emitterSpec.render, emitterSpec.behavior, {
+                textures,
+                geometries,
+                expectedCapacity: emitterSpec.expectedCapacity,
+                castShadow: emitterSpec.castShadow ?? false,
+                receiveShadow: emitterSpec.receiveShadow ?? false,
+            }, this.world);
+            if (options.camera !== undefined && emitterSpec.sortInterval > 0) {
+                emitter.sortCamera = options.camera;
+                emitter.sortFraction = 1 / emitterSpec.sortInterval;
+            }
+            applyTransform(emitter, emitterSpec.transform);
+            this.add(emitter);
+            this.emitterIndexByName.set(emitterSpec.name, this.emitters.length);
+            this.emitters.push(emitter);
+            this.emitterDriven.push(new Set());
+        }
+        for (const meshSpec of specification.meshes) {
+            const textures = texturesForSlots(meshSpec.externalSlots, assets);
+            const material = new FXMeshMaterial(meshSpec.render, textures);
+            const mesh = new Mesh(resolveGeometrySource(meshSpec.geometry, geometries), material.buildThreeMaterial());
+            if (meshSpec.receiveShadow ?? false) {
+                mesh.receiveShadow = true;
+            }
+            if (meshSpec.castShadow ?? false) {
+                mesh.castShadow = true;
+                mesh.customDepthMaterial = material.buildThreeDepthMaterial();
+            }
+            applyTransform(mesh, meshSpec.transform);
+            this.add(mesh);
+            this.meshIndexByName.set(meshSpec.name, this.meshes.length);
+            this.meshes.push(mesh);
+            this.meshMaterials.push(material);
+            this.meshMotionTrackers.push(new FXObjectMotionTracker());
+            this.meshDriven.push(new Set());
+        }
+        // Pose + value drive at the timeline start, so the effect shows its authored frame-0 state
+        // before playback begins.
+        this.driveFrame(0);
+        // Self-subscribe: from here the world drives this effect every frame; dispose() unsubscribes.
+        this.world.registerEffect(this);
+    }
+    /** Restarts the timeline from the top: clears live particles and begins playback. */
+    play() {
+        if (this.disposed) {
+            return;
+        }
+        this.resetTransport();
+        this.playing = true;
+        this.driveFrame(0);
+    }
+    /** Halts playback and clears live particles, returning to the authored frame-0 state. */
+    stop() {
+        if (this.disposed) {
+            return;
+        }
+        this.playing = false;
+        this.resetTransport();
+        this.driveFrame(0);
+    }
+    /**
+     * @internal Advances this effect one frame; driven by {@link FXWorld.update}. Drives only the
+     * timeline and the meshes - the world ticks the shared particle pool separately, exactly once.
+     * A stopped effect stays frozen.
+     */
+    advanceFrame(deltaSeconds) {
+        if (this.disposed) {
+            return;
+        }
+        // Gate the simulation on playback, exactly like the editor's transport: stopped => 0, so live
+        // particles and mesh clocks hold instead of drifting while the effect is not playing.
+        const simulationDelta = this.playing ? deltaSeconds : 0;
+        if (this.playing) {
+            this.advance(deltaSeconds);
+        }
+        this.meshClock += simulationDelta;
+        for (let i = 0; i < this.meshes.length; i += 1) {
+            const mesh = this.meshes[i];
+            // World-space velocity/angular velocity since the previous frame, from the mesh's own
+            // matrixWorld (posed by `advance()` -> `driveFrame()` above, or by a host live-driving it
+            // directly through `getMesh()`) - never from PARTICLE_POSITION-style local state, since a
+            // mesh is a single non-instanced object with no such thing.
+            mesh.updateWorldMatrix(true, false);
+            mesh.matrixWorld.decompose(this.meshPositionScratch, this.meshQuaternionScratch, this.meshScaleScratch);
+            const motion = this.meshMotionTrackers[i].sample({
+                position: [
+                    this.meshPositionScratch.x,
+                    this.meshPositionScratch.y,
+                    this.meshPositionScratch.z,
+                ],
+                quaternion: [
+                    this.meshQuaternionScratch.x,
+                    this.meshQuaternionScratch.y,
+                    this.meshQuaternionScratch.z,
+                    this.meshQuaternionScratch.w,
+                ],
+            }, simulationDelta);
+            const material = this.meshMaterials[i];
+            material.setElapsedTime(this.meshClock);
+            material.setDeltaTime(simulationDelta);
+            material.setObjectVelocity(motion.velocity);
+            material.setObjectAngularVelocity(motion.angularVelocity);
+        }
+    }
+    /**
+     * The runtime emitter named `name` (its `FXEmitter`, an `Object3D`) - for a live channel the
+     * editor marked "fake" (see {@link FXEffectSpec}), pose it directly through its own
+     * `position`/`quaternion`/`scale`; `driveFrame` never touches that channel again. `undefined`
+     * for an unknown name or once disposed (matching {@link dispose}'s emptied index).
+     */
+    getEmitter(name) {
+        if (this.disposed) {
+            return undefined;
+        }
+        const index = this.emitterIndexByName.get(name);
+        return index === undefined ? undefined : this.emitters[index];
+    }
+    /** The runtime mesh named `name` (a `three.Mesh`), for the same live-channel posing as {@link getEmitter}. */
+    getMesh(name) {
+        if (this.disposed) {
+            return undefined;
+        }
+        const index = this.meshIndexByName.get(name);
+        return index === undefined ? undefined : this.meshes[index];
+    }
+    /**
+     * Pushes `value` into emitter `name`'s Timeline Value `parameter` (a uniform/binding slot the
+     * editor marked "fake", so it is never sampled from baked keyframes). No-op for an unknown
+     * emitter, or once disposed - the underlying slot writer already no-ops for an unknown parameter.
+     */
+    setEmitterParam(name, parameter, value) {
+        if (this.disposed) {
+            return;
+        }
+        const index = this.emitterIndexByName.get(name);
+        if (index === undefined) {
+            return;
+        }
+        const specification = this.specification.emitters[index];
+        const uniforms = {};
+        const bindings = {};
+        writeParameterSlots(specification.render, specification.behavior, parameter, materializeValue(value), uniforms, bindings);
+        if (Object.keys(uniforms).length > 0 || Object.keys(bindings).length > 0) {
+            this.emitters[index].applyValues({ uniforms, bindings });
+        }
+    }
+    /** Pushes `value` into mesh `name`'s Timeline Value `parameter`. See {@link setEmitterParam}. */
+    setMeshParam(name, parameter, value) {
+        if (this.disposed) {
+            return;
+        }
+        const index = this.meshIndexByName.get(name);
+        if (index === undefined) {
+            return;
+        }
+        const specification = this.specification.meshes[index];
+        const uniforms = {};
+        const bindings = {};
+        writeParameterSlots(specification.render, NO_BEHAVIOR_BINDINGS, parameter, materializeValue(value), uniforms, bindings);
+        if (Object.keys(uniforms).length > 0) {
+            this.meshMaterials[index].applyUniformValues(uniforms);
+        }
+    }
+    /**
+     * Unsubscribes from its world, destroys every emitter, and disposes mesh resources; the group
+     * empties itself from its parent. Idempotent.
+     */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.playing = false;
+        this.world.unregisterEffect(this);
+        for (const emitter of this.emitters) {
+            emitter.destroy();
+        }
+        this.emitters.length = 0;
+        for (let i = 0; i < this.meshes.length; i += 1) {
+            const mesh = this.meshes[i];
+            // A "custom" geometry is the app's own `assets` object - only a primitive built
+            // by `resolveGeometrySource` is ours to dispose.
+            if (this.specification.meshes[i].geometry.type === "primitive") {
+                mesh.geometry.dispose();
+            }
+            mesh.material.dispose();
+        }
+        this.meshes.length = 0;
+        this.meshMaterials.length = 0;
+        this.removeFromParent();
+    }
+    resetTransport() {
+        this.time = 0;
+        this.lastTime = 0;
+        this.lastFrame = -1;
+        // meshClock is deliberately NOT reset: a mesh's time-driven shader runs on monotonic sim time,
+        // decoupled from the timeline playhead, so a replay does not snap its phase back. The motion
+        // trackers ARE reset - unlike meshClock's phase, a restarted effect should not report a
+        // teleport-spike velocity from wherever a mesh was last posed.
+        for (const emitter of this.emitters) {
+            emitter.stop();
+            emitter.reset();
+        }
+        for (const tracker of this.meshMotionTrackers) {
+            tracker.reset();
+        }
+    }
+    advance(deltaSeconds) {
+        const duration = this.specification.duration;
+        let now = this.time + deltaSeconds;
+        if (duration > 0 && now >= duration) {
+            // Loop wrap: finish this lap's tail, reset, then replay from the remainder.
+            this.fire(this.lastTime, duration);
+            for (const emitter of this.emitters) {
+                emitter.stop();
+                emitter.reset();
+            }
+            now = now % duration;
+            this.lastTime = 0;
+            this.lastFrame = -1;
+        }
+        this.fire(this.lastTime, now);
+        this.lastTime = now;
+        this.time = now;
+        const frame = frameOfTime(now, this.specification.fps);
+        if (frame !== this.lastFrame) {
+            this.lastFrame = frame;
+            this.driveFrame(timeOfFrame(frame, this.specification.fps));
+        }
+    }
+    /** Fires burst/play events whose time lies in `[from, to)` on their owning emitter. */
+    fire(from, to) {
+        if (to <= from) {
+            return;
+        }
+        for (let i = 0; i < this.specification.emitters.length; i += 1) {
+            const emitter = this.emitters[i];
+            for (const event of this.specification.emitters[i].events) {
+                if (event.time < from || event.time >= to) {
+                    continue;
+                }
+                // Guard degenerate authored counts/rates: FXEmitter asserts a positive count/rate and would
+                // throw straight out of the host's frame loop, so a zero-count burst is a no-op here.
+                if (event.kind === "burst") {
+                    if (event.count > 0) {
+                        emitter.burst(event.count);
+                    }
+                }
+                else if (event.rate > 0) {
+                    emitter.play(event.rate, event.duration > 0 ? { duration: event.duration } : {});
+                }
+            }
+        }
+    }
+    /**
+     * Poses every entity and scrubs its sampled parameter values into the runtime at time `time`. The
+     * root itself is never re-posed here (see {@link FXEffectSpec.transformTracks}) - only
+     * emitters/meshes, and only their non-live channels/parameters.
+     */
+    driveFrame(time) {
+        for (let i = 0; i < this.specification.emitters.length; i += 1) {
+            const emitterSpec = this.specification.emitters[i];
+            applyTransform(this.emitters[i], sampleTransform(emitterSpec.transform, emitterSpec.transformTracks, time), emitterSpec.liveChannels);
+            this.driveEmitterValues(i, sampleTracks(emitterSpec.tracks, time));
+        }
+        for (let i = 0; i < this.specification.meshes.length; i += 1) {
+            const meshSpec = this.specification.meshes[i];
+            applyTransform(this.meshes[i], sampleTransform(meshSpec.transform, meshSpec.transformTracks, time), meshSpec.liveChannels);
+            this.driveMeshValues(i, sampleTracks(meshSpec.tracks, time));
+        }
+    }
+    driveEmitterValues(index, values) {
+        const specification = this.specification.emitters[index];
+        const driven = this.emitterDriven[index];
+        const uniforms = {};
+        const bindings = {};
+        for (const [name, value] of values) {
+            writeParameterSlots(specification.render, specification.behavior, name, value, uniforms, bindings);
+            driven.add(name);
+        }
+        for (const name of [...driven]) {
+            if (!values.has(name)) {
+                writeParameterBaseline(specification.render, specification.behavior, name, uniforms, bindings);
+                driven.delete(name);
+            }
+        }
+        if (Object.keys(uniforms).length > 0 || Object.keys(bindings).length > 0) {
+            this.emitters[index].applyValues({ uniforms, bindings });
+        }
+    }
+    driveMeshValues(index, values) {
+        const specification = this.specification.meshes[index];
+        const driven = this.meshDriven[index];
+        const uniforms = {};
+        const bindings = {};
+        for (const [name, value] of values) {
+            writeParameterSlots(specification.render, NO_BEHAVIOR_BINDINGS, name, value, uniforms, bindings);
+            driven.add(name);
+        }
+        for (const name of [...driven]) {
+            if (!values.has(name)) {
+                writeParameterBaseline(specification.render, NO_BEHAVIOR_BINDINGS, name, uniforms, bindings);
+                driven.delete(name);
+            }
+        }
+        if (Object.keys(uniforms).length > 0) {
+            this.meshMaterials[index].applyUniformValues(uniforms);
+        }
+    }
+}

package/dist/effect/FXEffectSampling.Internal.d.ts

@@ -0,0 +1,24 @@
+import type { FXKeyframe, FXQuat, FXTrack, FXTransform, FXTransformTrack, FXVec3 } from "./FXEffectSpec.js";
+export declare function frameOfTime(time: number, fps: number): number;
+export declare function timeOfFrame(frame: number, fps: number): number;
+/** The bounding keys straddling `time` and the fraction between (held at the ends). */
+export declare function keyframeSegment(keys: readonly FXKeyframe[], time: number): {
+    readonly a: FXKeyframe;
+    readonly b: FXKeyframe;
+    readonly u: number;
+} | undefined;
+export declare function sampleTrack(track: FXTrack, time: number): number | number[] | undefined;
+export declare function sampleTracks(tracks: readonly FXTrack[], time: number): Map<string, number | number[]>;
+/** A keyframe value read as a vec3 (missing components default to 0). */
+export declare function vectorFromValue(value: number | readonly number[]): FXVec3;
+/** A keyframe value read as a quaternion, falling back to identity for a malformed value. */
+export declare function quaternionFromValue(value: number | readonly number[]): FXQuat;
+/** Renormalizes a quaternion (a componentwise-lerped or hand-edited one drifts off the unit sphere). */
+export declare function normalizeQuaternion(quaternion: FXQuat): FXQuat;
+/** Spherical-linear blend of two quaternions at `u in [0, 1]` (shortest arc). */
+export declare function slerpQuaternion(a: FXQuat, b: FXQuat, u: number): FXQuat;
+/**
+ * The effective transform at time `time`: each channel with keyframes is sampled from its track, and
+ * any channel without keys holds the entity's authored `base` value.
+ */
+export declare function sampleTransform(base: FXTransform, tracks: readonly FXTransformTrack[], time: number): FXTransform;

package/dist/effect/FXEffectSampling.Internal.js

@@ -0,0 +1,165 @@
+/**
+ * Pure keyframe/transform sampling math for {@link FXEffect}'s timeline drive: hold-before-first,
+ * hold-after-last, linear interpolation between (slerp for rotation). No side effects, no `three`
+ * dependency. Every export here also backs the editor's own track/transform sampling: the editor
+ * used to hand-duplicate this exact math under different type names, and now imports it from here
+ * (this stays an `.Internal.ts` module, outside the public `sparcoon` package surface) so the two
+ * can never drift apart.
+ */
+const IDENTITY_QUAT = [0, 0, 0, 1];
+export function frameOfTime(time, fps) {
+    return fps > 0 ? Math.round(time * fps) : 0;
+}
+export function timeOfFrame(frame, fps) {
+    return fps > 0 ? frame / fps : 0;
+}
+/** The bounding keys straddling `time` and the fraction between (held at the ends). */
+export function keyframeSegment(keys, time) {
+    if (keys.length === 0) {
+        return undefined;
+    }
+    const first = keys[0];
+    if (time <= first.time || keys.length === 1) {
+        return { a: first, b: first, u: 0 };
+    }
+    const last = keys[keys.length - 1];
+    if (time >= last.time) {
+        return { a: last, b: last, u: 0 };
+    }
+    let a = first;
+    let b = last;
+    for (let i = 1; i < keys.length; i += 1) {
+        const key = keys[i];
+        if (key.time >= time) {
+            a = keys[i - 1];
+            b = key;
+            break;
+        }
+    }
+    const span = b.time - a.time;
+    return { a, b, u: span > 0 ? (time - a.time) / span : 0 };
+}
+function lerpValue(a, b, u) {
+    if (typeof a === "number" && typeof b === "number") {
+        return a + (b - a) * u;
+    }
+    const aArray = typeof a === "number" ? [a] : a;
+    const bArray = typeof b === "number" ? [b] : b;
+    const width = Math.min(aArray.length, bArray.length);
+    const output = [];
+    for (let i = 0; i < width; i += 1) {
+        output.push(aArray[i] + (bArray[i] - aArray[i]) * u);
+    }
+    return output;
+}
+export function sampleTrack(track, time) {
+    const segment = keyframeSegment(track.keys, time);
+    if (segment === undefined) {
+        return undefined;
+    }
+    return lerpValue(segment.a.value, segment.b.value, segment.u);
+}
+export function sampleTracks(tracks, time) {
+    const values = new Map();
+    for (const track of tracks) {
+        const value = sampleTrack(track, time);
+        if (value !== undefined) {
+            values.set(track.name, value);
+        }
+    }
+    return values;
+}
+/** A keyframe value read as a vec3 (missing components default to 0). */
+export function vectorFromValue(value) {
+    if (typeof value === "number") {
+        return [value, value, value];
+    }
+    return [value[0] ?? 0, value[1] ?? 0, value[2] ?? 0];
+}
+/** A keyframe value read as a quaternion, falling back to identity for a malformed value. */
+export function quaternionFromValue(value) {
+    if (typeof value === "number" || value.length < 4) {
+        return IDENTITY_QUAT;
+    }
+    return [value[0] ?? 0, value[1] ?? 0, value[2] ?? 0, value[3] ?? 1];
+}
+/** Renormalizes a quaternion (a componentwise-lerped or hand-edited one drifts off the unit sphere). */
+export function normalizeQuaternion(quaternion) {
+    const length = Math.hypot(quaternion[0], quaternion[1], quaternion[2], quaternion[3]);
+    if (length === 0) {
+        return IDENTITY_QUAT;
+    }
+    return [
+        quaternion[0] / length,
+        quaternion[1] / length,
+        quaternion[2] / length,
+        quaternion[3] / length,
+    ];
+}
+/** Spherical-linear blend of two quaternions at `u in [0, 1]` (shortest arc). */
+export function slerpQuaternion(a, b, u) {
+    let ax = a[0];
+    let ay = a[1];
+    let az = a[2];
+    let aw = a[3];
+    const bx = b[0];
+    const by = b[1];
+    const bz = b[2];
+    const bw = b[3];
+    let dot = ax * bx + ay * by + az * bz + aw * bw;
+    if (dot < 0) {
+        ax = -ax;
+        ay = -ay;
+        az = -az;
+        aw = -aw;
+        dot = -dot;
+    }
+    if (dot > 0.9995) {
+        return normalizeQuaternion([
+            ax + (bx - ax) * u,
+            ay + (by - ay) * u,
+            az + (bz - az) * u,
+            aw + (bw - aw) * u,
+        ]);
+    }
+    const theta0 = Math.acos(dot);
+    const theta = theta0 * u;
+    const sinTheta0 = Math.sin(theta0);
+    const s0 = Math.cos(theta) - (dot * Math.sin(theta)) / sinTheta0;
+    const s1 = Math.sin(theta) / sinTheta0;
+    return [ax * s0 + bx * s1, ay * s0 + by * s1, az * s0 + bz * s1, aw * s0 + bw * s1];
+}
+function sampleVectorChannel(track, time) {
+    const segment = track === undefined ? undefined : keyframeSegment(track.keys, time);
+    if (segment === undefined) {
+        return undefined;
+    }
+    const a = vectorFromValue(segment.a.value);
+    const b = vectorFromValue(segment.b.value);
+    return [
+        a[0] + (b[0] - a[0]) * segment.u,
+        a[1] + (b[1] - a[1]) * segment.u,
+        a[2] + (b[2] - a[2]) * segment.u,
+    ];
+}
+function sampleQuaternionChannel(track, time) {
+    const segment = track === undefined ? undefined : keyframeSegment(track.keys, time);
+    if (segment === undefined) {
+        return undefined;
+    }
+    return slerpQuaternion(quaternionFromValue(segment.a.value), quaternionFromValue(segment.b.value), segment.u);
+}
+function transformChannel(tracks, name) {
+    return tracks.find((track) => track.channel === name);
+}
+/**
+ * The effective transform at time `time`: each channel with keyframes is sampled from its track, and
+ * any channel without keys holds the entity's authored `base` value.
+ */
+export function sampleTransform(base, tracks, time) {
+    return {
+        position: sampleVectorChannel(transformChannel(tracks, "position"), time) ?? base.position,
+        rotation: sampleQuaternionChannel(transformChannel(tracks, "rotation"), time) ?? base.rotation,
+        scale: sampleVectorChannel(transformChannel(tracks, "scale"), time) ?? base.scale,
+    };
+}