@flighthq/animation 0.2.1-next.640.ec2ea9a → 0.2.1-next.652.c550eaa

package/dist/animationCrossfade.d.ts

@@ -0,0 +1,6 @@
+import type { AnimationChannel, AnimationCrossfade, AnimationCrossfadeOptions, AnimationPlayer } from '@flighthq/types';
+export declare function advanceAnimationCrossfade(state: AnimationCrossfade, dt: number): void;
+export declare function createAnimationCrossfade(from: AnimationPlayer, to: AnimationPlayer, duration: number, opts?: Readonly<AnimationCrossfadeOptions>): AnimationCrossfade;
+export declare function isAnimationCrossfadeComplete(state: Readonly<AnimationCrossfade>): boolean;
+export declare function sampleAnimationCrossfade(out: number[] | Float32Array, state: Readonly<AnimationCrossfade>, visit: (sampled: Readonly<number[] | Float32Array>, channel: Readonly<AnimationChannel>, index: number) => void): void;
+//# sourceMappingURL=animationCrossfade.d.ts.map

package/dist/animationCrossfade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animationCrossfade.d.ts","sourceRoot":"","sources":["../src/animationCrossfade.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAElB,yBAAyB,EACzB,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAQzB,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAKrF;AAKD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,eAAe,EACrB,EAAE,EAAE,eAAe,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,QAAQ,CAAC,yBAAyB,CAAC,GACzC,kBAAkB,CAiBpB;AAKD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAEzF;AAMD,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EAAE,GAAG,YAAY,EAC5B,KAAK,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACnC,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAC9G,IAAI,CAkBN"}

package/dist/animationCrossfade.js

@@ -0,0 +1,120 @@
+import { createEntity } from '@flighthq/entity';
+import { blendAnimationSamples } from './animationBlend';
+import { advanceAnimationPlayer } from './animationPlayer';
+import { sampleAnimationTrack } from './animationTrack';
+// Advances both source players by the same delta and updates the transition weight. Nothing advances
+// implicitly; callers drive this alongside their other animation state.
+export function advanceAnimationCrossfade(state, dt) {
+    advanceAnimationPlayer(state.from, dt);
+    advanceAnimationPlayer(state.to, dt);
+    state.elapsed += dt;
+    state.weight = state.curve(getLinearAnimationCrossfadeWeight(state.elapsed, state.duration));
+}
+// Allocates a two-player transition, target-correspondence layout, and reusable sample scratch.
+// Channels correspond when their opaque targetRef values have identity equality. A target present in
+// only one clip remains in the layout as a pass-through channel.
+export function createAnimationCrossfade(from, to, duration, opts) {
+    const resolvedDuration = Math.max(0, duration);
+    const curve = opts?.curve ?? linearAnimationCrossfadeCurve;
+    const channels = createAnimationCrossfadeChannels(from, to);
+    let sampleWidth = 0;
+    for (const entry of channels)
+        sampleWidth = Math.max(sampleWidth, entry.channel.track.components);
+    return createEntity({
+        channels,
+        curve,
+        duration: resolvedDuration,
+        elapsed: 0,
+        from,
+        fromSample: new Float32Array(sampleWidth),
+        to,
+        toSample: new Float32Array(sampleWidth),
+        weight: curve(getLinearAnimationCrossfadeWeight(0, resolvedDuration)),
+    });
+}
+// Reports when elapsed transition time has reached duration. Completion deliberately ignores the
+// curved weight because back/elastic easing may overshoot 1 before the lifecycle duration ends. The
+// caller owns retirement/removal of a completed transition; the controller has no hidden scheduler.
+export function isAnimationCrossfadeComplete(state) {
+    return state.duration <= 0 || state.elapsed >= state.duration;
+}
+// Samples every target correspondence using the caller-supplied per-channel scratch and visitor,
+// mirroring sampleAnimationClip. Matched targets blend by the destination weight; one-sided targets
+// pass their existing clip value through unchanged. The visitor must consume `out` before returning
+// because the same buffer is overwritten for the next channel. Allocation-free after construction.
+export function sampleAnimationCrossfade(out, state, visit) {
+    const fromChannels = state.from.clip.channels;
+    const toChannels = state.to.clip.channels;
+    for (let index = 0; index < state.channels.length; index++) {
+        const entry = state.channels[index];
+        if (entry.fromIndex === null) {
+            sampleAnimationTrack(out, toChannels[entry.toIndex].track, state.to.time);
+        }
+        else if (entry.toIndex === null) {
+            sampleAnimationTrack(out, fromChannels[entry.fromIndex].track, state.from.time);
+        }
+        else {
+            const fromTrack = fromChannels[entry.fromIndex].track;
+            const toTrack = toChannels[entry.toIndex].track;
+            sampleAnimationTrack(state.fromSample, fromTrack, state.from.time);
+            sampleAnimationTrack(state.toSample, toTrack, state.to.time);
+            blendAnimationSamples(out, state.fromSample, state.toSample, state.weight, fromTrack.quaternion);
+        }
+        visit(out, entry.channel, index);
+    }
+}
+function createAnimationCrossfadeChannels(from, to) {
+    const fromChannels = from.clip.channels;
+    const toChannels = to.clip.channels;
+    assertUniqueAnimationCrossfadeTargets(fromChannels, 'source');
+    assertUniqueAnimationCrossfadeTargets(toChannels, 'destination');
+    const toByTarget = new Map();
+    for (let index = 0; index < toChannels.length; index++) {
+        if (!toByTarget.has(toChannels[index].targetRef))
+            toByTarget.set(toChannels[index].targetRef, index);
+    }
+    const channels = [];
+    const matchedTo = new Set();
+    for (let fromIndex = 0; fromIndex < fromChannels.length; fromIndex++) {
+        const fromChannel = fromChannels[fromIndex];
+        const toIndex = toByTarget.get(fromChannel.targetRef);
+        if (toIndex === undefined) {
+            channels.push({ channel: fromChannel, fromIndex, toIndex: null });
+            continue;
+        }
+        const toChannel = toChannels[toIndex];
+        if (fromChannel.track.components !== toChannel.track.components) {
+            throw new RangeError(`AnimationCrossfade target has different component widths (${fromChannel.track.components} and ${toChannel.track.components}).`);
+        }
+        if (fromChannel.track.quaternion !== toChannel.track.quaternion) {
+            throw new TypeError('AnimationCrossfade target has incompatible quaternion flags.');
+        }
+        channels.push({ channel: toChannel, fromIndex, toIndex });
+        matchedTo.add(toIndex);
+    }
+    for (let toIndex = 0; toIndex < toChannels.length; toIndex++) {
+        if (!matchedTo.has(toIndex)) {
+            channels.push({ channel: toChannels[toIndex], fromIndex: null, toIndex });
+        }
+    }
+    return channels;
+}
+function assertUniqueAnimationCrossfadeTargets(channels, clipLabel) {
+    const targets = new Set();
+    for (const channel of channels) {
+        if (targets.has(channel.targetRef)) {
+            throw new TypeError(`AnimationCrossfade ${clipLabel} clip contains a duplicate targetRef.`);
+        }
+        targets.add(channel.targetRef);
+    }
+}
+function getLinearAnimationCrossfadeWeight(elapsed, duration) {
+    if (duration <= 0)
+        return 1;
+    const normalized = elapsed / duration;
+    return normalized < 0 ? 0 : normalized > 1 ? 1 : normalized;
+}
+function linearAnimationCrossfadeCurve(t) {
+    return t;
+}
+//# sourceMappingURL=animationCrossfade.js.map

