Technical documentation for Lilith's comprehensive animation framework covering UI transitions, 3D avatar animations, facial expressions, and movement meditation sequences.
Overview#
The Lilith Platform implements a multi-layer animation system spanning:
- UI Animation Layer: Token-based CSS animations with React hooks
- 3D Avatar Animation: Gesture system with procedural/clip-based animations
- Inverse Kinematics (IK): Real-time bone manipulation for natural movement
- AI-Driven Facial Animation: Lip-sync and expression generation
- Movement Meditation: Tai Chi, Qigong, and mindful walking sequences
Architecture#
┌─────────────────────────────────────────────────────────────────────────┐
│ Animation System Architecture │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ UI Animation Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Animation │ │ Animation │ │ React Animation │ │ │
│ │ │ Tokens │──│ Presets │──│ Hooks & Components │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 3D Animation Layer │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Gesture │ │ IK System │ │ Animation │ │ │
│ │ │ Manager │──│ (CCD Solver) │──│ Mixer │ │ │
│ │ │ (22 Gestures) │ │ │ │ (THREE.js) │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ AI Animation Services │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌─────────────────────┐ │ │
│ │ │ Facial/LipSync│ │ Skeletal │ │ Movement │ │ │
│ │ │ Animation │──│ Animation │──│ Meditation │ │ │
│ │ │ │ │ │ │ (Tai Chi/Qigong) │ │ │
│ │ └───────────────┘ └───────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
UI Animation Layer#
1. Animation Tokens#
Location: web/src/lib/animation-tokens.ts
Design system tokens providing consistent animation parameters across the platform.
Duration Tokens#
| Token | Value | Use Case |
|---|---|---|
instant |
0ms | No animation |
fastest |
50ms | Micro-interactions |
faster |
100ms | Quick feedback |
fast |
150ms | Snappy transitions |
normal |
200ms | Standard transitions |
slow |
300ms | Emphasized transitions |
slower |
500ms | Complex animations |
verySlow |
1000ms | Dramatic effects |
Easing Functions#
| Category | Functions |
|---|---|
| Linear | linear |
| Standard | easeIn, easeOut, easeInOut |
| Emphasized | sharp, emphasized, emphasizedDecel, emphasizedAccel |
| Special | bounce, smooth, snappy |
Spring Physics Presets#
| Preset | Stiffness | Damping | Mass | Use Case |
|---|---|---|---|---|
gentle |
100 | 14 | 1 | Subtle movements |
default |
170 | 26 | 1 | Standard animations |
wobbly |
180 | 12 | 1 | Playful bounce |
stiff |
210 | 20 | 1 | Responsive feedback |
slow |
280 | 60 | 1 | Heavy elements |
molasses |
280 | 120 | 1 | Very slow, smooth |
Transform Tokens#
// Scale tokens
scale: {
hidden: 0,
small: 0.5,
normal: 1,
large: 1.2,
double: 2.0
}
// Rotation tokens
rotation: {
tiltLeft: -5,
tiltRight: 5,
quarter: 90,
half: 180,
threeQuarter: 270,
full: 360
}
// Distance tokens
distance: {
tiny: 4,
small: 8,
medium: 16,
large: 24,
larger: 32,
huge: 48,
fullViewport: '100%'
}
2. Animation Presets#
Location: web/src/lib/animation-presets.ts
Pre-configured animation configurations for common use cases.
Preset Categories#
| Category | Presets | Description |
|---|---|---|
| Fade | in, out, inScale, outScale |
Opacity transitions |
| Slide | inLeft/Right/Top/Bottom, outLeft/Right/Top/Bottom |
Directional slides |
| Scale | in, out, inZero, outZero, inBounce, pop |
Size transitions |
| Rotate | inClockwise/Counterclockwise, outClockwise/Counterclockwise, spin |
Rotation effects |
| Zoom | in, out, inBig, outBig |
Zoom effects |
| Flip | inX/Y, outX/Y |
3D flip with preserve-3d |
| Bounce | in, out |
Elastic animations |
| Blur | in, out |
Focus transitions |
| Interaction | lift, scaleUp, press, glow, shake, pulse |
User interaction feedback |
Configuration Structure#
interface AnimationConfig {
initial: AnimationKeyframe; // Pre-animation state
final: AnimationKeyframe; // Post-animation state
duration?: Duration;
easing?: Easing;
delay?: Delay;
css?: Record<string, string>; // Additional CSS properties
}
// Example: fadeIn preset
const fadeIn: AnimationConfig = {
initial: { opacity: 0 },
final: { opacity: 1 },
duration: 'normal',
easing: 'easeOut',
};
// Example: slideInLeft preset
const slideInLeft: AnimationConfig = {
initial: { opacity: 0, translateX: -24 },
final: { opacity: 1, translateX: 0 },
duration: 'slow',
easing: 'emphasizedDecel',
};
3. Animation Utilities#
Location: web/src/lib/animation-utils.ts
Core utility functions for animation construction and management.
CSS Generation#
// Build CSS transition string
buildTransition(properties: string[], duration: Duration, easing: Easing): string
// Result: "opacity 200ms ease-out, transform 200ms ease-out"
// Build CSS animation string
buildAnimation(name: string, duration: Duration, easing: Easing, config?: AnimationOptions): string
// Result: "fadeIn 200ms ease-out forwards"
// Build multi-transform chain
buildTransform(transforms: TransformConfig): string
// Result: "translate3d(10px, 20px, 0) rotate(45deg) scale(1.2)"
// Generate @keyframes CSS
generateKeyframes(name: string, keyframes: AnimationKeyframe[]): string
Physics & Interpolation#
// Linear interpolation
interpolate(start: number, end: number, progress: number): number
// Bounds checking
clamp(value: number, min: number, max: number): number
// Easing function calculator
ease(progress: number, easingFn: Easing): number
// Spring physics simulation
spring(current: number, target: number, velocity: number, config: SpringConfig): SpringResult
// Check if spring has settled
isSpringAtRest(current: number, target: number, velocity: number, threshold?: number): boolean
Performance Optimization#
// Enable GPU acceleration
enableGPUAcceleration(element: HTMLElement): void
// Adds: transform: translateZ(0), backfaceVisibility: hidden
// Apply will-change hint
applyWillChange(element: HTMLElement, properties: string[]): void
// Remove will-change (call after animation)
removeWillChange(element: HTMLElement): void
// Batch DOM updates via RAF
batchDOMUpdates(updates: Array<() => void>): void
FLIP Technique#
// First, Last, Invert, Play animation technique
flip(
element: HTMLElement,
getNewState: () => void,
options?: FLIPOptions
): Promise<void>
// Usage
await flip(card, () => {
card.classList.toggle('expanded');
});
Animation State Machine#
// Create state machine for animation lifecycle
const stateMachine = createAnimationStateMachine();
// States: idle → entering → entered → exiting → exited
stateMachine.transition('entering');
console.log(stateMachine.getState()); // 'entering'
RAF Animation Loop#
// Create animation loop with deltaTime tracking
const loop = createAnimationLoop((deltaTime: number) => {
// Update animation based on elapsed time
position += velocity * deltaTime;
});
loop.start();
loop.stop();
4. React Animation Hooks#
Location: web/src/hooks/use-animation.ts
React hooks for declarative animation management.
Core Hooks#
// Detect user's reduced motion preference
const prefersReducedMotion = useReducedMotion();
// Apply animation to element
const { ref, style, isAnimating } = useAnimation({
preset: 'fadeIn',
duration: 'normal',
delay: 'short',
onComplete: () => console.log('Animation complete'),
});
// Track animation state
const { state, enter, exit } = useAnimationState();
// state: 'idle' | 'entering' | 'entered' | 'exiting' | 'exited'
// Physics-based spring animation
const { value, set } = useSpring({
from: 0,
to: 100,
config: 'wobbly',
});
Interaction Hooks#
// Gesture-triggered animations
const gestureProps = useGesture({
onHover: { scale: 1.1 },
onPress: { scale: 0.95 },
onDrag: true,
});
// FLIP technique hook
const flipRef = useFLIP();
List Animation Hooks#
// Staggered animations for lists
const { containerRef, itemProps } = useStagger({
stagger: 'normal',
preset: 'slideInLeft',
});
// Mount/unmount animations
const { ref, isVisible } = useMountAnimation({
enter: 'fadeIn',
exit: 'fadeOut',
});
// Exit animation support (like Framer Motion)
const { isPresent, safeToRemove } = usePresence();
5. Animation Components#
Location: web/src/components/Animation.tsx
Declarative animation components for common patterns.
Base Components#
// Generic animation wrapper
<Animated preset="fadeIn" delay="short">
<Card />
</Animated>
// Specific animation types
<Fade in={isVisible}>
<Modal />
</Fade>
<Slide direction="left" in={isOpen}>
<Sidebar />
</Slide>
<Scale in={isActive} bounce>
<Button />
</Scale>
<Rotate turns={1} duration="slow">
<Icon />
</Rotate>
<Zoom in={isExpanded}>
<Image />
</Zoom>
List & Presence Components#
// Staggered children animations
<Stagger stagger="normal" preset="slideInUp">
{items.map(item => (
<Card key={item.id} />
))}
</Stagger>
// Exit animations
<AnimatePresence>
{isVisible && (
<Modal key="modal" exit="fadeOut" />
)}
</AnimatePresence>
// Conditional reduced motion rendering
<ReducedMotion fallback={<StaticContent />}>
<AnimatedContent />
</ReducedMotion>
Gesture Components#
Location: web/src/components/GestureAnimation.tsx
// Hover state animations
<Hover scale={1.05} lift>
<Card />
</Hover>
// Press/click animations
<Press scale={0.95}>
<Button />
</Press>
// Drag interaction
<Draggable
onDragStart={handleStart}
onDragEnd={handleEnd}
bounds="parent"
>
<DraggableItem />
</Draggable>
// Spring-based interactions
<SpringInteractive config="wobbly">
<BouncyButton />
</SpringInteractive>
// Material Design ripple
<Ripple color="primary">
<Button />
</Ripple>
3D Avatar Animation#
1. Gesture System#
Location: web/src/lib/avatar-gesture-system.ts
Comprehensive gesture library for avatar expression and communication.
Gesture Library (22 Types)#
| Category | Gestures | Description |
|---|---|---|
| Basic | idle, stand |
Default states |
| Social | wave, clap, bow, point, thumbsup, thumbsdown, nod, shake-head |
Communication gestures |
| Emote | dance, shrug, thinking, confused, celebrate, cry, laugh |
Emotional expressions |
| Movement | walk, run, jump |
Locomotion |
| Meditation | sit, namaste, meditate |
Spiritual gestures |
Gesture Configuration#
interface GestureConfig {
id: GestureType;
displayName: string;
icon: string; // Emoji representation
description: string;
duration: number; // Seconds
loop: boolean; // Continuous playback
priority: number; // Higher interrupts lower
proceduralAnimation?: ProceduralAnimationFn;
clipName?: string; // GLB/GLTF animation name
category: 'basic' | 'social' | 'emote' | 'movement' | 'meditation';
networked: boolean; // Sync across network
}
Gesture Manager#
import { AvatarGestureManager } from '@/lib/avatar-gesture-system';
const gestureManager = new AvatarGestureManager(avatarModel);
// Play a gesture
gestureManager.playGesture('wave');
// Play immediately (skip queue)
gestureManager.playGesture('bow', true);
// Stop current gesture
gestureManager.stopGesture();
// Update in render loop
function animate() {
const delta = clock.getDelta();
gestureManager.update(delta);
renderer.render(scene, camera);
requestAnimationFrame(animate);
}
// Query available gestures
const gestures = gestureManager.getAvailableGestures();
const socialGestures = gestureManager.getGesturesByCategory('social');
// Queue management
const queue = gestureManager.getQueue();
gestureManager.clearQueue();
Procedural Animation#
When GLB clips are unavailable, procedural animations provide fallback:
interface ProceduralAnimationResult {
positionOffset?: THREE.Vector3;
rotationOffset?: THREE.Euler;
scaleOffset?: THREE.Vector3;
armPositions?: {
left: THREE.Vector3;
right: THREE.Vector3;
};
legPositions?: {
left: THREE.Vector3;
right: THREE.Vector3;
};
}
// Example: Wave procedural animation
const waveAnimation = (time: number): ProceduralAnimationResult => ({
armPositions: {
right: new THREE.Vector3(
0.8 + Math.sin(time * 8) * 0.2, // Side-to-side wave
1.5 + Math.sin(time * 4) * 0.1, // Up-down motion
0.3
),
left: new THREE.Vector3(-0.3, 0.5, 0), // Neutral position
},
});
Animation Blending#
// Fade durations
const FADE_IN_DURATION = 0.2; // 200ms
const FADE_OUT_DURATION = 0.3; // 300ms
// AnimationMixer handles blending
mixer.clipAction(newClip).fadeIn(FADE_IN_DURATION).play();
currentAction.fadeOut(FADE_OUT_DURATION);
2. Inverse Kinematics (IK) System#
Location: web/src/lib/avatar-ik-system.ts
Real-time bone manipulation for natural, responsive avatar movement.
IK Solver#
Uses THREE.js CCDIKSolver (Cyclic Coordinate Descent) for efficient IK calculations.
interface IKChainConfig {
target: string; // Target bone name
effector: string; // End effector bone name
links: Array<{
index: number;
name?: string;
limitation?: THREE.Vector3; // Rotation constraints (radians)
}>;
iteration?: number; // Solver iterations (default: 1)
minAngle?: number; // Minimum angle change
}
Bone Naming (VRM/ReadyPlayerMe Compatible)#
Spine Chain: Hips → Spine → Spine1 → Spine2 → Neck → Head
Left Arm: LeftShoulder → LeftArm → LeftForeArm → LeftHand
Right Arm: RightShoulder → RightArm → RightForeArm → RightHand
Left Leg: LeftUpLeg → LeftLeg → LeftFoot → LeftToe
Right Leg: RightUpLeg → RightLeg → RightFoot → RightToe
Eyes: LeftEye, RightEye
AvatarIKSystem Usage#
import { AvatarIKSystem } from '@/lib/avatar-ik-system';
const ikSystem = new AvatarIKSystem(avatarModel);
// Look-At Control
ikSystem.setLookAtTarget(targetPosition);
ikSystem.setLookAtStrength(0.8); // 0-1
ikSystem.setLookAtSmoothing(0.9); // 0-1
// Hand Reaching
ikSystem.setHandTarget('left', leftTargetPosition);
ikSystem.setHandTarget('right', rightTargetPosition);
// Convenience Methods
ikSystem.pointAt(targetPosition, 'right'); // Point at with right hand
ikSystem.wave('right'); // Wave gesture
// Ground Placement
ikSystem.setGroundLevel('left', groundY);
ikSystem.setGroundLevel('right', groundY);
// Update in render loop
function animate() {
ikSystem.update(delta);
renderer.render(scene, camera);
}
// Query bone positions
const handPos = ikSystem.getBoneWorldPosition('LeftHand');
const handRot = ikSystem.getBoneWorldRotation('LeftHand');
// List available bones
const bones = ikSystem.listBones();
// Debug visualization
ikSystem.setDebugMode(true); // Shows CCDIKHelper
// Reset to neutral pose
ikSystem.reset();
IK Behavior Presets#
// Quick pointing
ikSystem.pointAt(objectPosition, 'right');
// Wave gesture with height
ikSystem.wave('right'); // Hand at shoulder height
// Look at with adjustable intensity
ikSystem.lookAt(targetPosition, 0.5); // 50% strength
// Reset all IK influences
ikSystem.reset();
AI-Driven Animation Services#
1. Facial Animation & Lip-Sync#
Location: services/ai/src/facial-animation-lipsync/
Generates realistic facial animations synchronized with speech.
Phoneme System#
39 English phonemes (ARPAbet notation):
Vowels: AA, AE, AH, AO, AW, AY, EH, ER, EY, IH, IY, OW, OY, UH, UW
Consonants: B, CH, D, DH, F, G, HH, JH, K, L, M, N, NG, P, R, S, SH, T, TH, V, W, Y, Z, ZH
Silence: SIL
Viseme Library (15 Visemes)#
| Viseme | Mouth Shape | Phonemes |
|---|---|---|
sil |
Closed/neutral | Silence |
PP |
Lips pressed | P, B, M |
FF |
Lower lip to teeth | F, V |
TH |
Tongue between teeth | TH, DH |
DD |
Tongue to ridge | T, D, N |
kk |
Back of tongue raised | K, G, NG |
CH |
Lips rounded, tongue raised | CH, JH, SH, ZH |
SS |
Teeth close, tongue forward | S, Z |
nn |
Tongue to palate | L |
RR |
Lips slightly rounded | R |
aa |
Mouth open wide | AA, AE, AH |
E |
Mouth slightly open | EH, EY |
ih |
Mouth open, lips relaxed | IH, IY |
oh |
Lips rounded | AO, OW |
ou |
Lips pursed | OO, UH, UW |
Speaker Styles (9 Profiles)#
| Style | Mouth Scale | Blinks/min | Characteristics |
|---|---|---|---|
neutral |
1.0x | 15 | Balanced expression |
expressive |
1.3x | 18 | Enhanced movement |
reserved |
0.8x | 12 | Subtle expression |
theatrical |
1.5x | 20 | Maximum expression |
meditative |
0.7x | 8 | Calm, minimal movement |
enthusiastic |
1.4x | 22 | High energy |
gentle |
0.9x | 12 | Warm, soft |
authoritative |
1.1x | 10 | Strong articulation |
Animation Generators#
// Pipeline: Text/Audio → Phonemes → Visemes → Blendshapes → Animation
// 1. Extract phonemes from text or audio
const phonemes = phonemeExtractor.extract(textOrAudio);
// 2. Generate viseme timeline
const visemes = visemeGenerator.generate(phonemes);
// 3. Convert to blendshape weights
const blendshapes = blendshapeGenerator.generate(visemes, emotion);
// 4. Generate eye animations
const eyeAnimation = eyeAnimationGenerator.generate(duration, style);
// 5. Generate head movement
const headAnimation = headAnimationGenerator.generate(duration, style);
// 6. Add micro-expressions
const microExpressions = microExpressionGenerator.generate(duration);
Lip-Sync Output Structure#
interface LipSyncOutput {
animation: {
id: string;
frames: FacialAnimationFrame[]; // Per-frame blendshapes
duration: number;
frameRate: number; // Default: 60 FPS
metadata: AnimationMetadata;
};
phonemeTimeline: PhonemeEvent[];
visemeTimeline: VisemeFrame[];
emotionTimeline?: EmotionalExpression[];
quality: {
syncAccuracy: number;
smoothness: number;
naturalness: number;
};
}
interface FacialAnimationFrame {
time: number;
blendshapes: Record<string, number>; // ARKit blendshape weights
}
Emotion Blendshapes#
12 base emotions with corresponding blendshape configurations:
joy,sadness,anger,fear,disgust,surprisecontempt,serenity,compassion,wonder,concentrationamusement,warmth
Eye Animation Features#
- Blink Patterns: Style-dependent rates (8-22 blinks/minute)
- Natural Intervals: Randomized with variance
- Gaze Saccades: Small, natural eye movements
- Pupil Dilation: Emotion-responsive changes
Micro-Expressions#
- 3 expressions per minute (configurable)
- 100-200ms duration
- Fast fade-in (30ms) / fade-out (50ms)
- Independent of primary emotion
2. Movement Meditation Animation#
Location: services/ai/src/movement-meditation-animation/
Generates Tai Chi, Qigong, and mindful walking sequences.
Multi-Agent Architecture#
┌────────────────────────────────────────────────────────────────────┐
│ Movement Meditation Agents │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ Labyrinth │ │ Walking Path │ │ Pace Variation │ │
│ │ Generator │ │ Agent │ │ Agent │ │
│ │ (7,11-circuit) │ │ (Kinhin, Slow) │ │ (Linear, Wave) │ │
│ └───────────────────┘ └───────────────────┘ └─────────────────┘ │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ Qigong Movement │ │ Tai Chi Movement │ │ Energy │ │
│ │ Agent │ │ Agent │ │ Visualization │ │
│ │ (Ba Duan Jin) │ │ (Yang 24 Form) │ │ Agent │ │
│ └───────────────────┘ └───────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐│
│ │ Breath Sync Agent ││
│ │ (Timeline, Cues, Synchronization) ││
│ └─────────────────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────────────┘
Labyrinth Generator#
type LabyrinthStyle =
| 'classical_7' // Classical 7-circuit
| 'chartres_11' // Chartres Cathedral 11-circuit
| 'classical_11' // Classical 11-circuit variant
| 'cretan'; // Ancient Cretan design
interface LabyrinthPath {
circuits: number;
waypoints: Point2D[];
segments: PathSegment[];
totalLength: number;
}
Walking Meditation Styles#
| Style | Speed | Characteristics |
|---|---|---|
kinhin |
Moderate | Zen walking, straight paths, mindful turns |
theravada_slow |
Very slow (~0.2 units/s) | Step phases: lift, move, place |
labyrinth |
Slow | Following labyrinth path |
mindful_generic |
Variable | Meandering curves |
Qigong Movement Forms#
Eight Pieces of Brocade (Ba Duan Jin):
const movements = [
'Two Hands Hold Up the Heavens',
'Drawing the Bow to Shoot the Eagle',
'Separate Heaven and Earth',
'Wise Owl Gazes Backward',
'Sway the Head and Shake the Tail',
'Two Hands Hold the Feet to Strengthen the Kidneys',
'Clench the Fists and Glare Fiercely',
'Bouncing on the Toes',
];
Standing Meditation (Zhan Zhuang):
- Various stance types
- Extended hold durations
- Subtle body adjustments
Tai Chi Movement Forms#
Yang 24 Form:
- Complete form with 24 movements
- Asymmetric arm positions
- Flowing weight transitions
Silk Reeling (Chan Si Gong):
- Spiral movement patterns
- Core-initiated motion
- Continuous flow
Movement Keyframe Structure#
interface MovementKeyframe {
time: number; // 0-1 normalized
bodyPosition: {
stance: StanceType;
spineAlignment: SpineAlignment;
headPosition: Point3D;
torsoRotation: number; // degrees
kneeBend: number; // 0-1
};
armPositions: {
leftArm: ArmPosition;
rightArm: ArmPosition;
symmetry: 'mirrored' | 'asymmetric';
};
handPositions: {
leftHand: HandPosition;
rightHand: HandPosition;
};
weight: {
leftFoot: number; // 0-1
rightFoot: number; // 0-1
forward: number; // 0-1
rooted: number; // 0-1
};
intention: string; // Internal focus cue
}
Stance Types#
type StanceType =
| 'wu_ji' // Standing meditation
| 'horse' // Wide stance
| 'bow' // Front-weighted
| 'empty' // Back-weighted
| 'cat' // Light front foot
| 'rooster' // Single leg
| 'sitting'; // Low stance
Energy Visualization#
interface EnergyVisualization {
particles: {
count: number; // 50+ × intensity
color: Color;
size: number;
emitRate: number;
};
trails: {
path: 'central_channel' | 'arm_channels' | 'leg_channels';
color: Color;
width: number;
flow: 'ascending' | 'descending';
};
auras: {
position: 'lower_dantian' | 'middle_dantian' | 'upper_dantian';
color: Color;
intensity: number;
pulseFrequency: number;
};
}
Breath Synchronization#
interface BreathTimeline {
phases: Array<{
type: 'inhale' | 'exhale' | 'hold';
duration: number;
startTime: number;
cue: string; // Awareness instruction
}>;
movementSync: Array<{
movementPhase: string;
breathPhase: 'inhale' | 'exhale';
}>;
}
Performance Optimization#
GPU Acceleration#
// Enable hardware acceleration for animated elements
enableGPUAcceleration(element);
// Adds: transform: translateZ(0), backfaceVisibility: hidden
// Apply will-change before animation
applyWillChange(element, ['transform', 'opacity']);
// Remove will-change after animation (prevents memory leaks)
removeWillChange(element);
Animation Loop Best Practices#
// Use deltaTime for frame-independent animation
const loop = createAnimationLoop((deltaTime: number) => {
// Frame-rate independent updates
position += velocity * deltaTime;
// Batch DOM updates
batchDOMUpdates([
() => (element1.style.transform = `translateX(${position}px)`),
() => (element2.style.opacity = opacity.toString()),
]);
});
Reduced Motion Support#
// Check user preference
const prefersReducedMotion = window.matchMedia(
'(prefers-reduced-motion: reduce)'
).matches;
// Get safe duration (returns 0 if reduced motion preferred)
const duration = getSafeDuration('normal');
// Component-level handling
<ReducedMotion fallback={<StaticVersion />}>
<AnimatedVersion />
</ReducedMotion>
3D Animation Optimization#
| Technique | Description |
|---|---|
| Clip Caching | Pre-load and cache animation clips |
| Bone Caching | Cache bone references to avoid traversal |
| LOD Integration | Reduce animation complexity at distance |
| Procedural Fallbacks | Use simpler procedural animations when clips unavailable |
| Update Throttling | Reduce IK update frequency for distant avatars |
Network Synchronization#
Gesture Networking#
interface GestureNetworkMessage {
type: 'gesture';
participantId: string;
gestureType: GestureType;
timestamp: number;
priority: number;
}
// Send gesture to network
gestureManager.playGesture('wave');
network.broadcast({
type: 'gesture',
participantId: myId,
gestureType: 'wave',
timestamp: Date.now(),
priority: 5,
});
// Receive gesture from network
network.on('gesture', (message) => {
const avatar = getAvatarById(message.participantId);
avatar.gestureManager.playGesture(message.gestureType);
});
Animation State Sync#
For continuous animations (movement, meditation):
- Position updates at 20Hz
- Keyframe interpolation on client
- Dead reckoning for smooth playback
- Correction blending when state diverges
Integration Examples#
Complete Avatar Setup#
import { AvatarGestureManager } from '@/lib/avatar-gesture-system';
import { AvatarIKSystem } from '@/lib/avatar-ik-system';
// Initialize systems
const gestureManager = new AvatarGestureManager(avatarModel);
const ikSystem = new AvatarIKSystem(avatarModel);
// Configure IK behaviors
ikSystem.setLookAtTarget(cameraPosition);
ikSystem.setLookAtStrength(0.7);
ikSystem.setLookAtSmoothing(0.9);
// Animation loop
const clock = new THREE.Clock();
function animate() {
const delta = clock.getDelta();
// Update animation systems
gestureManager.update(delta);
ikSystem.update(delta);
// Render
renderer.render(scene, camera);
requestAnimationFrame(animate);
}
animate();
// Play gestures in response to user input
document.addEventListener('keydown', (e) => {
if (e.key === 'w') gestureManager.playGesture('wave');
if (e.key === 'b') gestureManager.playGesture('bow');
if (e.key === 'm') gestureManager.playGesture('meditate');
});
Lip-Sync with Speech#
import { FacialAnimationService } from '@/services/ai/facial-animation-lipsync';
const facialService = new FacialAnimationService();
async function speak(text: string, emotion: Emotion) {
// Generate facial animation
const animation = await facialService.generate({
text,
emotion,
speakerStyle: 'expressive',
});
// Apply to avatar
let frameIndex = 0;
const interval = setInterval(() => {
if (frameIndex >= animation.frames.length) {
clearInterval(interval);
return;
}
const frame = animation.frames[frameIndex];
applyBlendshapes(avatar, frame.blendshapes);
frameIndex++;
}, 1000 / animation.frameRate);
}
Meditation Movement Session#
import { MovementMeditationService } from '@/services/ai/movement-meditation';
const meditationService = new MovementMeditationService();
async function startQigongSession() {
// Generate movement sequence
const session = await meditationService.generate({
style: 'qigong',
form: 'eight_pieces_of_brocade',
duration: 600, // 10 minutes
includeBreathSync: true,
includeEnergyVisualization: true,
});
// Play movement keyframes
for (const movement of session.movements) {
await playMovement(avatar, movement);
// Show breath cue
updateBreathCue(movement.breathPhase);
// Update energy visualization
updateEnergyParticles(movement.energyFlow);
}
}
Best Practices#
Do's#
- Use animation tokens for consistent timing across the platform
- Respect
prefers-reduced-motionfor accessibility - Apply
will-changebefore animations, remove after - Use FLIP technique for layout animations
- Blend gestures smoothly with fade in/out
- Cache bone references in IK system
- Use procedural fallbacks when clips unavailable
Don'ts#
- Don't animate layout properties (width, height, top, left)
- Don't create new animation clips every frame
- Don't ignore reduced motion preferences
- Don't leave
will-changeapplied permanently - Don't update IK for off-screen avatars
- Don't skip animation blending (causes jarring transitions)
Related Documentation#
Last Updated: January 2026