@downdraft/engine 0.0.0 → 0.1.1

package/core/src/animation/clip.ts

@@ -0,0 +1,252 @@
+import type { AnimationEventTrack } from "./animation-event";
+import type { MorphTargetTrack } from "./morph-target";
+import { sampleMorphWeight } from "./morph-target";
+
+export type TrackPath = "position" | "rotation" | "scale";
+
+export interface KeyframeTrack {
+  boneName: string;
+  boneIndex: number;
+  path: TrackPath;
+  times: Float32Array;
+  values: Float32Array;
+  interpolation: "step" | "linear" | "cubicspline";
+}
+
+export interface AnimationClipData {
+  name: string;
+  duration: number;
+  tracks: KeyframeTrack[];
+  morphTracks?: MorphTargetTrack[];
+  eventTrack?: AnimationEventTrack;
+}
+
+export class AnimationClip {
+  data: AnimationClipData;
+  private trackIndexMap: Map<string, KeyframeTrack[]> = new Map();
+  trackedBones: Set<number>;
+  morphTrackedTargets: Set<number> = new Set();
+
+  constructor(data: AnimationClipData) {
+    this.data = data;
+    this.trackedBones = new Set();
+    data.tracks.forEach((track) => {
+      this.trackedBones.add(track.boneIndex);
+      const key = `${track.boneIndex}:${track.path}`;
+      let tracks = this.trackIndexMap.get(key);
+      if (!tracks) {
+        tracks = [];
+        this.trackIndexMap.set(key, tracks);
+      }
+      tracks.push(track);
+    });
+    if (data.morphTracks) {
+      data.morphTracks.forEach((mt) => {
+        this.morphTrackedTargets.add(mt.targetIndex);
+      });
+    }
+  }
+
+  get duration(): number {
+    return this.data.duration;
+  }
+
+  get name(): string {
+    return this.data.name;
+  }
+
+  get trackCount(): number {
+    return this.data.tracks.length;
+  }
+
+  get morphTrackCount(): number {
+    return this.data.morphTracks?.length ?? 0;
+  }
+
+  get morphTracks(): MorphTargetTrack[] {
+    return this.data.morphTracks ?? [];
+  }
+
+  get eventTrack(): AnimationEventTrack | undefined {
+    return this.data.eventTrack;
+  }
+
+  getTracksForBone(boneIndex: number, path: TrackPath): KeyframeTrack[] {
+    return this.trackIndexMap.get(`${boneIndex}:${path}`) ?? [];
+  }
+
+  sample(
+    time: number,
+    outPositions: Array<[number, number, number]>,
+    outRotations: Array<[number, number, number, number]>,
+    outScales: Array<[number, number, number]>,
+  ): void {
+    let t: number;
+    if (this.data.duration > 0) {
+      t = time % this.data.duration;
+      if (t === 0 && time > 0) t = this.data.duration;
+    } else {
+      t = 0;
+    }
+
+    this.data.tracks.forEach((track) => {
+      switch (track.path) {
+        case "position":
+          outPositions[track.boneIndex] = sampleVec3(track, t, outPositions[track.boneIndex] ?? [0, 0, 0]);
+          break;
+        case "rotation":
+          outRotations[track.boneIndex] = sampleQuat(track, t, outRotations[track.boneIndex] ?? [0, 0, 0, 1]);
+          break;
+        case "scale":
+          outScales[track.boneIndex] = sampleVec3(track, t, outScales[track.boneIndex] ?? [1, 1, 1]);
+          break;
+      }
+    });
+  }
+
+  sampleMorphWeights(time: number, outWeights: Float32Array): void {
+    if (!this.data.morphTracks || this.data.morphTracks.length === 0) return;
+    let t: number;
+    if (this.data.duration > 0) {
+      t = time % this.data.duration;
+      if (t === 0 && time > 0) t = this.data.duration;
+    } else {
+      t = 0;
+    }
+    this.data.morphTracks.forEach((track) => {
+      outWeights[track.targetIndex] = sampleMorphWeight(track, t);
+    });
+  }
+}
+
+function findKeyframeIndex(times: Float32Array, t: number): { index: number; alpha: number } {
+  if (times.length === 0) return { index: 0, alpha: 0 };
+  if (times.length === 1) return { index: 0, alpha: 0 };
+  if (t <= times[0]) return { index: 0, alpha: 0 };
+  if (t >= times[times.length - 1]) return { index: times.length - 2, alpha: 1 };
+
+  let lo = 0;
+  let hi = times.length - 1;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (times[mid] <= t) lo = mid;
+    else hi = mid;
+  }
+
+  const duration = times[hi] - times[lo];
+  const alpha = duration > 0 ? (t - times[lo]) / duration : 0;
+  return { index: lo, alpha };
+}
+
+function sampleVec3(track: KeyframeTrack, t: number, out: [number, number, number]): [number, number, number] {
+  const { index, alpha } = findKeyframeIndex(track.times, t);
+  const base = index * 3;
+  if (track.interpolation === "step" || alpha === 0) {
+    out[0] = track.values[base];
+    out[1] = track.values[base + 1];
+    out[2] = track.values[base + 2];
+  } else {
+    const next = (index + 1) * 3;
+    out[0] = track.values[base] + (track.values[next] - track.values[base]) * alpha;
+    out[1] = track.values[base + 1] + (track.values[next + 1] - track.values[base + 1]) * alpha;
+    out[2] = track.values[base + 2] + (track.values[next + 2] - track.values[base + 2]) * alpha;
+  }
+  return out;
+}
+
+function slerpQuat(
+  a: [number, number, number, number],
+  b: [number, number, number, number],
+  t: number,
+): [number, number, number, number] {
+  let dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+  let bx = b[0], by = b[1], bz = b[2], bw = b[3];
+  if (dot < 0) {
+    bx = -bx; by = -by; bz = -bz; bw = -bw;
+    dot = -dot;
+  }
+  if (dot > 0.9995) {
+    return [
+      a[0] + (bx - a[0]) * t,
+      a[1] + (by - a[1]) * t,
+      a[2] + (bz - a[2]) * t,
+      a[3] + (bw - a[3]) * t,
+    ];
+  }
+  const theta = Math.acos(Math.min(1, Math.max(-1, dot)));
+  const sinTheta = Math.sin(theta);
+  const sinT0 = Math.sin((1 - t) * theta) / sinTheta;
+  const sinT1 = Math.sin(t * theta) / sinTheta;
+  return [
+    a[0] * sinT0 + bx * sinT1,
+    a[1] * sinT0 + by * sinT1,
+    a[2] * sinT0 + bz * sinT1,
+    a[3] * sinT0 + bw * sinT1,
+  ];
+}
+
+function sampleQuat(track: KeyframeTrack, t: number, out: [number, number, number, number]): [number, number, number, number] {
+  const { index, alpha } = findKeyframeIndex(track.times, t);
+  const base = index * 4;
+  if (track.interpolation === "step" || alpha === 0) {
+    out[0] = track.values[base];
+    out[1] = track.values[base + 1];
+    out[2] = track.values[base + 2];
+    out[3] = track.values[base + 3];
+  } else {
+    const a: [number, number, number, number] = [
+      track.values[base], track.values[base + 1], track.values[base + 2], track.values[base + 3],
+    ];
+    const next = (index + 1) * 4;
+    const b: [number, number, number, number] = [
+      track.values[next], track.values[next + 1], track.values[next + 2], track.values[next + 3],
+    ];
+    const result = slerpQuat(a, b, alpha);
+    out[0] = result[0]; out[1] = result[1]; out[2] = result[2]; out[3] = result[3];
+  }
+  return out;
+}
+
+export function buildAnimationClipFromGLTF(
+  name: string,
+  channels: Array<{
+    nodeIndex: number;
+    boneName: string;
+    boneIndex: number;
+    path: TrackPath;
+    times: Float32Array;
+    values: Float32Array;
+    interpolation?: "step" | "linear" | "cubicspline";
+  }>,
+  morphTracks?: MorphTargetTrack[],
+): AnimationClip {
+  let maxTime = 0;
+  channels.forEach((ch) => {
+    for (let i = 0; i < ch.times.length; i++) {
+      if (ch.times[i] > maxTime) maxTime = ch.times[i];
+    }
+  });
+  if (morphTracks) {
+    morphTracks.forEach((mt) => {
+      for (let i = 0; i < mt.times.length; i++) {
+        if (mt.times[i] > maxTime) maxTime = mt.times[i];
+      }
+    });
+  }
+
+  const tracks: KeyframeTrack[] = channels.map((ch) => ({
+    boneName: ch.boneName,
+    boneIndex: ch.boneIndex,
+    path: ch.path,
+    times: ch.times,
+    values: ch.values,
+    interpolation: ch.interpolation ?? "linear",
+  }));
+
+  return new AnimationClip({
+    name,
+    duration: maxTime,
+    tracks,
+    morphTracks,
+  });
+}