package/dist/animationCrossfade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animationCrossfade.js","sourceRoot":"","sources":["../src/animationCrossfade.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './animationClip';
 export * from './animationBlend';
+export * from './animationCrossfade';
 export * from './animationPlayer';
 export * from './animationTrack';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './animationClip';
 export * from './animationBlend';
+export * from './animationCrossfade';
 export * from './animationPlayer';
 export * from './animationTrack';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/animation",
-  "version": "0.2.1-next.640.ec2ea9a",
+  "version": "0.2.1-next.652.c550eaa",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -32,9 +32,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/entity": "0.2.1-next.640.ec2ea9a",
-    "@flighthq/signals": "0.2.1-next.640.ec2ea9a",
-    "@flighthq/types": "0.2.1-next.640.ec2ea9a"
+    "@flighthq/entity": "0.2.1-next.652.c550eaa",
+    "@flighthq/signals": "0.2.1-next.652.c550eaa",
+    "@flighthq/types": "0.2.1-next.652.c550eaa"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/animationBlend.test.ts

@@ -46,6 +46,16 @@ describe('addAnimationSample', () => {
 });
 
 describe('blendAnimationSamples', () => {
+  it('supports output aliasing either input', () => {
+    const a = [0, 10];
+    blendAnimationSamples(a, a, [10, 20], 0.25);
+    expect(a).toEqual([2.5, 12.5]);
+
+    const b = [10, 20];
+    blendAnimationSamples(b, [0, 10], b, 0.25);
+    expect(b).toEqual([2.5, 12.5]);
+  });
+
   it('linearly blends components and clamps alpha', () => {
     const out = [0, 0];
     blendAnimationSamples(out, [0, 10], [10, 20], 0.25);

package/src/animationCrossfade.test.ts

@@ -0,0 +1,223 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { createAnimationChannel, createAnimationClip } from './animationClip';
+import {
+  advanceAnimationCrossfade,
+  createAnimationCrossfade,
+  isAnimationCrossfadeComplete,
+  sampleAnimationCrossfade,
+} from './animationCrossfade';
+import { createAnimationPlayer } from './animationPlayer';
+import { createAnimationTrack } from './animationTrack';
+
+function player(targetRef: unknown, values: number[], opts?: Readonly<{ components?: number; quaternion?: boolean }>) {
+  const track = createAnimationTrack({
+    components: opts?.components,
+    quaternion: opts?.quaternion,
+    times: [0, 1],
+    values,
+  });
+  return createAnimationPlayer(createAnimationClip([createAnimationChannel(track, targetRef)]));
+}
+
+describe('advanceAnimationCrossfade', () => {
+  it('advances both players by the same delta and updates linear weight', () => {
+    const target = {};
+    const from = player(target, [0, 10]);
+    const to = player(target, [20, 30]);
+    const state = createAnimationCrossfade(from, to, 2);
+    advanceAnimationCrossfade(state, 0.5);
+    expect(from.time).toBe(0.5);
+    expect(to.time).toBe(0.5);
+    expect(state.elapsed).toBe(0.5);
+    expect(state.weight).toBe(0.25);
+  });
+
+  it('applies a caller-provided curve to clamped normalized time', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 1]), player(target, [1, 2]), 1, {
+      curve: (t) => t * t,
+    });
+    advanceAnimationCrossfade(state, 0.5);
+    expect(state.weight).toBe(0.25);
+    advanceAnimationCrossfade(state, 2);
+    expect(state.weight).toBe(1);
+  });
+});
+
+describe('createAnimationCrossfade', () => {
+  it('creates an Entity with linear weight and reusable scratch by default', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 1]), player(target, [1, 2]), 2);
+    expect(EntityRuntimeKey in state).toBe(true);
+    expect(state.elapsed).toBe(0);
+    expect(state.weight).toBe(0);
+    expect(state.fromSample).toBeInstanceOf(Float32Array);
+    expect(state.toSample).toBeInstanceOf(Float32Array);
+  });
+
+  it('completes a zero-duration transition immediately', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 1]), player(target, [1, 2]), 0);
+    expect(state.weight).toBe(1);
+    expect(isAnimationCrossfadeComplete(state)).toBe(true);
+  });
+
+  it('matches reordered channels by target and retains one-sided channels', () => {
+    const shared = {};
+    const fromOnly = {};
+    const toOnly = {};
+    const from = createAnimationPlayer(
+      createAnimationClip([
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [1] }), shared),
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [2] }), fromOnly),
+      ]),
+    );
+    const to = createAnimationPlayer(
+      createAnimationClip([
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [3] }), toOnly),
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [4] }), shared),
+      ]),
+    );
+    const state = createAnimationCrossfade(from, to, 1);
+    expect(state.channels).toEqual([
+      { channel: to.clip.channels[1], fromIndex: 0, toIndex: 1 },
+      { channel: from.clip.channels[1], fromIndex: 1, toIndex: null },
+      { channel: to.clip.channels[0], fromIndex: null, toIndex: 0 },
+    ]);
+  });
+
+  it('rejects incompatible tracks that claim the same target', () => {
+    const target = {};
+    const scalar = player(target, [0, 1]);
+    const vector = player(target, [0, 0, 1, 1], { components: 2 });
+    expect(() => createAnimationCrossfade(scalar, vector, 1)).toThrow(/different component widths/);
+
+    const quaternion = player(target, [0, 0, 0, 1, 0, 0, 0, 1], {
+      components: 4,
+      quaternion: true,
+    });
+    const vector4 = player(target, [0, 0, 0, 1, 0, 0, 0, 1], { components: 4 });
+    expect(() => createAnimationCrossfade(quaternion, vector4, 1)).toThrow(/incompatible quaternion flags/);
+  });
+
+  it('rejects duplicate target references in either clip', () => {
+    const duplicate = {};
+    const unique = {};
+    const track = createAnimationTrack({ times: [0], values: [1] });
+    const duplicateClip = createAnimationClip([
+      createAnimationChannel(track, duplicate),
+      createAnimationChannel(track, duplicate),
+    ]);
+    const uniqueClip = createAnimationClip([
+      createAnimationChannel(track, duplicate),
+      createAnimationChannel(track, unique),
+    ]);
+    expect(() =>
+      createAnimationCrossfade(createAnimationPlayer(duplicateClip), createAnimationPlayer(uniqueClip), 1),
+    ).toThrow(/source clip contains a duplicate targetRef/);
+    expect(() =>
+      createAnimationCrossfade(createAnimationPlayer(uniqueClip), createAnimationPlayer(duplicateClip), 1),
+    ).toThrow(/destination clip contains a duplicate targetRef/);
+  });
+});
+
+describe('isAnimationCrossfadeComplete', () => {
+  it('uses elapsed duration as the retirement condition', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 1]), player(target, [1, 2]), 2);
+    expect(isAnimationCrossfadeComplete(state)).toBe(false);
+    advanceAnimationCrossfade(state, 2);
+    expect(isAnimationCrossfadeComplete(state)).toBe(true);
+  });
+
+  it('does not retire early when an easing curve overshoots 1', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 1]), player(target, [1, 2]), 1, {
+      curve: (t) => 1 + t,
+    });
+    advanceAnimationCrossfade(state, 0.7);
+    expect(state.weight).toBeGreaterThan(1);
+    expect(isAnimationCrossfadeComplete(state)).toBe(false);
+    advanceAnimationCrossfade(state, 0.31);
+    expect(isAnimationCrossfadeComplete(state)).toBe(true);
+  });
+});
+
+describe('sampleAnimationCrossfade', () => {
+  it('samples both playheads and blends through a distinct output buffer', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 10]), player(target, [20, 40]), 2);
+    advanceAnimationCrossfade(state, 0.5);
+    const out = [0];
+    const seen: number[] = [];
+    sampleAnimationCrossfade(out, state, (sampled) => seen.push(sampled[0]));
+    expect(seen).toEqual([11.25]);
+  });
+
+  it('supports output aliasing either internal blend input', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 10]), player(target, [20, 40]), 2);
+    advanceAnimationCrossfade(state, 0.5);
+    const seen: number[] = [];
+    sampleAnimationCrossfade(state.fromSample, state, (sampled) => seen.push(sampled[0]));
+    expect(seen).toEqual([11.25]);
+    sampleAnimationCrossfade(state.toSample, state, (sampled) => seen.push(sampled[0]));
+    expect(seen).toEqual([11.25, 11.25]);
+  });
+
+  it('visits matched and one-sided channels in stable target order', () => {
+    const shared = {};
+    const fromOnly = {};
+    const toOnly = {};
+    const from = createAnimationPlayer(
+      createAnimationClip([
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [2] }), shared),
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [7] }), fromOnly),
+      ]),
+    );
+    const to = createAnimationPlayer(
+      createAnimationClip([
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [9] }), toOnly),
+        createAnimationChannel(createAnimationTrack({ times: [0], values: [6] }), shared),
+      ]),
+    );
+    const state = createAnimationCrossfade(from, to, 2);
+    advanceAnimationCrossfade(state, 1);
+    const seen: Array<{ index: number; target: unknown; value: number }> = [];
+    sampleAnimationCrossfade([0], state, (sampled, channel, index) => {
+      seen.push({ index, target: channel.targetRef, value: sampled[0] });
+    });
+    expect(seen).toEqual([
+      { index: 0, target: shared, value: 4 },
+      { index: 1, target: fromOnly, value: 7 },
+      { index: 2, target: toOnly, value: 9 },
+    ]);
+  });
+
+  it('preserves alpha endpoints and reuses scratch buffers', () => {
+    const target = {};
+    const state = createAnimationCrossfade(player(target, [0, 10]), player(target, [20, 40]), 1);
+    const fromSample = state.fromSample;
+    const toSample = state.toSample;
+    const values: number[] = [];
+    sampleAnimationCrossfade([0], state, (sampled) => values.push(sampled[0]));
+    advanceAnimationCrossfade(state, 2);
+    sampleAnimationCrossfade([0], state, (sampled) => values.push(sampled[0]));
+    expect(values).toEqual([0, 20]);
+    expect(state.fromSample).toBe(fromSample);
+    expect(state.toSample).toBe(toSample);
+  });
+
+  it('uses shortest-arc quaternion slerp', () => {
+    const target = {};
+    const from = player(target, [0, 0, 0, 1, 0, 0, 0, 1], { components: 4, quaternion: true });
+    const to = player(target, [0, 0, -1, 0, 0, 0, -1, 0], { components: 4, quaternion: true });
+    const state = createAnimationCrossfade(from, to, 1);
+    advanceAnimationCrossfade(state, 0.5);
+    sampleAnimationCrossfade([0, 0, 0, 0], state, (sampled) => {
+      expect(Math.abs(sampled[2])).toBeCloseTo(Math.SQRT1_2);
+      expect(Math.abs(sampled[3])).toBeCloseTo(Math.SQRT1_2);
+    });
+  });
+});