# Ready Player Me Avatar Integration

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