package/core/src/animation/index.ts

@@ -0,0 +1,22 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Animation library — re-exports
+// ─────────────────────────────────────────────────────────────────────────────
+export { createAnimationEventTrack, getEventsInRange } from "./animation-event";
+export type { AnimationEvent, AnimationEventTrack } from "./animation-event";
+export { BoneMaskPreset, buildBoneMask, buildCustomBoneMask, registerCustomMask } from "./bone-mask";
+export { AnimationClip, buildAnimationClipFromGLTF } from "./clip";
+export type { AnimationClipData, KeyframeTrack, TrackPath } from "./clip";
+export { DEFAULT_MIXAMO_CONFIG, MixamoRetargeter } from "./mixamo";
+export type { MixamoRetargetConfig } from "./mixamo";
+export { buildMorphTargetData, createMorphTargetTrack, findMorphKeyframeIndex, sampleMorphWeight } from "./morph-target";
+export type { MorphTarget, MorphTargetData, MorphTargetTrack } from "./morph-target";
+export { AnimationPlayer, MAX_MORPH_TARGETS } from "./player";
+export type { LayerBlendMode, PlayOptions } from "./player";
+export { buildRetargetMapping, retargetClip } from "./retarget";
+export type { BoneMapping, RetargetMapping } from "./retarget";
+export { buildSkeletonFromGLTF, Skeleton } from "./skeleton";
+export type { Bone, GLTFSkin, SkeletonData } from "./skeleton";
+export { SkeletonAnimator, skinDataToSkeletonData } from "./skeleton-animator";
+export type { AnimationChannel, AnimationData, AnimState, BoneData, SkinData } from "./skeleton-animator";
+export { AnimationStateMachine } from "./state-machine";
+export type { AnimationState, AnimationTransition, BlendTree, BlendTree1D, BlendTree2D } from "./state-machine";

