Uploading avatars

Upload VRM files to your experiment's avatar set so AssignAvatarToParticipant can use them. Includes special avatar names, thumbnail generation, and the relationship to the project-level AvatarRegistry.

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.

The Web Console's Avatars tab lets you upload per-experiment VRM avatars. These avatars are stored in LUIDA's S3 bucket alongside the experiment's other assets and made available to the runtime for use with AssignAvatarToParticipant.

Most experiments don't need this page. The per-experiment avatar set is largely superseded by the Unity-side Configure avatars window, which registers avatars at the project level (faster, no S3 round-trip, no per-experiment duplication). Use the Web Console avatar tab only if you specifically need server-side avatar storage — e.g., to swap avatars between experiments without rebuilding the Unity project, or to share an avatar set across multiple experiments owned by different researchers.

When to use the Web Console avatar tab

Project-level alternative is easier: drop a VRM into Unity, wrap it, register in LUIDA › Configure avatars. The Web Console tab exists for legacy reasons and for cross-experiment sharing.
The Web Console tab is useful when you want to update the avatar set without re-uploading the Unity world to Cluster — e.g., you've added a new condition mid-collection and need a new avatar variant.

If you're not sure: use the Unity-side registry. Come back to this page only when you hit a specific blocker.

Where the tab lives

On any experiment detail page, scroll to the Avatars section (or Avatars tab — exact UI varies by Web Console version). You'll see:

A list of avatars currently registered for this experiment, each with a thumbnail, an avatarID (used by the runtime), and a delete button.
An + Upload Avatar button.

Screenshot pending — the Avatars tab on the experiment detail page, with two registered avatars (doctor_coat, trainee_outfit) shown with their thumbnails and avatarIDs.

Uploading a VRM

Click + Upload Avatar. The dialog has:

Field	Purpose
avatarID	The string that identifies this avatar at runtime. Must match what your Unity code passes to `AssignAvatarToParticipant("...", n)`. Case-sensitive.
VRM file	The `.vrm` file itself. Maximum size and format requirements per the LUIDA team's S3 policy — see the upload dialog for current limits.
Thumbnail	Optional preview image (PNG/JPG). If you skip this, the Web Console auto-generates one from the VRM's first-frame render.
Display name	Optional human-readable label shown in the listing.
Description	Optional notes for collaborators (e.g., "Outfit A for the role-priming condition").

After upload, the file lands in LUIDA's S3 bucket under a key tied to the experiment's eID. The runtime fetches it via the experiment's questInfo response when a session starts.

Special avatar names

LUIDA reserves a small number of avatarIDs with special runtime semantics:

`avatarID`	Meaning
`_hide`	Equivalent to setting `participantAvatarMode` to `HIDE`. Forces the transparent LUIDA avatar.
`_default`	Equivalent to `DEFAULT` — forces the standard LUIDA avatar.
`_unrestricted`	Equivalent to `UNRESTRICTED` — lets the participant keep their own Cluster avatar.

Calling AssignAvatarToParticipant("_hide", 1) is a clean way to swap back to the invisible avatar in the middle of a session without UnassignAvatarFromParticipant semantics. The exact set of reserved names may vary across LUIDA versions; check Assets/ClusterMetaverseLab/LuidaExpTemplate/Runtime/Scripts/CSharp/ for the authoritative list.

World-specific avatar sets (deprecated)

Earlier LUIDA versions had a concept of per-world avatar sets — avatars uploaded to one experiment's worldID would also be available to any other experiment sharing that world. This was useful for sample-experiment galleries but caused permission and ownership confusion.

The feature has been deprecated. Avatars uploaded via the Web Console are now scoped to a single eID. If you need the same avatar in two experiments, upload it to each one separately, or use the project-level Unity-side registry which is global to your Unity project.

If you're inheriting an old experiment that depended on per-world sharing, the LUIDA team can migrate the legacy avatar entries — ask via luida@cluster.mu.

How runtime lookup works

When AssignAvatarToParticipant("doctor_coat", 1) fires at runtime, the lookup order is:

The Unity-side AvatarRegistry (registered via LUIDA › Configure avatars). Resolves to a local prefab — fastest.
The Web Console's per-experiment avatar set (this page). Resolves to an S3-hosted VRM that's downloaded on demand.
Reserved names (_hide, _default, _unrestricted) — these bypass both registries.

If the avatarID isn't found in either registry, the action logs a warning and no-ops. So avatarIDs in the two registries should be distinct — registering the same name in both is fine but the Unity-side wins.

What gets stored

Per uploaded avatar, the Web Console stores:

avatarID, displayName, description
VRM file in S3 (keyed by eID + avatarID)
Thumbnail in S3 (auto-generated if not provided)
Upload timestamp, uploader account

The VRM file itself is not versioned — re-uploading the same avatarID replaces the previous file. If you need version history, keep a separate copy and re-upload with a different avatarID.

Common pitfalls

avatarID mismatch. The Unity code calling AssignAvatarToParticipant("doctorcoat", 1) won't find anything if the avatar was registered as doctor_coat. Exact string match, including case.
Reusing the same avatarID across the Unity registry and Web Console set. The Unity registry wins, so updates to the Web Console version aren't visible to the runtime. Use distinct names.
Uploading non-VRM files. Only .vrm is supported. Convert via Blender + UniVRM or VRoid Studio if you have a different format.
Forgetting participantAvatarMode = HIDE. All avatar-assignment workflows require HIDE mode at the experiment level so the original Cluster avatar doesn't render behind the assigned wrapper. See Platform & avatar settings.

Where to go next

Unity-side LUIDA › Configure avatars — the recommended, project-level alternative to this page.
AssignAvatarToParticipant — the runtime action that resolves through these registries.
Platform & avatar settings — the experiment-level participantAvatarMode that must be HIDE for avatar swapping to look right.

On this page