Blend Shape Timeline Lock

Severity: ℹ️ Info
Fixable: 🔧 Manual (Runtime workaround)
Prevalence: 🔶 Medium

Summary

RealityKit’s AnimationPlaybackController takes exclusive ownership of blend shape weights during playback. Even when paused, animations continue to “sample” each frame, overwriting any manual blend shape changes. This prevents real-time facial expression control while an animation is playing.

---

Evidence

Community Reports

• Developers attempting to blend facial animations with manual expressions encounter this
• Common in avatar/character customization scenarios

TODO: Add specific forum links

---

When It Occurs

Whenever:

1. A model has blend shape weights
2. An animation targeting those weights is playing
3. Developer tries to manually set blend shape values

---

Root Cause

RealityKit’s animation system maintains exclusive control over animated properties:

• pause() freezes the animation but still samples each frame
• Only stop() fully releases ownership of the weights

This is by design for animation system consistency, but not well documented.

---

Detection

File: PreflightCore/USDClient.swift

Preflight detects when both:

• Blend shape targets exist on meshes
• SkelAnimation with blend shape channels exists

---

Solution

Runtime Workaround

// To manually control blend shapes:
controller.stop()  // NOT pause()

// Apply your manual weights
blendShapeWeightsComponent.weights = [...]

// Resume animation from stored time when done

See: docs/AnimationPlaybackController_PauseVsStop.md

---

Validation

• Empirically verified in Preflight development
• RealityKit animation ownership behavior confirmed

---

Related Issues

• Skeleton Path Mismatch - Another animation issue

---

Changelog

Date	Change
2024-12-18	Stub created