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#
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#
type BodyType = 'slender' | 'average' | 'sturdy';
Appearance Parameters#
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#
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#
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#
// 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
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
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
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#
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#
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#
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#
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#
// Reach toward target
ikController.setHandTarget('right', targetPosition);
// Point at object
ikController.pointAt(targetPosition, 'right');
// Reset to idle
ikController.clearTargets();
Ground Placement#
// 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#
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#
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#
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#
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#
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#
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#
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#
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#
- Use LOD for RPM avatars:
meshLod: 'mobile'for crowds - Limit particle count: Reduce aura particles for many avatars
- Throttle IK updates: Update every 2-3 frames
- Pool animations: Reuse AnimationClips across similar avatars
- Batch gestures: Queue gestures to prevent rapid switching
Memory Management#
// 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#
Last Updated: January 2026