reze-engine 0.3.5 → 0.3.7

package/src/model.ts

@@ -1,6 +1,7 @@
-import { Mat4, Quat, Vec3, easeInOut } from "./math"
-import { Rigidbody, Joint } from "./physics"
+import { Mat4, Quat, Vec3, easeInOut, bezierInterpolate } from "./math"
+import { Rigidbody, Joint, Physics } from "./physics"
 import { IKSolverSystem } from "./ik-solver"
+import { VMDKeyFrame, VMDLoader, BoneFrame, MorphFrame } from "./vmd-loader"
 
 const VERTEX_STRIDE = 8
 
@@ -119,31 +120,29 @@ export interface MorphRuntime {
   weights: Float32Array // One weight per morph (0.0 to 1.0)
 }
 
-// Rotation tween state per bone
-interface RotationTweenState {
-  active: Uint8Array // 0/1 per bone
-  startQuat: Float32Array // quat per bone (x,y,z,w)
-  targetQuat: Float32Array // quat per bone (x,y,z,w)
-  startTimeMs: Float32Array // one float per bone (ms)
-  durationMs: Float32Array // one float per bone (ms)
-}
-
-// Morph weight tween state per morph
-interface MorphWeightTweenState {
-  active: Uint8Array // 0/1 per morph
-  startWeight: Float32Array // one float per morph
-  targetWeight: Float32Array // one float per morph
-  startTimeMs: Float32Array // one float per morph (ms)
-  durationMs: Float32Array // one float per morph (ms)
-}
-
-// Translation tween state per bone
-interface TranslationTweenState {
-  active: Uint8Array // 0/1 per bone
-  startVec: Float32Array // vec3 per bone (x,y,z)
-  targetVec: Float32Array // vec3 per bone (x,y,z)
-  startTimeMs: Float32Array // one float per bone (ms)
-  durationMs: Float32Array // one float per bone (ms)
+// Tween state - combines rotation, translation, and morph tweens
+// All tweens share the same time reference to avoid conflicts
+interface TweenState {
+  // Bone rotation tweens
+  rotActive: Uint8Array // 0/1 per bone
+  rotStartQuat: Float32Array // quat per bone (x,y,z,w)
+  rotTargetQuat: Float32Array // quat per bone (x,y,z,w)
+  rotStartTimeMs: Float32Array // one float per bone (ms)
+  rotDurationMs: Float32Array // one float per bone (ms)
+
+  // Bone translation tweens
+  transActive: Uint8Array // 0/1 per bone
+  transStartVec: Float32Array // vec3 per bone (x,y,z)
+  transTargetVec: Float32Array // vec3 per bone (x,y,z)
+  transStartTimeMs: Float32Array // one float per bone (ms)
+  transDurationMs: Float32Array // one float per bone (ms)
+
+  // Morph weight tweens
+  morphActive: Uint8Array // 0/1 per morph
+  morphStartWeight: Float32Array // one float per morph
+  morphTargetWeight: Float32Array // one float per morph
+  morphStartTimeMs: Float32Array // one float per morph (ms)
+  morphDurationMs: Float32Array // one float per morph (ms)
 }
 
 export class Model {
@@ -169,14 +168,29 @@ export class Model {
 
   // Runtime morph state
   private runtimeMorph!: MorphRuntime
+  private morphsDirty: boolean = false // Flag indicating if morphs need to be applied
 
   // Cached identity matrices to avoid allocations in computeWorldMatrices
   private cachedIdentityMat1 = Mat4.identity()
   private cachedIdentityMat2 = Mat4.identity()
 
-  private rotTweenState!: RotationTweenState
-  private transTweenState!: TranslationTweenState
-  private morphTweenState!: MorphWeightTweenState
+  // Cached skin matrices array to avoid allocations in getSkinMatrices
+  private cachedSkinMatrices?: Float32Array
+
+  private tweenState!: TweenState
+  private tweenTimeMs: number = 0 // Time tracking for tweens (milliseconds)
+
+  // Animation runtime
+  private animationData: VMDKeyFrame[] | null = null
+  private boneTracks: Map<string, Array<{ boneFrame: BoneFrame; time: number }>> = new Map()
+  private morphTracks: Map<string, Array<{ morphFrame: MorphFrame; time: number }>> = new Map()
+  private animationDuration: number = 0
+  private isPlaying: boolean = false
+  private isPaused: boolean = false
+  private animationTime: number = 0 // Current time in animation (seconds)
+
+  // Physics runtime
+  private physics: Physics | null = null
 
   constructor(
     vertexData: Float32Array<ArrayBuffer>,
@@ -207,11 +221,17 @@ export class Model {
     }
 
     this.initializeRuntimeSkeleton()
-    this.initializeRotTweenBuffers()
-    this.initializeTransTweenBuffers()
     this.initializeRuntimeMorph()
-    this.initializeMorphTweenBuffers()
+    this.initializeTweenBuffers()
     this.applyMorphs() // Apply initial morphs (all weights are 0, so no change)
+
+    // Initialize physics if rigidbodies exist
+    if (rigidbodies.length > 0) {
+      this.physics = new Physics(rigidbodies, joints)
+      console.log(`[Model] Physics initialized with ${rigidbodies.length} rigidbodies`)
+    } else {
+      console.log("[Model] No rigidbodies found, physics disabled")
+    }
   }
 
   private initializeRuntimeSkeleton(): void {
@@ -278,36 +298,31 @@ export class Model {
     this.runtimeSkeleton.ikSolvers = ikSolvers
   }
 
-  private initializeRotTweenBuffers(): void {
-    const n = this.skeleton.bones.length
-    this.rotTweenState = {
-      active: new Uint8Array(n),
-      startQuat: new Float32Array(n * 4),
-      targetQuat: new Float32Array(n * 4),
-      startTimeMs: new Float32Array(n),
-      durationMs: new Float32Array(n),
-    }
-  }
-
-  private initializeTransTweenBuffers(): void {
-    const n = this.skeleton.bones.length
-    this.transTweenState = {
-      active: new Uint8Array(n),
-      startVec: new Float32Array(n * 3),
-      targetVec: new Float32Array(n * 3),
-      startTimeMs: new Float32Array(n),
-      durationMs: new Float32Array(n),
-    }
-  }
+  private initializeTweenBuffers(): void {
+    const boneCount = this.skeleton.bones.length
+    const morphCount = this.morphing.morphs.length
 
-  private initializeMorphTweenBuffers(): void {
-    const n = this.morphing.morphs.length
-    this.morphTweenState = {
-      active: new Uint8Array(n),
-      startWeight: new Float32Array(n),
-      targetWeight: new Float32Array(n),
-      startTimeMs: new Float32Array(n),
-      durationMs: new Float32Array(n),
+    this.tweenState = {
+      // Bone rotation tweens
+      rotActive: new Uint8Array(boneCount),
+      rotStartQuat: new Float32Array(boneCount * 4),
+      rotTargetQuat: new Float32Array(boneCount * 4),
+      rotStartTimeMs: new Float32Array(boneCount),
+      rotDurationMs: new Float32Array(boneCount),
+
+      // Bone translation tweens
+      transActive: new Uint8Array(boneCount),
+      transStartVec: new Float32Array(boneCount * 3),
+      transTargetVec: new Float32Array(boneCount * 3),
+      transStartTimeMs: new Float32Array(boneCount),
+      transDurationMs: new Float32Array(boneCount),
+
+      // Morph weight tweens
+      morphActive: new Uint8Array(morphCount),
+      morphStartWeight: new Float32Array(morphCount),
+      morphTargetWeight: new Float32Array(morphCount),
+      morphStartTimeMs: new Float32Array(morphCount),
+      morphDurationMs: new Float32Array(morphCount),
     }
   }
 
@@ -322,32 +337,37 @@ export class Model {
     }
   }
 
-  private updateRotationTweens(): void {
-    const state = this.rotTweenState
-    const now = performance.now()
+  // Tween update - processes all tweens together with a single time reference
+  // This avoids conflicts and ensures consistent timing across all tween types
+  // Returns true if morph weights changed (needed for vertex buffer updates)
+  private updateTweens(): boolean {
+    const state = this.tweenState
+    const now = this.tweenTimeMs // Single time reference for all tweens
+    let morphChanged = false
+
+    // Update bone rotation tweens
     const rotations = this.runtimeSkeleton.localRotations
     const boneCount = this.skeleton.bones.length
-
     for (let i = 0; i < boneCount; i++) {
-      if (state.active[i] !== 1) continue
+      if (state.rotActive[i] !== 1) continue
 
-      const startMs = state.startTimeMs[i]
-      const durMs = Math.max(1, state.durationMs[i])
+      const startMs = state.rotStartTimeMs[i]
+      const durMs = Math.max(1, state.rotDurationMs[i])
       const t = Math.max(0, Math.min(1, (now - startMs) / durMs))
       const e = easeInOut(t)
 
       const qi = i * 4
       const startQuat = new Quat(
-        state.startQuat[qi],
-        state.startQuat[qi + 1],
-        state.startQuat[qi + 2],
-        state.startQuat[qi + 3]
+        state.rotStartQuat[qi],
+        state.rotStartQuat[qi + 1],
+        state.rotStartQuat[qi + 2],
+        state.rotStartQuat[qi + 3]
       )
       const targetQuat = new Quat(
-        state.targetQuat[qi],
-        state.targetQuat[qi + 1],
-        state.targetQuat[qi + 2],
-        state.targetQuat[qi + 3]
+        state.rotTargetQuat[qi],
+        state.rotTargetQuat[qi + 1],
+        state.rotTargetQuat[qi + 2],
+        state.rotTargetQuat[qi + 3]
       )
       const result = Quat.slerp(startQuat, targetQuat, e)
 
@@ -356,87 +376,81 @@ export class Model {
       rotations[qi + 2] = result.z
       rotations[qi + 3] = result.w
 
-      if (t >= 1) state.active[i] = 0
+      if (t >= 1) {
+        state.rotActive[i] = 0
+      }
     }
-  }
 
-  private updateTranslationTweens(): void {
-    const state = this.transTweenState
-    const now = performance.now()
+    // Update bone translation tweens
     const translations = this.runtimeSkeleton.localTranslations
-    const boneCount = this.skeleton.bones.length
-
     for (let i = 0; i < boneCount; i++) {
-      if (state.active[i] !== 1) continue
+      if (state.transActive[i] !== 1) continue
 
-      const startMs = state.startTimeMs[i]
-      const durMs = Math.max(1, state.durationMs[i])
+      const startMs = state.transStartTimeMs[i]
+      const durMs = Math.max(1, state.transDurationMs[i])
       const t = Math.max(0, Math.min(1, (now - startMs) / durMs))
       const e = easeInOut(t)
 
       const ti = i * 3
-      translations[ti] = state.startVec[ti] + (state.targetVec[ti] - state.startVec[ti]) * e
-      translations[ti + 1] = state.startVec[ti + 1] + (state.targetVec[ti + 1] - state.startVec[ti + 1]) * e
-      translations[ti + 2] = state.startVec[ti + 2] + (state.targetVec[ti + 2] - state.startVec[ti + 2]) * e
+      translations[ti] = state.transStartVec[ti] + (state.transTargetVec[ti] - state.transStartVec[ti]) * e
+      translations[ti + 1] =
+        state.transStartVec[ti + 1] + (state.transTargetVec[ti + 1] - state.transStartVec[ti + 1]) * e
+      translations[ti + 2] =
+        state.transStartVec[ti + 2] + (state.transTargetVec[ti + 2] - state.transStartVec[ti + 2]) * e
 
-      if (t >= 1) state.active[i] = 0
+      if (t >= 1) {
+        state.transActive[i] = 0
+      }
     }
-  }
 
-  private updateMorphWeightTweens(): boolean {
-    const state = this.morphTweenState
-    const now = performance.now()
+    // Update morph weight tweens
     const weights = this.runtimeMorph.weights
     const morphCount = this.morphing.morphs.length
-    let hasActiveTweens = false
-
     for (let i = 0; i < morphCount; i++) {
-      if (state.active[i] !== 1) continue
+      if (state.morphActive[i] !== 1) continue
 
-      hasActiveTweens = true
-      const startMs = state.startTimeMs[i]
-      const durMs = Math.max(1, state.durationMs[i])
+      const startMs = state.morphStartTimeMs[i]
+      const durMs = Math.max(1, state.morphDurationMs[i])
       const t = Math.max(0, Math.min(1, (now - startMs) / durMs))
       const e = easeInOut(t)
 
-      weights[i] = state.startWeight[i] + (state.targetWeight[i] - state.startWeight[i]) * e
+      const oldWeight = weights[i]
+      weights[i] = state.morphStartWeight[i] + (state.morphTargetWeight[i] - state.morphStartWeight[i]) * e
+
+      // Check if weight actually changed (accounting for floating point precision)
+      if (Math.abs(weights[i] - oldWeight) > 1e-6) {
+        morphChanged = true
+      }
 
       if (t >= 1) {
-        weights[i] = state.targetWeight[i]
-        state.active[i] = 0
+        weights[i] = state.morphTargetWeight[i]
+        state.morphActive[i] = 0
+        // Check if final weight is different from old weight
+        if (Math.abs(weights[i] - oldWeight) > 1e-6) {
+          morphChanged = true
+        }
       }
     }
 
-    return hasActiveTweens
+    return morphChanged
   }
 
-  // Get interleaved vertex data for GPU upload
-  // Format: [x,y,z, nx,ny,nz, u,v, x,y,z, nx,ny,nz, u,v, ...]
   getVertices(): Float32Array<ArrayBuffer> {
     return this.vertexData
   }
 
-  // Get texture information
   getTextures(): Texture[] {
     return this.textures
   }
 
-  // Get material information
   getMaterials(): Material[] {
     return this.materials
   }
 
-  // Get vertex count
-  getVertexCount(): number {
-    return this.vertexCount
-  }
-
-  // Get index data for GPU upload
   getIndices(): Uint32Array<ArrayBuffer> {
     return this.indexData
   }
 
-  // Accessors for skeleton/skinning
   getSkeleton(): Skeleton {
     return this.skeleton
   }
@@ -445,7 +459,6 @@ export class Model {
     return this.skinning
   }
 
-  // Accessors for physics data
   getRigidbodies(): Rigidbody[] {
     return this.rigidbodies
   }
@@ -454,7 +467,6 @@ export class Model {
     return this.joints
   }
 
-  // Accessors for morphing
   getMorphing(): Morphing {
     return this.morphing
   }
@@ -465,14 +477,10 @@ export class Model {
 
   // ------- Bone helpers (public API) -------
 
-  getBoneNames(): string[] {
-    return this.skeleton.bones.map((b) => b.name)
-  }
-
   rotateBones(names: string[], quats: Quat[], durationMs?: number): void {
-    const state = this.rotTweenState
+    const state = this.tweenState
     const normalized = quats.map((q) => q.normalize())
-    const now = performance.now()
+    const now = this.tweenTimeMs
     const dur = durationMs && durationMs > 0 ? durationMs : 0
 
     for (let i = 0; i < names.length; i++) {
@@ -489,7 +497,7 @@ export class Model {
         rotations[qi + 1] = ty
         rotations[qi + 2] = tz
         rotations[qi + 3] = tw
-        state.active[idx] = 0
+        state.rotActive[idx] = 0
         continue
       }
 
@@ -498,22 +506,22 @@ export class Model {
       let sz = rotations[qi + 2]
       let sw = rotations[qi + 3]
 
-      if (state.active[idx] === 1) {
-        const startMs = state.startTimeMs[idx]
-        const prevDur = Math.max(1, state.durationMs[idx])
+      if (state.rotActive[idx] === 1) {
+        const startMs = state.rotStartTimeMs[idx]
+        const prevDur = Math.max(1, state.rotDurationMs[idx])
         const t = Math.max(0, Math.min(1, (now - startMs) / prevDur))
         const e = easeInOut(t)
         const startQuat = new Quat(
-          state.startQuat[qi],
-          state.startQuat[qi + 1],
-          state.startQuat[qi + 2],
-          state.startQuat[qi + 3]
+          state.rotStartQuat[qi],
+          state.rotStartQuat[qi + 1],
+          state.rotStartQuat[qi + 2],
+          state.rotStartQuat[qi + 3]
         )
         const targetQuat = new Quat(
-          state.targetQuat[qi],
-          state.targetQuat[qi + 1],
-          state.targetQuat[qi + 2],
-          state.targetQuat[qi + 3]
+          state.rotTargetQuat[qi],
+          state.rotTargetQuat[qi + 1],
+          state.rotTargetQuat[qi + 2],
+          state.rotTargetQuat[qi + 3]
         )
         const result = Quat.slerp(startQuat, targetQuat, e)
         sx = result.x
@@ -522,25 +530,25 @@ export class Model {
         sw = result.w
       }
 
-      state.startQuat[qi] = sx
-      state.startQuat[qi + 1] = sy
-      state.startQuat[qi + 2] = sz
-      state.startQuat[qi + 3] = sw
-      state.targetQuat[qi] = tx
-      state.targetQuat[qi + 1] = ty
-      state.targetQuat[qi + 2] = tz
-      state.targetQuat[qi + 3] = tw
-      state.startTimeMs[idx] = now
-      state.durationMs[idx] = dur
-      state.active[idx] = 1
+      state.rotStartQuat[qi] = sx
+      state.rotStartQuat[qi + 1] = sy
+      state.rotStartQuat[qi + 2] = sz
+      state.rotStartQuat[qi + 3] = sw
+      state.rotTargetQuat[qi] = tx
+      state.rotTargetQuat[qi + 1] = ty
+      state.rotTargetQuat[qi + 2] = tz
+      state.rotTargetQuat[qi + 3] = tw
+      state.rotStartTimeMs[idx] = now
+      state.rotDurationMs[idx] = dur
+      state.rotActive[idx] = 1
     }
   }
 
   // Move bones using VMD-style relative translations (relative to bind pose world position)
   // This is the default behavior for VMD animations
   moveBones(names: string[], relativeTranslations: Vec3[], durationMs?: number): void {
-    const state = this.transTweenState
-    const now = performance.now()
+    const state = this.tweenState
+    const now = this.tweenTimeMs
     const dur = durationMs && durationMs > 0 ? durationMs : 0
     const localRot = this.runtimeSkeleton.localRotations
 
@@ -608,7 +616,7 @@ export class Model {
         translations[ti] = tx
         translations[ti + 1] = ty
         translations[ti + 2] = tz
-        state.active[idx] = 0
+        state.transActive[idx] = 0
         continue
       }
 
@@ -616,25 +624,25 @@ export class Model {
       let sy = translations[ti + 1]
       let sz = translations[ti + 2]
 
-      if (state.active[idx] === 1) {
-        const startMs = state.startTimeMs[idx]
-        const prevDur = Math.max(1, state.durationMs[idx])
+      if (state.transActive[idx] === 1) {
+        const startMs = state.transStartTimeMs[idx]
+        const prevDur = Math.max(1, state.transDurationMs[idx])
         const t = Math.max(0, Math.min(1, (now - startMs) / prevDur))
         const e = easeInOut(t)
-        sx = state.startVec[ti] + (state.targetVec[ti] - state.startVec[ti]) * e
-        sy = state.startVec[ti + 1] + (state.targetVec[ti + 1] - state.startVec[ti + 1]) * e
-        sz = state.startVec[ti + 2] + (state.targetVec[ti + 2] - state.startVec[ti + 2]) * e
+        sx = state.transStartVec[ti] + (state.transTargetVec[ti] - state.transStartVec[ti]) * e
+        sy = state.transStartVec[ti + 1] + (state.transTargetVec[ti + 1] - state.transStartVec[ti + 1]) * e
+        sz = state.transStartVec[ti + 2] + (state.transTargetVec[ti + 2] - state.transStartVec[ti + 2]) * e
       }
 
-      state.startVec[ti] = sx
-      state.startVec[ti + 1] = sy
-      state.startVec[ti + 2] = sz
-      state.targetVec[ti] = tx
-      state.targetVec[ti + 1] = ty
-      state.targetVec[ti + 2] = tz
-      state.startTimeMs[idx] = now
-      state.durationMs[idx] = dur
-      state.active[idx] = 1
+      state.transStartVec[ti] = sx
+      state.transStartVec[ti + 1] = sy
+      state.transStartVec[ti + 2] = sz
+      state.transTargetVec[ti] = tx
+      state.transTargetVec[ti + 1] = ty
+      state.transTargetVec[ti + 2] = tz
+      state.transStartTimeMs[idx] = now
+      state.transDurationMs[idx] = dur
+      state.transActive[idx] = 1
     }
   }
 
@@ -646,8 +654,28 @@ export class Model {
     return this.skeleton.inverseBindMatrices
   }
 
-  getMorphNames(): string[] {
-    return this.morphing.morphs.map((m) => m.name)
+  getSkinMatrices(): Float32Array {
+    const boneCount = this.skeleton.bones.length
+    const worldMats = this.runtimeSkeleton.worldMatrices
+    const invBindMats = this.skeleton.inverseBindMatrices
+
+    // Initialize cached array if needed or if bone count changed
+    if (!this.cachedSkinMatrices || this.cachedSkinMatrices.length !== boneCount * 16) {
+      this.cachedSkinMatrices = new Float32Array(boneCount * 16)
+    }
+
+    const skinMatrices = this.cachedSkinMatrices
+
+    // Compute skin matrices: skinMatrix = worldMatrix × inverseBindMatrix
+    // Use Mat4.multiplyArrays to avoid creating Mat4 objects
+    for (let i = 0; i < boneCount; i++) {
+      const worldOffset = i * 16
+      const invBindOffset = i * 16
+      const skinOffset = i * 16
+      Mat4.multiplyArrays(worldMats, worldOffset, invBindMats, invBindOffset, skinMatrices, skinOffset)
+    }
+
+    return skinMatrices
   }
 
   setMorphWeight(name: string, weight: number, durationMs?: number): void {
@@ -660,30 +688,30 @@ export class Model {
     if (dur === 0) {
       // Instant change
       this.runtimeMorph.weights[idx] = clampedWeight
-      this.morphTweenState.active[idx] = 0
+      this.tweenState.morphActive[idx] = 0
       this.applyMorphs()
       return
     }
 
     // Animated change
-    const state = this.morphTweenState
-    const now = performance.now()
+    const state = this.tweenState
+    const now = this.tweenTimeMs
 
     // If already tweening, start from current interpolated value
     let startWeight = this.runtimeMorph.weights[idx]
-    if (state.active[idx] === 1) {
-      const startMs = state.startTimeMs[idx]
-      const prevDur = Math.max(1, state.durationMs[idx])
+    if (state.morphActive[idx] === 1) {
+      const startMs = state.morphStartTimeMs[idx]
+      const prevDur = Math.max(1, state.morphDurationMs[idx])
       const t = Math.max(0, Math.min(1, (now - startMs) / prevDur))
       const e = easeInOut(t)
-      startWeight = state.startWeight[idx] + (state.targetWeight[idx] - state.startWeight[idx]) * e
+      startWeight = state.morphStartWeight[idx] + (state.morphTargetWeight[idx] - state.morphStartWeight[idx]) * e
     }
 
-    state.startWeight[idx] = startWeight
-    state.targetWeight[idx] = clampedWeight
-    state.startTimeMs[idx] = now
-    state.durationMs[idx] = dur
-    state.active[idx] = 1
+    state.morphStartWeight[idx] = startWeight
+    state.morphTargetWeight[idx] = clampedWeight
+    state.morphStartTimeMs[idx] = now
+    state.morphDurationMs[idx] = dur
+    state.morphActive[idx] = 1
 
     // Immediately apply morphs with current weight
     this.runtimeMorph.weights[idx] = startWeight
@@ -755,15 +783,313 @@ export class Model {
     }
   }
 
-  evaluatePose(): boolean {
-    this.updateRotationTweens()
-    this.updateTranslationTweens()
-    const hasActiveMorphTweens = this.updateMorphWeightTweens()
-    if (hasActiveMorphTweens) {
+  /**
+   * Load VMD animation file
+   */
+  async loadVmd(vmdUrl: string): Promise<void> {
+    this.animationData = await VMDLoader.load(vmdUrl)
+    this.processFrames()
+    // Apply initial pose at time 0
+    this.animationTime = 0
+    this.getPoseAtTime(0)
+
+    // Apply morphs if animation changed them
+    if (this.morphsDirty) {
       this.applyMorphs()
+      this.morphsDirty = false
     }
 
-    // Compute initial world matrices (needed for IK solving to read bone positions)
+    // Compute world matrices after applying initial pose
+    this.computeWorldMatrices()
+  }
+
+  /**
+   * Process frames into tracks
+   */
+  private processFrames(): void {
+    if (!this.animationData) return
+
+    // Helper to group frames by name and sort by time
+    const groupFrames = <T>(
+      items: Array<{ item: T; name: string; time: number }>
+    ): Map<string, Array<{ item: T; time: number }>> => {
+      const tracks = new Map<string, Array<{ item: T; time: number }>>()
+      for (const { item, name, time } of items) {
+        if (!tracks.has(name)) tracks.set(name, [])
+        tracks.get(name)!.push({ item, time })
+      }
+      for (const keyFrames of tracks.values()) {
+        keyFrames.sort((a, b) => a.time - b.time)
+      }
+      return tracks
+    }
+
+    // Collect all bone and morph frames
+    const boneItems: Array<{ item: BoneFrame; name: string; time: number }> = []
+    const morphItems: Array<{ item: MorphFrame; name: string; time: number }> = []
+
+    for (const keyFrame of this.animationData) {
+      for (const boneFrame of keyFrame.boneFrames) {
+        boneItems.push({ item: boneFrame, name: boneFrame.boneName, time: keyFrame.time })
+      }
+      for (const morphFrame of keyFrame.morphFrames) {
+        morphItems.push({ item: morphFrame, name: morphFrame.morphName, time: keyFrame.time })
+      }
+    }
+
+    // Transform to expected format
+    this.boneTracks = new Map()
+    for (const [name, frames] of groupFrames(boneItems).entries()) {
+      this.boneTracks.set(
+        name,
+        frames.map((f) => ({ boneFrame: f.item, time: f.time }))
+      )
+    }
+
+    this.morphTracks = new Map()
+    for (const [name, frames] of groupFrames(morphItems).entries()) {
+      this.morphTracks.set(
+        name,
+        frames.map((f) => ({ morphFrame: f.item, time: f.time }))
+      )
+    }
+
+    // Calculate duration from all tracks
+    const allTracks = [...this.boneTracks.values(), ...this.morphTracks.values()]
+    this.animationDuration = allTracks.reduce((max, keyFrames) => {
+      const lastTime = keyFrames[keyFrames.length - 1]?.time ?? 0
+      return Math.max(max, lastTime)
+    }, 0)
+  }
+
+  /**
+   * Start or resume playback
+   */
+  playAnimation(): void {
+    if (!this.animationData) {
+      console.warn("[Model] Cannot play animation: no animation data loaded")
+      return
+    }
+
+    this.isPaused = false
+    this.isPlaying = true
+
+    // Apply initial pose at current animation time
+    this.getPoseAtTime(this.animationTime)
+
+    // Apply morphs if animation changed them
+    if (this.morphsDirty) {
+      this.applyMorphs()
+      this.morphsDirty = false
+    }
+
+    // Compute world matrices after applying pose
+    this.computeWorldMatrices()
+
+    // Reset physics when starting animation (prevents instability from sudden pose changes)
+    if (this.physics) {
+      this.physics.reset(this.runtimeSkeleton.worldMatrices, this.skeleton.inverseBindMatrices)
+    }
+  }
+
+  /**
+   * Pause playback
+   */
+  pauseAnimation(): void {
+    if (!this.isPlaying || this.isPaused) return
+    this.isPaused = true
+  }
+
+  /**
+   * Stop playback and reset to beginning
+   */
+  stopAnimation(): void {
+    this.isPlaying = false
+    this.isPaused = false
+    this.animationTime = 0
+
+    // Reset physics state when stopping animation (prevents instability from sudden pose changes)
+    if (this.physics) {
+      this.computeWorldMatrices()
+      this.physics.reset(this.runtimeSkeleton.worldMatrices, this.skeleton.inverseBindMatrices)
+    }
+  }
+
+  /**
+   * Seek to specific time
+   * Immediately applies pose at the seeked time
+   */
+  seekAnimation(time: number): void {
+    if (!this.animationData) return
+
+    const clampedTime = Math.max(0, Math.min(time, this.animationDuration))
+    this.animationTime = clampedTime
+    // Immediately apply pose at seeked time
+    this.getPoseAtTime(clampedTime)
+
+    // Apply morphs if animation changed them
+    if (this.morphsDirty) {
+      this.applyMorphs()
+      this.morphsDirty = false
+    }
+
+    // Compute world matrices after applying pose
+    this.computeWorldMatrices()
+  }
+
+  /**
+   * Get current animation progress
+   */
+  getAnimationProgress(): { current: number; duration: number; percentage: number } {
+    const duration = this.animationDuration
+    const percentage = duration > 0 ? (this.animationTime / duration) * 100 : 0
+    return {
+      current: this.animationTime,
+      duration,
+      percentage,
+    }
+  }
+
+  /**
+   * Get pose at specific time (internal helper)
+   */
+  private getPoseAtTime(time: number): void {
+    if (!this.animationData) return
+
+    // Helper for binary search upper bound
+    const upperBound = <T extends { time: number }>(time: number, keyFrames: T[]): number => {
+      let left = 0,
+        right = keyFrames.length
+      while (left < right) {
+        const mid = Math.floor((left + right) / 2)
+        if (keyFrames[mid].time <= time) left = mid + 1
+        else right = mid
+      }
+      return left
+    }
+
+    // Process bone tracks
+    for (const [boneName, keyFrames] of this.boneTracks.entries()) {
+      if (keyFrames.length === 0) continue
+
+      const clampedTime = Math.max(keyFrames[0].time, Math.min(keyFrames[keyFrames.length - 1].time, time))
+      const idx = upperBound(clampedTime, keyFrames) - 1
+      if (idx < 0) continue
+
+      const frameA = keyFrames[idx].boneFrame
+      const frameB = keyFrames[idx + 1]?.boneFrame
+
+      const boneIdx = this.runtimeSkeleton.nameIndex[boneName]
+      if (boneIdx === undefined) continue
+
+      if (!frameB) {
+        this.runtimeSkeleton.localRotations[boneIdx * 4] = frameA.rotation.x
+        this.runtimeSkeleton.localRotations[boneIdx * 4 + 1] = frameA.rotation.y
+        this.runtimeSkeleton.localRotations[boneIdx * 4 + 2] = frameA.rotation.z
+        this.runtimeSkeleton.localRotations[boneIdx * 4 + 3] = frameA.rotation.w
+        this.runtimeSkeleton.localTranslations[boneIdx * 3] = frameA.translation.x
+        this.runtimeSkeleton.localTranslations[boneIdx * 3 + 1] = frameA.translation.y
+        this.runtimeSkeleton.localTranslations[boneIdx * 3 + 2] = frameA.translation.z
+      } else {
+        const timeA = keyFrames[idx].time
+        const timeB = keyFrames[idx + 1].time
+        const gradient = (clampedTime - timeA) / (timeB - timeA)
+        const interp = frameB.interpolation
+
+        // Interpolate rotation using SLERP with bezier
+        const rotT = bezierInterpolate(interp[0] / 127, interp[1] / 127, interp[2] / 127, interp[3] / 127, gradient)
+        const rotation = Quat.slerp(frameA.rotation, frameB.rotation, rotT)
+
+        // Interpolate translation using bezier for each component
+        const getWeight = (offset: number) =>
+          bezierInterpolate(
+            interp[offset] / 127,
+            interp[offset + 8] / 127,
+            interp[offset + 4] / 127,
+            interp[offset + 12] / 127,
+            gradient
+          )
+
+        const lerp = (a: number, b: number, w: number) => a + (b - a) * w
+        const translation = new Vec3(
+          lerp(frameA.translation.x, frameB.translation.x, getWeight(0)),
+          lerp(frameA.translation.y, frameB.translation.y, getWeight(16)),
+          lerp(frameA.translation.z, frameB.translation.z, getWeight(32))
+        )
+
+        this.runtimeSkeleton.localRotations[boneIdx * 4] = rotation.x
+        this.runtimeSkeleton.localRotations[boneIdx * 4 + 1] = rotation.y
+        this.runtimeSkeleton.localRotations[boneIdx * 4 + 2] = rotation.z
+        this.runtimeSkeleton.localRotations[boneIdx * 4 + 3] = rotation.w
+        this.runtimeSkeleton.localTranslations[boneIdx * 3] = translation.x
+        this.runtimeSkeleton.localTranslations[boneIdx * 3 + 1] = translation.y
+        this.runtimeSkeleton.localTranslations[boneIdx * 3 + 2] = translation.z
+      }
+    }
+
+    // Process morph tracks
+    for (const [morphName, keyFrames] of this.morphTracks.entries()) {
+      if (keyFrames.length === 0) continue
+
+      const clampedTime = Math.max(keyFrames[0].time, Math.min(keyFrames[keyFrames.length - 1].time, time))
+      const idx = upperBound(clampedTime, keyFrames) - 1
+      if (idx < 0) continue
+
+      const frameA = keyFrames[idx].morphFrame
+      const frameB = keyFrames[idx + 1]?.morphFrame
+
+      const morphIdx = this.runtimeMorph.nameIndex[morphName]
+      if (morphIdx === undefined) continue
+
+      const weight = frameB
+        ? frameA.weight +
+          (frameB.weight - frameA.weight) *
+            ((clampedTime - keyFrames[idx].time) / (keyFrames[idx + 1].time - keyFrames[idx].time))
+        : frameA.weight
+
+      this.runtimeMorph.weights[morphIdx] = weight
+      this.morphsDirty = true // Mark as dirty when animation sets morph weights
+    }
+  }
+
+  /**
+   * Updates the model pose by recomputing all matrices.
+   * If animation is playing, applies animation pose first.
+   * deltaTime: Time elapsed since last update in seconds
+   * Returns true if vertices were modified (morphs changed)
+   */
+  update(deltaTime: number): boolean {
+    // Update tween time (in milliseconds)
+    this.tweenTimeMs += deltaTime * 1000
+
+    // Update all active tweens (rotations, translations, morphs)
+    const tweensChangedMorphs = this.updateTweens()
+
+    // Apply animation if playing or paused (always apply pose if animation data exists and we have a time set)
+    if (this.animationData) {
+      if (this.isPlaying && !this.isPaused) {
+        this.animationTime += deltaTime
+
+        if (this.animationTime >= this.animationDuration) {
+          this.animationTime = this.animationDuration
+          this.pauseAnimation() // Auto-pause at end
+        }
+
+        this.getPoseAtTime(this.animationTime)
+      } else if (this.isPaused || (!this.isPlaying && this.animationTime >= 0)) {
+        // Apply pose at paused time or if we have a seeked time but not playing
+        this.getPoseAtTime(this.animationTime)
+      }
+    }
+
+    // Apply morphs if tweens changed morphs or animation changed morphs
+    const verticesChanged = this.morphsDirty || tweensChangedMorphs
+    if (this.morphsDirty || tweensChangedMorphs) {
+      this.applyMorphs()
+      this.morphsDirty = false
+    }
+
+    // Compute world matrices (needed for IK solving to read bone positions)
     this.computeWorldMatrices()
 
     // Solve IK chains (modifies localRotations with final IK rotations)
@@ -772,7 +1098,11 @@ export class Model {
     // Recompute world matrices with final IK rotations applied to localRotations
     this.computeWorldMatrices()
 
-    return hasActiveMorphTweens
+    if (this.physics) {
+      this.physics.step(deltaTime, this.runtimeSkeleton.worldMatrices, this.skeleton.inverseBindMatrices)
+    }
+
+    return verticesChanged
   }
 
   private solveIKChains(): void {