LUIDA Docs
ComponentsUnity templateEditor windows

Configure avatars

Register VRM avatars in the project's AvatarRegistry so AssignAvatarToParticipant can spawn them at runtime by string ID.

These pages are not yet fully reviewed. The LUIDA team is continuing to review and improve them. If you find anything wrong on these pages, or have questions that aren't resolved by reading them, please ask or report to the LUIDA team.

LUIDA › Configure avatars is the editor-side companion to the runtime action AssignAvatarToParticipant(avatarID, participantIndex). It manages the project's AvatarRegistry — a name-to-prefab table that lets your state-listening items spawn researcher-supplied avatars by string ID without hardcoding prefab references.

If your experiment doesn't swap participant avatars (most don't), you can skip this window entirely. If you're doing embodiment research, avatar manipulation studies, or any paired study where each participant should look different from their Cluster default, this is where you register the avatars you'll later assign at runtime.

Screenshot pending — the Configure avatars window with three registered avatars: doctor_coat, trainee_outfit, instructor_outfit, each with its prefab reference and preview thumbnail.

What you register

For each entry in the registry, you specify:

FieldTypeWhat it controls
avatarIDstringThe name AssignAvatarToParticipant looks up. Use a stable, code-friendly identifier (e.g., doctor_coat, not Doctor Coat #1).
Avatar prefabreferenceA Unity prefab — typically a VRM file imported via UniVRM and wrapped in a LUIDA avatar wrapper. The wrapper carries AvatarSyncClone.js, which is what continuously syncs the wrapper's bones to the participant's avatar.

The registry is global to the project — any scene can reference any registered avatarID.

How it interacts with the runtime

At session time:

  1. A state-listening item calls AssignAvatarToParticipant("doctor_coat", 1).
  2. LUIDA's avatar manager looks up doctor_coat in the AvatarRegistry, finds the matching prefab, and spawns it as a CCK item at participant 1's current world position.
  3. AvatarSyncClone.js on the spawned wrapper reads participant 1's bone transforms each frame and applies them to the wrapper.
  4. Other players in the room see the wrapper rendered over (or in place of) the participant's normal Cluster avatar.

For the visual swap to look clean, the experiment's Participant Avatar mode in the Web Console must be HIDE — otherwise the original Cluster avatar shows through. See Web Console → Creating an experiment → World & Platform.

Importing a VRM into the registry

The typical workflow:

  1. Drop a .vrm file into the Unity project. UniVRM auto-imports it into a Unity prefab.
  2. Wrap the imported VRM in the LUIDA avatar wrapper prefab provided in Assets/ClusterMetaverseLab/LuidaExpTemplate/Runtime/Prefabs/Avatars/ (or equivalent — exact path may vary by template version). The wrapper carries the CCK item and the AvatarSyncClone.js script.
  3. Open LUIDA › Configure avatars, click + Add Avatar, enter the avatarID you want to use, and drag the wrapper prefab into the slot.

After saving, the avatar is callable from any state-listening item in any scene of the project.

A registered prefab must be a wrapper containing the VRM, not the raw VRM itself. The wrapper provides the CCK item and the bone-sync script. The raw imported VRM is just a mesh — AssignAvatarToParticipant won't position or animate it. The template ships an example wrapper prefab you should duplicate; don't build the wrapper from scratch unless you know what you're doing.

Where the registry is stored

The AvatarRegistry is a ScriptableObject (or a similar persistence asset) under:

Assets/_Experiment_/Settings/Avatars/AvatarRegistry.asset

(Exact path may differ slightly by template version; this window is the canonical UI.)

Treat the file as managed by this window — edit only through the editor, not by hand.

When to use this window vs. the Web Console avatar settings

There are three avatar-related settings to keep straight:

WhereWhat it does
Web Console → Creating an experiment → Participant Avatar mode (HIDE / DEFAULT / UNRESTRICTED)Project-wide policy for what avatar participants render with. See create-experiment.
Web Console → experiment → Avatars tab(Deprecated per-world avatar set; most projects don't use this.) See Web Console → Avatars.
This window (LUIDA › Configure avatars)Project-level registry of researcher-supplied prefabs that AssignAvatarToParticipant looks up.

In short: the Web Console controls what the participant looks like by default; this window controls what you can swap them into at runtime.

Common pitfalls

  • avatarID typo. AssignAvatarToParticipant("doctorcoat", 1) silently no-ops if the registry has it as doctor_coat. Case-sensitive, exact match.
  • Forgetting the Web Console mode. With participantAvatarMode = UNRESTRICTED, the participant's Cluster avatar renders behind the LUIDA wrapper and you'll see double. Set to HIDE.
  • Spawning the raw VRM as the wrapper. The bone sync script needs the wrapper around it. Use the template-provided wrapper prefab.
  • Cross-project assumptions. The registry is per-project. If you copy a state-listening script with AssignAvatarToParticipant("foo", 1) to a new project, you must also register foo in the new project's registry.

Where to go next

Configure experiment identifiers

The Unity window where you paste your eID, verify token, callExternal endpoint, pNum, and isTestMode. The same content lives at Setup → Connect to Web Console — see there for the full walkthrough.

Configure data collector

Visual builder for the per-scene LuidaDataCollectorConfig: declare the labels participants and gimmicks can write, define the fields uploaded per recording tick, and (optionally) write the calculator body in raw JS.

On this page

What you registerHow it interacts with the runtimeImporting a VRM into the registryWhere the registry is storedWhen to use this window vs. the Web Console avatar settingsCommon pitfallsWhere to go next