Avatars

An avatar is a character players wear. You mark a rigged model with an AvatarDescriptor, configure how it moves and emotes, then build and upload it like a world.

New to avatar authoring here? Start with the Avatar Toolkit

The Avatar Toolkit adds non-destructive features — toggles, outfit merging (Armature Link), modes, gestures, blendshape links, and more — with one component, compiled into your avatar automatically at upload. It's the fastest path from a rigged model to a fully featured avatar.

Mark the avatar root

Add an AvatarDescriptor (Social Scape/Avatar Descriptor) to the root of your rigged model. One per avatar.

Configure it

Group	Fields
Avatar settings	First‑person eye position, voice source position, default scale.
Animation layers	Base layers (locomotion, gesture, action) + optional special layers, each an animator controller — see Avatar Animation.
Expressions	An expression menu + parameters players can drive.
Eye & lipsync	Eye‑movement tracking (eye bones), blink blendshapes, and viseme lipsync (15 visemes) on the body mesh.
Bone references	Head bone (and optional neck) for look/IK.
Customization	Allow recoloring + which materials can be recolored.

Lip‑sync (visemes)

Tick useVisemeLipsync on the AvatarDescriptor and the avatar's mouth moves with whatever it says — proximity voice from the player wearing it, or an AI NPC voice. It's driven by the audio itself, so it just works for everyone with no per‑session setup.

Pick how the mouth is driven

Not every avatar has fifteen mouth shapes, and some have no mouth mesh at all — a robot, a helmet, a mask. Viseme Mode picks how your speech is spent:

Mode	What it does	Use it when
Viseme Blend Shape	A shape key per mouth shape. The most expressive.	Your mesh has the full viseme set. (default)
Jaw Flap Bone	Rotates one jaw bone open and shut on how loudly you speak.	You have a rigged jaw and no mouth shape keys.
Jaw Flap Blend Shape	Drives a single open‑mouth shape key on volume.	You have "mouth open" but not the full set.
Viseme Parameter Only	Drives nothing directly — publishes the Viseme number (0–14) and the Voice level (0–1) to your animator so you can build the mouth yourself.	Texture‑swap mouths, hand‑built rigs, anything unusual.

All four look correct to everyone else, not just to you — the mouth is reproduced on every player's screen the same way, whichever mode you choose, and none of them costs any more networking than another.

Jaw Flap Bone hinging the wrong way?

Rigs genuinely disagree about which axis opens a jaw, and it can't be detected reliably — so it's yours to set. Change Jaw Open Axis (or negate it, e.g. -1, 0, 0) until it swings the right way, and tune Jaw Open Angle for how wide it opens at full volume.

Voice works in every mode

The Voice parameter (0 = silent, 1 = loud) is published whatever your viseme mode is — so an Avatar Toolkit When Talking reaction fires even on an avatar with no visemes at all.

Map the 15 visemes

