Eve library

Metaverse Animation System

Guide

Revision 1

On this page

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#

text
┌─────────────────────────────────────────────────────────────────────────┐
│                        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#

typescript
// 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#

typescript
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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

tsx
// 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#

tsx
// 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

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#

typescript
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#

typescript
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:

typescript
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#

typescript
// 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.

typescript
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)#

text
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#

typescript
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#

typescript
// 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):

text
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#

typescript
// 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#

typescript
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, surprise
  • contempt, serenity, compassion, wonder, concentration
  • amusement, 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#

text
┌────────────────────────────────────────────────────────────────────┐
│                  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#

typescript
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):

typescript
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#

typescript
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#

typescript
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#

typescript
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#

typescript
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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
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#

typescript
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#

typescript
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#

typescript
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-motion for accessibility
  • Apply will-change before 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-change applied permanently
  • Don't update IK for off-screen avatars
  • Don't skip animation blending (causes jarring transitions)


Last Updated: January 2026