LUIDA Docs

Unique avatar per participant

Assign a researcher-supplied VRM to each participant — same avatar every session, or a different one per condition.

Goal

Replace the participant's normal Cluster avatar with a VRM you supply. Either everyone in the experiment gets the same one, or you assign a different avatar per condition for an embodiment manipulation.

Smallest setup

  • A LUIDA scene with at least one state.
  • A .vrm file (VRM 0.x or 1.0) or a humanoid prefab to use as the assigned avatar.
  • A Web Console experiment registered (so you can set participantAvatarMode = HIDE).

This recipe is the short version of Tutorial 2: Priming + Proteus Effect (with LUIDA automation). If you've never done avatar assignment before, do the tutorial once — there are three settings that need to line up and the tutorial walks them all. This page is the lookup-when-you've-forgotten version.

The recipe

Register the avatar in Configure avatars

Open LUIDA › Configure avatars and drop the .vrm file (or humanoid prefab) onto the Register Avatars zone. LUIDA imports it, generates the wrapper prefab and bone map, and adds an entry whose Avatar ID defaults to the file name. Change the Avatar ID to my_avatar — that's the string the action rows below use. There's nothing to save.

Add the Avatar Spawner to the scene

Still in the window, under Avatar Spawner (Current Scene), click Add Avatar Spawner to Current Scene if the scene doesn't have one. LUIDA-AvatarSpawner is the item that spawns and syncs the avatar at runtime; without it the assign action only logs a warning.

Set participantAvatarMode = HIDE in the Web Console

On the experiment detail page, scroll to World & Platform, set Participant Avatar to HIDE. Save.

Without this, the participant's normal Cluster avatar renders behind your assigned VRM — you'll see double.

Add the assign action on entry

In LUIDA › Configure experiment automation → State-listening Items, find a controller item (any state-listener-bearing GameObject) at the first state of the experiment. Under On State Start, add:

  • Action: AssignAvatarToParticipant
  • avatarID: my_avatar
  • participantIndex: 1

Add the unassign action on exit

In the same row, under On State Exit of the experiment's End state, add:

  • Action: UnassignAvatarFromParticipant
  • participantIndex: 1

Run the scene once in a private Cluster test space (Japanese walkthrough) — or press Play in Unity, if you installed CSEmulator. The participant's view shifts to the assigned avatar at the start, follows their head and hands throughout the experiment, and disappears at the end.

Why this works

AssignAvatarToParticipant asks LUIDA-AvatarSpawner to spawn the wrapper prefab (generated by the Configure avatars window when you registered the avatar) as a CCK item at the participant's current world position, then AvatarSyncClone.js reads the participant's bone transforms each frame and applies them to the wrapper. The participant's underlying Cluster avatar is still rendered behind it — participantAvatarMode = HIDE is what makes the underlying avatar invisible so only your wrapper shows.

The wrapper is just a regular CCK item under the hood. The participant doesn't "become" the avatar; they're still controlling their own (now-hidden) Cluster avatar, and the wrapper is a separate visible item that mimics them. This is why bone-attached props (SyncWithParticipantBone) work alongside it without conflict.

See Concepts → Conditions, sessions, participants for how the participant index is resolved, and Editor → Configure avatars for the registry's full UI.

Variants

Different avatar per condition (embodiment manipulation). Add a between-subjects variable role: doctor,control. Register two avatars with the Avatar IDs doctor_coat and trainee_outfit. Use the if toggle on the action row:

if (CONDITION["role"] === "doctor") {
  AssignAvatarToParticipant("doctor_coat", 1);
} else {
  AssignAvatarToParticipant("trainee_outfit", 1);
}

LUIDA's balancer alternates role across sessions; each participant gets exactly one of the two avatars for the full session.

Two participants, different avatars each. For a dyad study (pNum = 2):

AssignAvatarToParticipant("instructor_outfit", 1);
AssignAvatarToParticipant("trainee_outfit", 2);

Pair with two unassigns on End:

UnassignAvatarFromParticipant(1);
UnassignAvatarFromParticipant(2);

Mid-experiment avatar swap. Add another AssignAvatarToParticipant("different_avatar", 1) on a later state's On State Start. The action despawns the prior wrapper before spawning the new one — safe to call repeatedly. No explicit unassign needed between the two assigns.

Legacy: avatars uploaded via the Web Console. The in-Unity LUIDA › Configure avatars registry is the current way to supply avatars. Older experiments may still have VRMs uploaded through the Web Console's Avatars tab; the runtime falls back to that S3-hosted set only when the Unity-side AvatarRegistry doesn't contain the ID. It isn't the documented path for new experiments.

Defensive unassign at experiment start. If you're worried about state leaking between sessions:

// Very first On State Start of the experiment
UnassignAvatarFromParticipant(1);
AssignAvatarToParticipant("my_avatar", 1);

The unassign is a safe no-op if there's nothing to clean.

Common pitfalls

  • avatarID mismatch. AssignAvatarToParticipant("My_Avatar", 1) won't find anything registered as my_avatar. Case-sensitive, exact string match.
  • Forgetting HIDE mode. With UNRESTRICTED or DEFAULT, you'll see the participant's original avatar rendering behind your wrapper.
  • No LUIDA-AvatarSpawner in the scene. The assign action logs a warning and nothing appears. Add one from the bottom of the Configure avatars window.
  • Registering in the wrong scene. The registry is per scene and a new scene starts empty — register my_avatar again there.
  • Skipping the unassign. The wrapper persists into the next session if you don't clean up. Always pair an assign with an unassign on a symmetric state boundary.

Where to go next