# Metaverse Avatar System

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

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

```
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

```
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);
}
```

---

## Related Documentation

- [Rendering System](./rendering-system.md)
- [Animation System](./animation-system.md)
- [Networking](./networking.md)
- [Physics System](./physics-system.md)

---

_Last Updated: January 2026_