(Viseme Blend Shape mode only — the other modes don't need this.) You map the 15 standard visemes (sil, PP, FF, TH, DD, kk, CH, SS, nn, RR, aa, E, I, O, U) to your body mesh's blendshapes:

1. Set Body Mesh to the SkinnedMeshRenderer that carries the mouth blendshapes.
2. Click Auto‑Detect Viseme Blendshapes. It recognises the common naming schemes — plain (aa), prefixed (vrc.v_aa and vrc.aa), and viseme_aa — and fills the 15 slots, reporting "Found N of 15".
3. Fix anything it missed with the dropdowns (they list every blendshape on the mesh).

Unusual blendshape names? Make a mapping rule

If your avatar uses an unconventional naming scheme and Auto‑Detect comes back short, open Social Scape ▸ Tools ▸ Viseme Mapping Editor. Add your blendshape names as tokens on the right viseme slot (or create a whole rule set for that style), hit Preview Match against your avatar to confirm 15/15, then Apply to Descriptor — or just run Auto‑Detect again. Your rules are saved, so the next avatar with the same naming maps in one click. Matching is prefix‑tolerant, so adding vrc. as a strip‑prefix makes every vrc.<name> resolve automatically.

Avatar Dynamics — secondary motion & interaction

Beyond animation, an avatar can carry a family of Avatar Dynamics components that add life and touch. They all simulate per-viewer (nothing extra on the wire beyond the odd animator parameter), draw their setup in the Scene view, and can be tested live with the Avatar Animation Preview.

Add	What it does	Page
Social Bone (+ Social Bone Collider)	Spring secondary motion — hair, tails, ears, cloth — with collision, limits, stretch, and grab.	Social Bones
Magica Cloth 2 (your own licensed copy)	Real cloth simulation for skirts, capes and drapery. Officially supported, with limits on the costly settings.	Magica Cloth 2
Contact Sender / Contact Receiver	Detect touch & proximity between avatars (headpats, handholds) and drive an animator parameter.	Contacts
Position / Rotation / Scale / Parent / Aim / Look At Constraint	Drive one transform from others — followers, aim rigs, mounts, world-anchored props.	Constraints
Grab IK (Poseable Limb)	Let players grab a hand/foot and pose the limb via IK.	Poseable Limbs

Each has its own upload budget; the SDK reports it and trims the excess (see limits and each page). VR grab poses (how a held object sits in the hand) and haptic feedback are covered under Interactables.

Fixing avatar materials (URP)

Social Scape renders with the Universal Render Pipeline (URP). An avatar authored for the Standard shader or a custom avatar shader can import with materials that show up bright magenta ("missing shader"). Select the avatar and run Social Scape ▸ Tools ▸ Convert Materials to URP Lit — it switches every material on the avatar's renderers to the clean URP/Lit shader and auto‑sets the base texture (plus base colour, tiling, and opaque/cutout/transparent type) from the original. It's a one‑click way to get a clean, correct base look you can refine from. The change is in place and Undo‑able, so duplicate the avatar first if you want to keep the originals untouched.

Prefer a flat, fullbright look (or your base texture already bakes in its shading)? Use Convert Materials to URP Unlit instead — same conversion, but the material ignores scene lighting.

Pink terrain?

For a world whose terrain renders magenta (a terrain authored for the wrong pipeline), use Social Scape ▸ Tools ▸ Fix Scene Terrain Shaders — it repoints every scene Terrain's material at the correct URP terrain shader.

Build & upload

Same flow as worlds — Social Scape ▸ Content Manager:

1. Select the avatar and build (the SDK validates the rig and captures a thumbnail).
2. Upload — the first upload assigns a GUID (the avatar's permanent identity) and a content id. The GUID is shown on the AvatarDescriptor under Upload Identity and is saved onto the avatar, so every later upload updates the same avatar instead of creating a duplicate.

Avatars have a smaller size budget than worlds; the SDK reports the limit and any validation errors at build time. Fix them before uploading.

Re-uploading

When you re‑upload an existing avatar, the form pre‑fills its current name, description, and tags from the server — edit only what changed. Tick "Don't override picture" to keep the existing thumbnail, or leave it off to capture a fresh one.

Updating an avatar vs. making a new one

Upload from the same prefab and its GUID links the update to the right record. To point a model at a different existing avatar, paste that avatar's GUID into Upload Identity on the AvatarDescriptor before uploading. (There's no separate "GUID script" — it's a field on the descriptor.)

Performance tier

At build the SDK computes a performance rating for your avatar — Excellent, Medium, or Poor (lighter is better) — from its triangle count, materials, bones, and other costs (use Analyze Performance on the AvatarDescriptor to see the full breakdown; an avatar that exceeds the budget is rated Very Poor and rejected). The rating is baked into the avatar and travels with it.

In‑game, players can set a maximum avatar tier in their performance settings — avatars above a player's cap are shown as a default placeholder instead of being downloaded. So a leaner avatar reaches more people: keep triangles, materials, and bones reasonable and aim for Medium or better.

Protecting your asset

The upload form has an "Encrypt this asset" option, ticked by default — your avatar is protected by Aegis: encrypted on your machine before upload and kept encrypted in every player's cache, so the raw model can't be copied off disk and opened in a ripper. It loads exactly the same in‑game. Leave it on unless you deliberately want to share the avatar openly; you can change it on any re‑upload.

→ How it works and why it's safe: Aegis content protection.

Using avatars in a world

A world can force a specific avatar on everyone, or restrict players to a set the creator chose, with the Avatar Policy component — see Enforced avatars. (The older allowAvatarSwitching toggle on WorldDescriptor is superseded by it.)