package/core/src/animation/mixamo.ts

@@ -0,0 +1,113 @@
+import type { SkeletonData, Bone } from "./skeleton";
+import type { AnimationClipData, KeyframeTrack } from "./clip";
+import { buildRetargetMapping, retargetClip, type RetargetMapping } from "./retarget";
+
+const MIXAMO_PREFIX = "mixamorig:";
+
+export interface MixamoRetargetConfig {
+  stripPrefix: boolean;
+  tPoseToAPose: boolean;
+  aPoseArmAngle: number;
+}
+
+export const DEFAULT_MIXAMO_CONFIG: MixamoRetargetConfig = {
+  stripPrefix: true,
+  tPoseToAPose: true,
+  aPoseArmAngle: 20,
+};
+
+export class MixamoRetargeter {
+  private config: MixamoRetargetConfig;
+  private mappingCache: Map<string, RetargetMapping> = new Map();
+
+  constructor(config: Partial<MixamoRetargetConfig> = {}) {
+    this.config = { ...DEFAULT_MIXAMO_CONFIG, ...config };
+  }
+
+  stripMixamoPrefix(name: string): string {
+    if (name.startsWith(MIXAMO_PREFIX)) {
+      return name.slice(MIXAMO_PREFIX.length);
+    }
+    return name;
+  }
+
+  normalizeSkeleton(skeleton: SkeletonData): SkeletonData {
+    const normalizedBones: Bone[] = skeleton.bones.map((bone) => ({
+      ...bone,
+      name: this.config.stripPrefix ? this.stripMixamoPrefix(bone.name) : bone.name,
+      childrenIndices: [...bone.childrenIndices],
+    }));
+    return { ...skeleton, bones: normalizedBones };
+  }
+
+  buildMapping(
+    mixamoSkeleton: SkeletonData,
+    targetSkeleton: SkeletonData,
+  ): RetargetMapping {
+    const cacheKey = `${mixamoSkeleton.name}:${targetSkeleton.name}`;
+    const cached = this.mappingCache.get(cacheKey);
+    if (cached) return cached;
+
+    const normalizedMixamo = this.normalizeSkeleton(mixamoSkeleton);
+    const mapping = buildRetargetMapping(normalizedMixamo, targetSkeleton);
+
+    if (this.config.tPoseToAPose) {
+      this.applyTPoseToAPoseCorrection(mapping, targetSkeleton);
+    }
+
+    this.mappingCache.set(cacheKey, mapping);
+    return mapping;
+  }
+
+  retarget(
+    clip: AnimationClipData,
+    mixamoSkeleton: SkeletonData,
+    targetSkeleton: SkeletonData,
+  ): AnimationClipData {
+    const mapping = this.buildMapping(mixamoSkeleton, targetSkeleton);
+    return retargetClip(clip, mapping);
+  }
+
+  private applyTPoseToAPoseCorrection(
+    mapping: RetargetMapping,
+    targetSkeleton: SkeletonData,
+  ): void {
+    const armBones = [
+      "LeftArm", "RightArm",
+      "LeftForeArm", "RightForeArm",
+      "LeftUpArm", "RightUpArm",
+    ];
+
+    mapping.mappings.forEach((m) => {
+      const targetBone = targetSkeleton.bones[m.targetBoneIndex];
+      if (armBones.includes(targetBone.name)) {
+        const isLeft = targetBone.name.startsWith("Left");
+        const angle = isLeft ? this.config.aPoseArmAngle : -this.config.aPoseArmAngle;
+        const rad = (angle * Math.PI) / 180;
+        const correction: [number, number, number, number] = [
+          0,
+          Math.sin(rad / 2),
+          0,
+          Math.cos(rad / 2),
+        ];
+        m.rotationOffset = multiplyQuat(correction, m.rotationOffset);
+      }
+    });
+  }
+
+  clearCache(): void {
+    this.mappingCache.clear();
+  }
+}
+
+function multiplyQuat(
+  a: [number, number, number, number],
+  b: [number, number, number, number],
+): [number, number, number, number] {
+  return [
+    a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+    a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+    a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+    a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+  ];
+}

