Animators

From VRChat Wiki
Revision as of 06:07, 15 April 2026 by DAG-XR (talk | contribs) (Category:VRCSDK)
V · EThis is an official VRChat information page!
It is reviewed and approved by the VRCWiki Team. Learn how to contribute to this page by reading the Contribution Guide.

Animators in VRChat usually refers to the Unity Animator component, Animator Controllers, and the playable-layer setup that drives avatar behavior.

VRChat avatars rely heavily on Unity's animation system. In practice, creator workflows combine:

  • A Unity Animator component on the avatar root.
  • One or more Animator Controllers assigned through playable layers.
  • Parameters from Expressions and VRChat built-in inputs.
  • State behaviors that modify tracking, locomotion, layer weight, and parameters.

For most avatars, creator logic is authored through playable layers in the Avatar Descriptor.

Animator component

The Unity Animator component evaluates an Animator Controller on a GameObject. For avatars, it is placed on the same GameObject as the Avatar Descriptor.

Unity adds this component automatically when importing an FBX with a rig definition.

Animation path scope

Animation property paths are relative to the nearest parent Animator.

For example, if the hierarchy is Avatar/Parent/Child:

  • If the nearest Animator is on Avatar, the path to animate Child is Parent/Child.
  • If the nearest Animator is on Parent, the path is Child.

This same scope affects the Animation window. Full clip editing features (such as record/preview workflows) depend on selecting an object that resolves to an Animator context with a usable controller/clip setup.

Animator Controllers

An Animator Controller is the logic graph used by the Animator. It is made up of:

  • Parameters, which store values used by transitions and blend trees.
  • Layers, which separate different groups of states.
  • States, which hold motions such as animation clips or blend trees.
  • Transitions, which define when the controller moves from one state to another.

In VRChat, these controllers commonly read:

  • Custom parameters from Expressions.
  • Built-in VRChat animator parameters (read-only at runtime).

Because built-in and custom values can change at any time, controllers should avoid dead-end states with no reliable exit path.

States and transitions

A State usually contains an animation clip or blend tree. A Transition describes when the controller should move to another state, often using one or more conditions tied to parameters.

Playable layers

VRChat combines multiple playable layers in order. For humanoid avatars, the order is:

  • Base
  • Additive
  • Gesture
  • Action
  • FX

Generic avatars commonly use:

  • Base
  • Action
  • FX

Higher layers take precedence when they animate the same property.

Layer Typical purpose Notes
Base Locomotion and movement-state logic. Transform-focused. Replacing this layer usually requires rebuilding locomotion behavior.
Additive Additive humanoid motion (for example subtle breathing). Transform-focused and intended as an additive overlay.
Gesture Hand/body-part gestures and many non-locomotion transform animations. Commonly used with avatar masks for per-part control.
Action Full-body override actions (emote-like behavior). This playable layer is weight 0 by default and is typically blended in/out with Playable Layer Control.
FX Non-transform feature logic (toggles, blendshapes, materials, component values). Commonly used for most avatar feature systems.

Use Animation Controllers in playable-layer slots, and avoid assigning the same controller to multiple slots.

State behaviors

VRChat adds several state behaviors to Unity's Animator workflow. These run when entering a state and are commonly used to alter parameters, tracking, locomotion, and layer weights.

  • Avatar Parameter Driver
  • Animator Tracking Control
  • Playable Layer Control
  • Animator Layer Control
  • Animator Locomotion Control
  • Animator Temporary Pose Space
  • Animator Play Audio

Important workflow notes:

  • Parameter Driver operations run top-to-bottom.
  • Synced custom parameter values are clamped to VRChat's sync ranges (Int 0-255, Float -1.0 to 1.0).
  • Built-in VRChat parameters are read-only and are not valid Parameter Driver targets.

Write Defaults

Write Defaults controls whether a state writes default values to properties that are not explicitly animated in that state.

Stay consistent within a controller and test carefully when mixing masks, layer interactions, and transform animation across layers. Avoid mixing Write Defaults modes in one controller unless a specific design requires it.

With Write Defaults Off, ensure states still contain valid motion data (clip or blend tree), including deliberate "buffer" clip patterns where needed.

Avatar Masks

An Avatar Mask controls which humanoid muscles, transforms, and material swaps a given Animator layer is allowed to animate. When a mask is applied to a layer, only the enabled parts of the mask can be changed by animations on that layer.

Key behaviors:

  • If a humanoid body part is enabled in the mask, animations on that layer can move that part. If disabled, they cannot.
  • If a transform is enabled (or not listed), animations can change its position, rotation, scale, and first material slot. If disabled, they cannot.
  • Blendshapes and non-transform component values are unaffected by masks.
  • Any layer with a mask cannot animate material swaps beyond the first slot, or the root transform of the Animator's GameObject.

Avatar Masks are especially important for VRChat's playable-layer architecture. Without masks, humanoid animations on a higher layer would override all humanoid muscles from lower layers, causing the avatar to fall into a default pose. For example, the default Gesture layer uses masks so the left-hand layer only affects left-hand muscles and the right-hand layer only affects right-hand muscles.

A common workflow issue arises when using Write Defaults Off transform animations on both the Gesture and FX layers. An unmasked WD Off transform animation on the FX layer will override all Gesture layer transform animations. When this occurs, creators should apply a mask to the FX layer that enables only the transforms being animated in FX.

Child animators and advanced setups

Blend Trees let a state blend between several motions using one or more parameters. They are commonly used for locomotion, puppets, analog gestures, and multi-option selectors.

Some advanced avatar setups also use additional Animator components on child objects or helper objects (often called sub-animators). They can be useful in specialized setups, but they add complexity around path scoping, update/culling behavior, and layer interaction.

For most setups, keep primary avatar logic in playable layers.

Official resources

Resources

Retrieved from "https://wiki.vrchat.com/index.php?title=Animators&oldid=69236"