Playable Layers


Unity Knowledge Required

This document is written with the assumption that you know a bit about Unity Animators.

In the Avatars 3.0 Avatar Descriptor, there are five buttons labeled:

  • Base
  • Additive
  • Gesture
  • Action
  • FX

These are Playable Layers. Each of them takes a Unity Animator, and they layer on top of each other. In other words, you've got five root animators to play with, and each of them can have a huge amount of Animator Layers (I'm not actually sure of the max layers, but whatever that is, that's the max).

These layers apply in order-- in other words, base gets applied, then additive, then gesture, action, FX. As an example, if something in Additive animates a bone (with 1.0 weight), and then something in Action animates that same bone (with 1.0 weight), the Action animation will take precedence.

We have example Playable Layers available in the SDK. Depending on how you learn and iterate on things, it might be easier for you to use and edit these default layers to figure things out!

When you are running VRChat and you're wearing (or viewing) an Avatar 3.0 avatar, all of these Playable Layers are put together into a combined Animator. This Animator is the root, main animator of your avatar, and you can control any part of it. This means that there is no reason to add any additional animators on your avatar.

As an aside, you should never use the same controller in multiple Playable Layers. This may work for some setups, but it is very poor practice and will cause major issues as you expand the functionality of your avatar.


Only Use Animation Controllers

We only support the use of Animation Controllers in Playable Layer slots. Do not use any other type of controller-- you will run into errors or will be unable to upload the content.

What do these Playable Layers do? Here's the short version:

Base: Stuff that should always play, react to movement (like locomotion), or the locomotion state of your avatar (running, falling, crouching, etc). Transform animations only.
Additive: Stuff that Base is already using, but you want to "add" to it-- like a breathing animation. Transform animations only.
Gesture: Things that get triggered by hand OR by the Expression menu. You can also use this for "idle animations" like a wagging tail, flapping wings, or moving ears. Transform animations only.
Action: Full override, similar to AV2 emotes. Transform animations only.
FX: Same as Gestures, but for everything that isn't a Transform position, rotation, or scale animation.

That's great, but let's go into some more detail.


The Base layer contains locomotion animations, including blend trees for walking, running, strafing. It also includes animation states for jumping, falling, falling fast, crouching, and crawling, among other things.

Keep in mind that if you put something in here, you'll have to redefine your locomotion animation states. This is pretty complex! Take a look at the example Base Playable Layer to see how complex it can get.

Animations in Base should only affect transforms, and all layers should be using Avatar Masks to ensure you're only affecting the appropriate transforms.


The Additive layer is meant for additive transform movement on top of humanoid bones that are animated in Base-- things like breathing animations that can "add on" to the Base layer.

If you want to add an idle animation to non-humanoid bones-- like a tail, ears, or etc-- use Gesture instead! Additive is specifically for humanoid bones.

The Additive layer is special because it is always set to "Additive" blending. In short, if you've got a transform that moves during locomotion, the Additive animation will "add" its animation on top. This can act really weirdly if you do crazy things to bones in Additive, so try to keep it pretty minimal.


Additive First Layer Avatar Mask Ignored

The first layer (base layer, 0th layer, etc)'s Avatar Mask is ignored. This is for internal masking purposes. You can still mask other layers, but any mask you apply to the first layer will be ignored.

Animations in Additive should only affect transforms.


The Gesture layer is for animations that need to act on individual body parts while still playing the underlying animations for the rest of the body. Kind of like AV2 Gestures, but applied to any part of the body.

Utilize Avatar Masking to ensure that the animations only affect the parts of the avatar you want to animate! So, if you want your gesture parameters to only make hand shapes for left/right hand, you'll want to mask out those hands on each of the layers.

In addition, if you want to have an "idle" animation for non-humanoid bones like a tail, wings, ears, etc-- Gesture is where you should put it.

Animations in Gesture should only affect transforms.


The Action layer is for bone animations that will override all other layers, when you need to take over total control of the character. Basically, think AV2 "Emotes".

This layer is blended to zero by default. Before you do anything in the action layer, you need to use the Playable Layer Control State Behavior to blend this layer up before transitioning to the actual action you're performing! Make sure you blend it back to zero when you're done.

Animations in Action should only affect transforms.


FX is a special layer. On every other layer, you should not be using material animations, shader property animations, or blendshape animations, because they aren't copied to your mirror clone. Only transforms are.

However, in the FX layer, all of that is copied over! You put your visemes here, if you're using Viseme parameters. In other words, everything that isn't a transform/muscle animation should go into the FX layer. This includes (but is not limited to) things like enabling/disabling GameObjects, components, material swaps, shader animations, particle system animating, etc.


FX First Layer Avatar Mask Ignored

The first layer (base layer, 0th layer, etc)'s Avatar Mask is ignored. This is for internal masking purposes. You can still mask other layers, but any mask you apply to the first layer will be ignored.

Animations in FX can be anything EXCEPT transform animations.

Additional Poses

There are some additional poses available for Avatars 3.0 avatars. The buttons for these are under the Playable Layers.


You can now provide your own T-Pose!

The T-Pose is used to determine various measurements of your avatar, especially for placement of your viewpoint (or view-ball). Viewpoint is dependent entirely on where your view-ball is when your avatar is in this T-Pose animation you provide.

Standard T-Pose - [Mixamo]( T-Pose - [Mixamo](

Standard T-Pose - Mixamo

Secondly, it is important for the wrist alignment/twist. The way your wrists are lined up in relation to the palm-down position will affect how your controller twisting in space will turn your wrist and arm.

Finally, your t-pose determines your wingspan-- your full length of your arms when in T-Pose. This also determines your avatar's interpupillary distance (IPD), or the distance between your avatars eyes. Having arms that are too long will make your IPD wider, making everything seem smaller. Having arms that are too short will make your IPD narrower, making everything seem larger.

In addition, (significant) joint bends in T-Pose aren't a good thing. As an example, if your elbows are bent in T-pose, this may affect many different things about your avatar that work off your proportions.

IK Pose

IK Pose is used to determine major joint bends. In the IK pose, your joints should be bent slightly in the direction they're intended to bend.

As an example, VRChat will look at the elbow bend from your IK Pose and determine if there is a angle bend in any given direction. That bend determines how your elbow bends.

Sitting Pose

The controller used in this slot is used for both animation and posing. When you sit, the viewpoint of your avatar is used for calibration. The animation is played, allowing you to create a "sitting down" animation, as well as a "sitting" idle animation.

If you want to make your own, fair warning: this can take some significant tweaking to get right! You may want to employ transition states for sitting down/standing up that will help a bit with how your avatar looks while sitting.

Did this page help you?