package/core/src/animation/morph-target.ts

@@ -0,0 +1,69 @@
+export interface MorphTarget {
+  name: string;
+  deltaPositions: Float32Array;
+  deltaNormals?: Float32Array;
+  weight: number;
+}
+
+export interface MorphTargetData {
+  targets: MorphTarget[];
+  maxInfluences: number;
+}
+
+export interface MorphTargetTrack {
+  targetIndex: number;
+  times: Float32Array;
+  values: Float32Array;
+  interpolation: "step" | "linear" | "cubicspline";
+}
+
+export function buildMorphTargetData(
+  targets: MorphTarget[],
+  maxInfluences?: number,
+): MorphTargetData {
+  const inferred = maxInfluences ?? Math.min(targets.length, 8);
+  return { targets, maxInfluences: inferred };
+}
+
+export function createMorphTargetTrack(
+  targetIndex: number,
+  times: Float32Array,
+  values: Float32Array,
+  interpolation: "step" | "linear" | "cubicspline" = "linear",
+): MorphTargetTrack {
+  return { targetIndex, times, values, interpolation };
+}
+
+export function findMorphKeyframeIndex(
+  times: Float32Array,
+  t: number,
+): { index: number; alpha: number } {
+  if (times.length === 0) return { index: 0, alpha: 0 };
+  if (times.length === 1) return { index: 0, alpha: 0 };
+  if (t <= times[0]) return { index: 0, alpha: 0 };
+  if (t >= times[times.length - 1])
+    return { index: times.length - 2, alpha: 1 };
+
+  let lo = 0;
+  let hi = times.length - 1;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (times[mid] <= t) lo = mid;
+    else hi = mid;
+  }
+
+  const duration = times[hi] - times[lo];
+  const alpha = duration > 0 ? (t - times[lo]) / duration : 0;
+  return { index: lo, alpha };
+}
+
+export function sampleMorphWeight(
+  track: MorphTargetTrack,
+  t: number,
+): number {
+  const { index, alpha } = findMorphKeyframeIndex(track.times, t);
+  const base = track.values[index];
+  if (track.interpolation === "step" || alpha === 0) return base;
+  const next = track.values[index + 1] ?? base;
+  return base + (next - base) * alpha;
+}