Avatar Masks

Unity Behaviour

A mask blocks out humanoid muscle values, material swaps and transform values from animations played in an animator controller based on what is enabled and what is disabled in the mask. If a layer has a mask with a certain value enabled in the mask, the animation is allowed to animate that value. If a layer has a mask with a certain value disabled in the mask, the animation is not allowed to animate that value.

To be specific:

• If a layer has a mask with a humanoid value (such as left hand) enabled, that humanoid muscle can be modified by an animation in that layer
• If a layer has a mask with a humanoid value (such as left hand) disabled, that humanoid muscle can't be modified by an animation in that layer
• If a layer has a mask with a transform value enabled or not specified, that transform can have its position, rotation and scale modified by an animation in that layer, as well as a material swap on the first material slot
• If a layer has a mask with a transform value disabled, that transform can't have its position, rotation or scale, or a material swap on the first material slot modified by an animation in that layer

If a layer has any mask whatsoever, it can't animate material swaps on any material slot beyond the first, or the root transform of the object with the animator on it.

Anything else (blendshapes & any other components) is unaffected by masks.

The reason we have masks is because if you animate a humanoid muscle on one layer, and then animate any humanoid muscle on a different layer that gets applied later (whether lower down in the animator or on a different playable layer), it gets overwritten (unless the other layer is an Additive layer, if so it adds on top of it). With transforms, this only happens if the second animation uses WD off and is on a Playable Layer that gets applied later. So for example if we didn’t have masks, if you animated a humanoid muscle on your Gesture Layer for hand movement, it would overwrite your Base Layer and your avatar would be in default pose (bike pose) all the time.

<aside> 🔥 This means that if you have a humanoid animation, without masking just the humanoid muscles you want to be enabled, and the rest disabled, all other humanoid muscles will be overwritten.

</aside>

<aside> 🔥 This also means that if you have Transform animations on your Gesture layer, and you have an unmasked WD Off Transform animation on the FX layer, all the Gesture Layer Transform animations will be overwritten.

</aside>

<aside> ⚠️ The default VRChat FX Layer uses an unmasked WD off blend tree. This can cause transform animations to not play in VRChat as long as you are using the default FX Layer. If you want to animate transforms on the Gesture layer, you have to either use your own FX Layer or remove theirs and set it to be empty.

</aside>

VRChat layer behaviour

All playable layers are applied one after the other. First the Base, then Additive, then Gesture, then Action and lastly FX.

On the first four layers (Base, Additive, Gesture & Action), you should only use animations which affect transforms (so either humanoid muscles or transform animations) and toggle gameobjects on/off.