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
.vrmfile (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_avatarparticipantIndex: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
avatarIDmismatch.AssignAvatarToParticipant("My_Avatar", 1)won't find anything registered asmy_avatar. Case-sensitive, exact string match.- Forgetting
HIDEmode. WithUNRESTRICTEDorDEFAULT, you'll see the participant's original avatar rendering behind your wrapper. - No
LUIDA-AvatarSpawnerin 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_avataragain 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
- Tutorial 2: Priming + Proteus Effect (with LUIDA automation) — the full 120–150 min walkthrough.
- Reference → AssignAvatarToParticipant — every parameter and side effect.
- Reference → UnassignAvatarFromParticipant — the teardown counterpart.
- Editor → Configure avatars — the registry UI.
- Web Console → Platform & avatars — the
participantAvatarModepolicy. - Web Console → Avatars — the legacy Web Console-side VRM upload, kept for cross-experiment sharing.