Eve library

Metaverse Avatar System

Guide

Revision 1

On this page

Technical documentation for Lilith's avatar creation, customization, and animation system.

Overview#

The Lilith platform implements a dual-approach avatar system featuring both procedural avatar generation for meditation guides and Ready Player Me integration for high-fidelity user avatars. The system supports comprehensive customization, real-time animation, and spiritual archetype theming.

Architecture#

text
┌─────────────────────────────────────────────────────────────┐
│                  Avatar Manager                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Multi-Avatar Registry                    │   │
│  └─────────────────────────┬───────────────────────────┘   │
└─────────────────────────────┼───────────────────────────────┘
                              │
        ┌─────────────────────┴─────────────────────┐
        │                                           │
┌───────▼───────────────┐               ┌──────────▼──────────┐
│  Procedural Avatars   │               │   Ready Player Me   │
│  ┌─────────────────┐  │               │  ┌────────────────┐ │
│  │   Geometry      │  │               │  │  GLTF Loader   │ │
│  │   System        │  │               │  │                │ │
│  └─────────────────┘  │               │  └────────────────┘ │
│  ┌─────────────────┐  │               │  ┌────────────────┐ │
│  │   Accessories   │  │               │  │  Cache Layer   │ │
│  │   System        │  │               │  │                │ │
│  └─────────────────┘  │               │  └────────────────┘ │
│  ┌─────────────────┐  │               └─────────────────────┘
│  │   Aura Effects  │  │
│  └─────────────────┘  │
└───────────────────────┘
        │
┌───────▼───────────────────────────────────────────────────┐
│                    Animation Layer                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Gesture  │  │Breathing │  │    IK    │  │  Network │  │
│  │ System   │  │ Patterns │  │  System  │  │   Sync   │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└───────────────────────────────────────────────────────────┘

Archetype System#

The avatar system features 8 spiritual archetype presets designed for meditation and contemplative experiences.

Available Archetypes#

Archetype Skin Robe Style Accessories Aura Height
Stoic Sage #d4a574 #8b7355 Simple Book — 1.80m
Zen Master #e8d5b7 #2f4f4f Simple Beads Sky Blue 1.70m
Sufi Mystic #c68642 #4b0082 Ornate Beads, Candles Purple 1.75m
Tibetan Monk #d4a574 #8b0000 Traditional Beads, Book — 1.70m
Vedic Teacher #8b5a3c #ff8c00 Traditional Beads, Crystals Gold 1.75m
Modern Therapist #f5deb3 #4682b4 Modern Book — 1.75m
Nature Shaman #a0826d #228b22 Simple Staff, Crystals Green 1.80m
Cosmic Guide #e6e6fa #4b0082 Ornate Crystals, Staff Purple 1.85m

Archetype Configuration#

typescript
interface PersonaAvatarConfig {
  id: string;
  archetype: ArchetypeType;
  position?: THREE.Vector3;
  rotation?: THREE.Euler;
  scale?: number;
  customAppearance?: Partial<AvatarAppearance>;
  readyPlayerMe?: ReadyPlayerMeOptions;
}

type ArchetypeType =
  | 'stoic-sage'
  | 'zen-master'
  | 'sufi-mystic'
  | 'tibetan-monk'
  | 'vedic-teacher'
  | 'modern-therapist'
  | 'nature-shaman'
  | 'cosmic-guide';

Body Customization#

Location: web/src/lib/persona-avatar-geometry.ts

Body Structure#

The procedural avatar body consists of:

Component Geometry Dimensions Notes
Torso CapsuleGeometry 0.25r × 0.5h 15° forward tilt for meditation pose
Legs CapsuleGeometry × 2 0.12r × 0.4h Crossed-leg meditation position
Arms CapsuleGeometry × 2 0.08r × 0.4h Meditation hand placement
Hands SphereGeometry × 2 0.08r Positioned for gestures
Head SphereGeometry 0.15r 16×16 segments

