Eve library

Ready Player Me Avatar Integration

Guide

Revision 1

On this page

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#

  • ReadyPlayerMeAvatarService constructs canonical Ready Player Me model URLs, loads GLB scenes (via GLTFLoader in production), and caches results by profile/options.
  • PersonaAvatar can declare readyPlayerMeAvatar options 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() and getReadyPlayerMeAvatar(), 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: true to bypass.
  • loadAvatar accepts an optional AbortSignal for cancellation.
  • The returned THREE.Group carries userData.readyPlayerMeUrl and should be cloned before attaching to multiple parents (the PersonaAvatar integration 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