AssignAvatarToParticipant

Description

Assigns the avatar identified by avatarID to the specified participant. Any avatar previously assigned to that participant is unassigned first. The avatar wrapper item is spawned at the participant's current position and continuously syncs its pose to the player (see AvatarSyncClone.js). Safe to call repeatedly — re-assigning the same avatar simply replaces the wrapper.

The call is readiness-gated: if the named participant is not yet enrolled in $.groupState.participants, or their PlayerHandle doesn't exist yet, or Cluster hasn't finished populating their humanoid pose data (i.e. getHumanoidBoneRotation(Hips) still returns null), the request is queued and re-tried each frame until the participant becomes ready. If the participant doesn't become ready within five seconds, AvatarManager falls back to a best-effort execution and logs a warning, but the call won't throw. This avoids a race that previously caused the wrapper to spawn in T-pose if the assign fired before the participant's pose data arrived.

Parameters

Side effects

• Spawns a CCK item from the avatar wrapper prefab tied to avatarID in AvatarRegistry, positioned at the participant's current world location (once they're ready — see Description above).
• Unassigns any prior avatar wrapper attached to this participant first (delegates to the same logic as UnassignAvatarFromParticipant).
• The spawned wrapper carries AvatarSyncClone.js, which 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 — set the experiment's Participant Avatar mode to HIDE on the Web Console so the original avatar doesn't show through.
• If avatarID isn't registered, the runtime logs a warning and the call is a no-op.
• If participantIndex is out of range and stays out of range for ≥ 5 seconds, AvatarManager logs a warning and drops the queued request.
• One pending request slot per participant — issuing a second AssignAvatarToParticipant("…", 1) before the first one runs overwrites the first. This is the intended behavior for back-to-back per-condition re-assigns.
• No global state keys are written. The wrapper's lifecycle and per-participant assignment are tracked internally by LUIDA's avatar manager (AvatarManager.js).

Example

Assign a researcher-supplied "doctor coat" avatar to participant 1 at the start of a condition's intro state:

// On State Start of an Intro state
AssignAvatarToParticipant("doctor_coat", 1);

For a paired study where each participant gets a different avatar:

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

When the relevant trial block ends, pair the assign with an unassign so participants return to their own avatar:

// On State Exit of the same condition's End state
UnassignAvatarFromParticipant(1);
UnassignAvatarFromParticipant(2);

Related

• UnassignAvatarFromParticipant(participantIndex) — the symmetric teardown. Always pair them across state boundaries.
• SyncWithParticipantBone(participantIndex, bone, posOffset, rotOffset) — alternative pattern: attach an arbitrary item to a bone instead of swapping the whole avatar.
• Tutorial 2 → Priming + Proteus Effect (with LUIDA automation) — full hands-on walkthrough that uses this action to assign elder vs young avatar between-subjects.
• Cookbook → Unique avatar per participant — short recipe distilling the same pipeline.
• Editor → Configure avatars — the project-side AvatarRegistry window that this action looks up.
• Web Console → Avatars — alternative VRM upload path (per-experiment, S3-backed).
• Web Console → Creating an experiment — why participantAvatarMode must be HIDE for assigned avatars to look right.

Source

Assets/Doc/LUIDA-StateListeningItemScriptDoc.md

- **Description**: Assigns the avatar identified by `avatarID` to the specified participant. Any avatar previously assigned to that participant is unassigned first. The avatar wrapper item is spawned at the participant's current position and continuously syncs its pose to the player (see `AvatarSyncClone.js`). Safe to call repeatedly — re-assigning the same avatar simply replaces the wrapper.
- **Parameters**:
  - `avatarID`: `string` — must match an entry in the project's `AvatarRegistry`.
  - `participantIndex`: `integer` (starts from 1)