Body Types#

typescript
type BodyType = 'slender' | 'average' | 'sturdy';

Appearance Parameters#

typescript
interface AvatarAppearance {
  height: number; // 1.5 - 2.0 meters
  skinTone: string; // Hex color (e.g., #d4a574)
  bodyType: BodyType;
  robeColor: string; // Hex color
  robeStyle: 'simple' | 'ornate' | 'traditional' | 'modern';
}

Material Properties#

typescript
const skinMaterial = new THREE.MeshStandardMaterial({
  color: skinTone,
  roughness: 0.8, // Realistic skin texture
  metalness: 0.1, // Subtle shine
});

Face Customization#

Facial Components#

Component Geometry Positioning
Head SphereGeometry (0.15r, 16×16) Y: 0.9
Eyes SphereGeometry × 2 (0.02r) Y: 0.88, Z: 0.05
Nose ConeGeometry (0.02r, 0.05h) Y: 0.85, Z: 0.15
Hood (optional) Semi-sphere (0.18r) Y: 0.95, Z: -0.05

Eye Material#

typescript
const eyeMaterial = new THREE.MeshStandardMaterial({
  color: '#2a2a2a',
  roughness: 0.3, // Realistic shine
  metalness: 0.0,
});

Clothing & Accessories System#

Location: web/src/lib/persona-avatar-accessories.ts

Robe System#

typescript
// Base robe geometry
const robeGeometry = new THREE.CylinderGeometry(
  0.4, // Top radius
  0.6, // Bottom radius
  0.8, // Height
  16 // Segments
);

const robeMaterial = new THREE.MeshStandardMaterial({
  color: robeColor,
  roughness: 0.9,
  metalness: 0.05,
  side: THREE.DoubleSide,
});

Available Accessories#

