Lilith’s metaverse client now wires Ready Player Me avatars directly into the
PersonaAvatar pipeline. This document explains how to configure remote
avatars, control lifecycle behaviour, and operate the supporting service.
Overview#
ReadyPlayerMeAvatarServiceconstructs canonical Ready Player Me model URLs, loads GLB scenes (viaGLTFLoaderin production), and caches results by profile/options.PersonaAvatarcan declarereadyPlayerMeAvataroptions to attach a remote avatar. Once the GLB resolves, procedural meshes are hidden (unless opt-out) and the Ready Player Me scene is mounted in situ with preserved metadata.- Consumers can introspect load status via
whenRemoteAvatarReady()andgetReadyPlayerMeAvatar(), enabling progress indicators or diagnostics overlays.
Configuring avatars#
ts
const avatar = new PersonaAvatar({
id: 'oracle-solstice',
name: 'Oracle of the Solstice',
appearance: createPresetAppearance('cosmic-guide'),
behavior: createPresetBehavior('cosmic-guide'),
readyPlayerMeAvatar: {
profileId: 'rpm-profile-42',
bodyType: 'fullbody',
gender: 'neutral',
outfit: 'formal',
pose: 'meditation',
morphTargets: ['viseme', 'blink'],
textureSize: 2048,
meshLod: 'high',
scale: 0.92,
yOffset: -0.35,
},
});
await avatar.whenRemoteAvatarReady();
console.log(avatar.getReadyPlayerMeAvatar()?.metadata.url);
Persona options#
| Option | Type | Default | Notes |
|---|---|---|---|
profileId |
string |
required | Ready Player Me profile ID |
bodyType |
'fullbody' | 'halfbody' |
'fullbody' |
Selects RPM body variant |
gender |
'male' | 'female' | 'neutral' |
'neutral' |
Adds gender query parameter |
outfit |
string |
– | Outfit preset (e.g., casual, formal) |
morphTargets |
string[] |
– | Comma-joined list (e.g., ['viseme','blink']) |
textureSize |
512|1024|2048|4096 |
1024 |
Texture atlas resolution |
meshLod |
'mobile' | 'standard' | 'high' |
– | Geometry level of detail |
pose |
string |
– | Pose preset (meditation, A, etc.) |
expression |
string |
– | Default facial expression |
scale |
number |
1 |
Uniform scaling applied when mounted |
yOffset |
number |
0 |
Vertical shift (metres) to align seating |
autoHideProcedural |
boolean |
true |
Hide procedural meshes once RPM avatar is ready |
Service usage#
ts
const service = new ReadyPlayerMeAvatarService();
const { group, metadata } = await service.loadAvatar({
profileId: 'avatar-123',
bodyType: 'halfbody',
gender: 'female',
outfit: 'cyberpunk',
morphTargets: ['viseme', 'blink'],
textureSize: 2048,
meshLod: 'high',
});
scene.add(group);
console.log(metadata.url); // Canonical Ready Player Me GLB URL
- Cached responses avoid redundant network loads; pass
forceReload: trueto bypass. loadAvataraccepts an optionalAbortSignalfor cancellation.- The returned
THREE.GroupcarriesuserData.readyPlayerMeUrland should be cloned before attaching to multiple parents (thePersonaAvatarintegration handles this automatically).
Testing#
Targeted Vitest coverage validates URL construction, cache behaviour, and persona integration:
bash
cd web
timeout -k 5 30000 npm run test -- src/lib/__tests__/ready-player-me-avatar.test.ts
timeout -k 5 30000 npm run test -- src/lib/__tests__/persona-avatar-system.test.ts