Beads (Traditional Mala)#

  • 108 spherical beads in circular arrangement
  • Brown material (#8b4513)
  • Positioned around neck
typescript
function createBeads(): THREE.Group {
  const group = new THREE.Group();
  const beadCount = 108;
  const radius = 0.3;

  for (let i = 0; i < beadCount; i++) {
    const angle = (i / beadCount) * Math.PI * 2;
    const bead = new THREE.Mesh(
      new THREE.SphereGeometry(0.008),
      new THREE.MeshStandardMaterial({ color: '#8b4513' })
    );
    bead.position.set(Math.cos(angle) * radius, 0.6, Math.sin(angle) * radius);
    group.add(bead);
  }
  return group;
}

Staff with Crystal#

  • Cylindrical staff (1.5m height)
  • OctahedronGeometry crystal top
  • Emissive purple glow
typescript
interface StaffConfig {
  height: number; // Default: 1.5
  radius: number; // Default: 0.02
  woodColor: string; // Default: #8b7355
  crystalColor: string; // Default: #9370db
  emissiveIntensity: number; // Default: 0.3
}

Book#

  • BoxGeometry (0.15 × 0.2 × 0.03)
  • Leather brown material
  • Positioned for meditation pose

Crystals#

  • 3 OctahedronGeometry crystals
  • Colors: Hot pink, Purple, Cyan
  • Transparent with 0.8 opacity

Animated Candles#

  • Two candles with dynamic flame animation
  • PointLight per candle (0.5 intensity)
  • Flame flickers at 10-15Hz
typescript
function animateCandles(candles: CandleGroup, time: number): void {
  for (const candle of candles) {
    const flicker = Math.sin(time * 12) * 0.5 + 0.5;
    candle.flame.scale.set(flicker, 1 + flicker * 0.3, flicker);
    candle.flame.position.y += Math.sin(time * 15) * 0.002;
  }
}

Animation System#

Location: web/src/lib/avatar-gesture-system.ts

Gesture Types#

The system supports 22 gesture types organized by category:

Basic Gestures#

Gesture Duration Priority Loop
Idle Continuous 0 Yes
Stand Transition 1 No
Sit Transition 1 No

Movement#

Gesture Duration Priority Loop
Walk Continuous 2 Yes
Run Continuous 3 Yes
Jump 1 second 4 No

Social Gestures#

Gesture Duration Priority Description
Wave 2 seconds 3 Right arm elevated
Clap Continuous 3 Hands approach/separate
Bow 0.5 seconds 3 45° bend
Point Continuous 2 Arm extended
Namaste 2 seconds 3 Hands together at chest
Nod 1 second 2 Head vertical movement
Shake Head 1 second 2 Head horizontal movement

Emotes#

Gesture Duration Priority Description
Dance Continuous 4 Bobbing + rotation
Celebrate 2 seconds 5 Arms raised, jumping
Thinking Continuous 2 Hand to chin
Confused 1 second 2 Rotation oscillation
Shrug 1 second 2 Shoulder animation
Laugh Continuous 3 Vertical bobbing
Cry Continuous 3 Forward bend

Meditation#

Gesture Duration Priority Description
Meditate Continuous 1 Seated, breathing sync

Gesture Configuration#

typescript
interface GestureDefinition {
  type: GestureType;
  priority: number; // 0-8 (higher interrupts lower)
  duration: number; // 0 = infinite/looping
  loop: boolean;
  category: 'basic' | 'social' | 'emote' | 'movement' | 'meditation';
  glbClipName?: string; // Animation clip from GLB
  procedural?: (avatar: Avatar, time: number) => void;
  networked: boolean; // Sync in multiplayer
}

Animation Manager#

typescript
class AvatarAnimationManager {
  private mixer: THREE.AnimationMixer;
  private currentGesture: GestureType;
  private queue: GestureType[];

  play(gesture: GestureType): void {
    if (this.canInterrupt(gesture)) {
      this.transition(gesture);
    } else {
      this.queue.push(gesture);
    }
  }

  private transition(gesture: GestureType): void {
    const current = this.getCurrentAction();
    const next = this.getAction(gesture);

    current?.fadeOut(0.2);
    next?.reset().fadeIn(0.3).play();

    this.currentGesture = gesture;
  }

  update(deltaTime: number): void {
    this.mixer.update(deltaTime);
    this.processQueue();
  }
}

Breathing System#

Each archetype has a unique breathing pattern synchronized with visual animation.

Breathing Patterns#

Archetype Inhale Hold Exhale Cycle
Stoic Sage 4s 4s 4s 12s
Zen Master 5s 5s 5s 15s
Sufi Mystic 3s 2s 4s 9s
Tibetan Monk 4s 2s 6s 12s
Vedic Teacher 4s 4s 4s 12s
Modern Therapist 3s 1s 4s 8s
Nature Shaman 4s 3s 5s 12s
Cosmic Guide 6s 4s 8s 18s

Breathing Animation#

typescript
function updateBreathing(avatar: Avatar, time: number): void {
  const pattern = avatar.breathingPattern;
  const cycleTime = time % pattern.totalCycle;

  let scale = 1.0;

  if (cycleTime < pattern.inhale) {
    // Inhaling - expand
    scale = 1.0 + 0.05 * (cycleTime / pattern.inhale);
  } else if (cycleTime < pattern.inhale + pattern.hold) {
    // Holding - maintain
    scale = 1.05;
  } else {
    // Exhaling - contract
    const exhaleProgress =
      (cycleTime - pattern.inhale - pattern.hold) / pattern.exhale;
    scale = 1.05 - 0.05 * exhaleProgress;
  }

  avatar.torso.scale.set(scale, 1, scale);
}

IK System#

Location: web/src/lib/avatar-ik-system.ts

Standard Humanoid Skeleton#

text
Hips
├── Spine → Spine1 → Spine2 → Neck → Head
│                                    ├── LeftEye
│                                    └── RightEye
├── LeftUpLeg → LeftLeg → LeftFoot → LeftToe
├── RightUpLeg → RightLeg → RightFoot → RightToe
├── LeftShoulder → LeftArm → LeftForeArm → LeftHand
└── RightShoulder → RightArm → RightForeArm → RightHand

Look-At System#

typescript
interface LookAtConfig {
  target: THREE.Vector3;
  strength: number; // 0-1 blend amount
  smoothing: number; // 0-1 (higher = faster)
}

class IKController {
  setLookAtTarget(target: THREE.Vector3, config?: Partial<LookAtConfig>): void {
    this.headTarget = target;
    this.lookAtStrength = config?.strength ?? 1.0;
    this.lookAtSmoothing = config?.smoothing ?? 0.1;
  }

  update(): void {
    if (this.headTarget && this.headBone) {
      const targetQuat = this.calculateLookAtQuaternion(this.headTarget);
      this.headBone.quaternion.slerp(targetQuat, this.lookAtSmoothing);
    }
  }
}

Hand Reaching#

typescript
// Reach toward target
ikController.setHandTarget('right', targetPosition);

// Point at object
ikController.pointAt(targetPosition, 'right');

// Reset to idle
ikController.clearTargets();

Ground Placement#

typescript
// Snap feet to terrain
ikController.setGroundLevel(0); // Y position

// Per-foot adjustment
ikController.setFootPosition('left', leftGroundY);
ikController.setFootPosition('right', rightGroundY);

Aura Effects#

Location: web/src/lib/persona-avatar-aura.ts

Aura Configuration#

Archetype Color Intensity
Zen Master #87ceeb (Sky Blue) 0.3
Sufi Mystic #9370db (Purple) 0.5
Vedic Teacher #ffd700 (Gold) 0.4
Nature Shaman #32cd32 (Green) 0.6
Cosmic Guide #9370db (Purple) 0.8

Particle System#

typescript
function createAura(color: string, intensity: number): THREE.Points {
  const particleCount = 200;
  const positions = new Float32Array(particleCount * 3);

  // Spherical distribution
  for (let i = 0; i < particleCount; i++) {
    const theta = Math.random() * Math.PI * 2;
    const phi = Math.random() * Math.PI;
    const radius = 0.5 + Math.random() * 0.3;

    positions[i * 3] = radius * Math.sin(phi) * Math.cos(theta);
    positions[i * 3 + 1] = radius * Math.cos(phi) + 0.5;
    positions[i * 3 + 2] = radius * Math.sin(phi) * Math.sin(theta);
  }

  const geometry = new THREE.BufferGeometry();
  geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));

  const material = new THREE.PointsMaterial({
    color: color,
    size: 0.02,
    transparent: true,
    opacity: intensity * 0.6,
    blending: THREE.AdditiveBlending,
  });

  return new THREE.Points(geometry, material);
}

Animation#

typescript
function animateAura(aura: THREE.Points, time: number): void {
  aura.rotation.y = time * 0.2; // Slow rotation
}

Ready Player Me Integration#

Location: web/src/lib/ready-player-me-avatar.ts

Configuration#

typescript
interface ReadyPlayerMeOptions {
  profileId: string; // RPM avatar UUID
  bodyType?: 'fullbody' | 'halfbody'; // Default: fullbody
  gender?: 'male' | 'female' | 'neutral';
  textureSize?: 512 | 1024 | 2048 | 4096;
  meshLod?: 'mobile' | 'standard' | 'high';
  morphTargets?: string[];
  pose?: string;
  expression?: string;
  scale?: number; // Default: 1.0
  yOffset?: number; // For seated poses
  autoHideProcedural?: boolean; // Default: true
}

Loading Avatar#

typescript
const avatarService = new ReadyPlayerMeAvatarService();

// Load with caching
const avatar = await avatarService.loadAvatar('profile-uuid', {
  bodyType: 'fullbody',
  meshLod: 'high',
  textureSize: 1024,
});

// Force reload
const freshAvatar = await avatarService.loadAvatar('profile-uuid', {
  forceReload: true,
});

// Check cache
if (avatarService.isAvatarCached('profile-uuid')) {
  // Use cached version
}

Integration with Procedural#

typescript
const avatar = manager.createAvatar({
  id: 'guide',
  archetype: 'zen-master',
  readyPlayerMe: {
    profileId: 'abc-123',
    autoHideProcedural: true, // Hide procedural when RPM loads
    scale: 1.0,
    yOffset: -0.5, // For meditation pose
  },
});

// Wait for RPM to load
await avatar.whenRemoteAvatarReady();

Avatar Manager#

Location: web/src/lib/persona-avatar-system.ts

Usage#

typescript
import { PersonaAvatarManager } from '@/lib/persona-avatar-system';

const manager = new PersonaAvatarManager(scene);

// Create avatar
const avatar = manager.createAvatar({
  id: 'meditation-guide',
  archetype: 'zen-master',
  position: new THREE.Vector3(0, 0, -3),
  rotation: new THREE.Euler(0, Math.PI, 0),
});

// Play gesture
avatar.playGesture('namaste');

// Update in render loop
function animate(time: number) {
  manager.update(time - lastTime);
  lastTime = time;
  requestAnimationFrame(animate);
}

// Get avatar
const guide = manager.getAvatar('meditation-guide');

// Remove avatar
manager.removeAvatar('meditation-guide');

// Cleanup all
manager.dispose();

Lifecycle#

text
1. createAvatar(config)
   ├── Build procedural geometry
   ├── Add accessories based on archetype
   ├── Initialize aura if configured
   └── Start async RPM loading (if configured)

2. update(deltaTime)
   ├── Update breathing animation
   ├── Update gesture system
   ├── Update IK targets
   ├── Update accessory animations (candles)
   └── Update aura rotation

3. dispose()
   ├── Dispose all geometries
   ├── Dispose all materials
   ├── Remove from scene
   └── Clear references

Network Synchronization#

Gesture Messages#

typescript
interface GestureNetworkMessage {
  type: 'gesture';
  participantId: string;
  gesture: GestureType;
  timestamp: number;
}

// Send gesture
socket.emit('avatar:gesture', {
  type: 'gesture',
  participantId: localAvatar.id,
  gesture: 'wave',
  timestamp: Date.now(),
});

// Receive gesture
socket.on('avatar:gesture', (msg: GestureNetworkMessage) => {
  const avatar = manager.getAvatar(msg.participantId);
  avatar?.playGesture(msg.gesture);
});

Transform Sync#

typescript
interface TransformNetworkMessage {
  type: 'transform';
  participantId: string;
  position: { x: number; y: number; z: number };
  rotation: { x: number; y: number; z: number; w: number };
  timestamp: number;
}

Performance Considerations#

Optimization Tips#

  1. Use LOD for RPM avatars: meshLod: 'mobile' for crowds
  2. Limit particle count: Reduce aura particles for many avatars
  3. Throttle IK updates: Update every 2-3 frames
  4. Pool animations: Reuse AnimationClips across similar avatars
  5. Batch gestures: Queue gestures to prevent rapid switching

Memory Management#

typescript
// Proper cleanup
function removeAvatar(avatar: PersonaAvatar): void {
  // Stop animations
  avatar.stopAllAnimations();

  // Dispose geometries
  avatar.traverse((child) => {
    if (child instanceof THREE.Mesh) {
      child.geometry.dispose();
      if (Array.isArray(child.material)) {
        child.material.forEach((m) => m.dispose());
      } else {
        child.material.dispose();
      }
    }
  });

  // Remove from scene
  scene.remove(avatar.group);
}


Last Updated: January 2026