AV3 Walkthrough - Part 3 - Weights, Blending, and Tracking

Hey, that last one was pretty short, especially if you’re working a bit ahead of the class. Here’s something a bit more complicated.

Alrighty, this is going to get a little complicated. Let’s explain some things, first.

Let’s talk about the playable layers. These are in the order that they’re applied! In other words, if you have something animated in Additive, and also animate it in Gesture-- it’ll be affected. How it is affected depends on your layer setups, blending modes, and blending weights. These are things you really shouldn’t worry too much about just yet-- just know that settings will change how transform animations mix (or blend) together.

Base Playable Layer

The Base playable layer is exceedingly important. It contains your locomotion blendtree. It is complex. Like, really, really complex. If you want to mess with it, feel free-- we include an example Base controller with the SDK, including “proxy” animations. Those proxy animations are replaced with the built-in VRChat animations if you leave them. If you replace them (like if you want a custom crawl or prone animation), we won’t touch those.

That being said, Base is complicated. Careful.

Additive Playable Layer

The Additive playable layer is for transform animations that layer “on top” of Base. This layer is meant for subtle secondary motion on top of the locomotion layer. Breathing, stuff like that.

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.

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. Putting those kinds of animations in Additive isn’t correct, because unless you’ve animated your non-humanoid bones in Base (you almost certainly haven’t), you’re “adding on” to a non-existent animation. So… you get weird results. Just use Gesture for those types of things.

Important Note
If you’re using a custom Additive layer, you MUST use an avatar mask! This mask should have the humanoid muscles selected (as shown below), with the IK circles unselected. In addition, you should import your Avatar from your model’s prefab and ensure that all transforms have been turned off.

Gesture Playable Layer

The Gesture playable layer is intended for transform animations that only apply to certain body parts. Basically, this is where you’d want to put things like custom hand shapes on gestures!

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.

If you replace the Gesture Playable layer, you’ll lose the default Gestures. You won’t notice this if you’re using Index-- as finger tracking overrides finger positions during gestures.

The reason this is a separate layer is for organizational purposes. The layer itself isn’t too special-- it is weighted to 1 by default. However, you’ll want to use a thing called an Avatar Mask. In fact, the layer requires that the Base animator layer have a mask.

You make an Avatar Mask in the Project window-- it is a file. You’ll find it in the root of the Create context menu:

Once you create it, you’ll be able to select out parts of the avatar you want to mask. You’ll probably want to import your own avatar, if you want to affect parts of the avatar that aren’t part of the default humanoid rig. As an example, here’s an Avatar Mask where only the Left Hand is permitted to animate:

You can see that I also added my rig in here by defining my avatar, and then unchecked everything else. You can click just outside any of the body parts on the Humanoid section to select-deselect all.

You can define masks for each Animator Layer (not Playable Layer!) using the little gear next to the layer, inside the Animator window.


FINALLY, one last important thing about Avatar Masks-- they layer. If you’ve got something masked in your top Animation Layer, that mask carries downwards to the other layers. So, to be safe, you’d want to have the mask you’re using in the top animation layer be the result of adding all the lower masks together. If your Gesture Playable Layer has Left and Right hand layers, you’ll want to mask in the Left hand on the LeftHand layer, the Right hand on the RightHand layer, and in the top “Base” animator layer-- mask in both the left and right hand. Got it?

To sum this up: the Avatar Mask on the base animator layer (as in, the topmost animator layer) must be the total mask of other avatar masks in that entire particular playable layer. This applies to all layers that use avatar masks.

So, why is this important? You know how in AV2 you make a gesture override by putting the same hand shape on both hands-- but when you only do it on your left hand, it only plays on the left hand? Maaaasks. :mage:

Are masks necessary? Not on all layers. (Gesture requires one. Read below!) They can help a lot, though, especially when dealing with mirrored animations that might only apply to one half at a time.

One Exception
The Gesture layer expects you to have a mask in the base layer. If you don’t use one in Gesture, you’re going to get errors.

In addition, if you create your own Gesture layer, you’ll lose the default hand shapes. You might want to work off the template! You won’t really notice this if you’re an Index user, BTW. Unless you set up animation stops via the Tracking State Behavior, your fingers will always follow finger tracking while using an Index.

Anyways, one application in the Gesture Playable layer is to create the setup described above, and then create a state machine that watches the Gesture parameter to move to the different gesture states. Remember, you should only be using Transform animations in the Gesture Playable layer!

Action Playable Layer

The Action playable layer is for transform animations that you “call up” using animation parameters-- basically like AV2 emotes, but you’re calling them from the Expression menu. If you want to do a dance that you can turn on and off, go into a ground-sitting mode, or scream-attack-eat-die :chicken:, this is where you do it.

The Action layer is special. By default, its weight is set to zero-- it won’t have anything playing. If you want to do something with the Action layer, you MUST set its weight to 1 first with the VRCPlayableLayerControl State Behavior. It looks like this!


You add this to an animation state. It’s kind of like a Unity Component, if States were GameObjects.

When you are “setting up” to do an animation in the Action playable layer, you must first set the Playable Layer weight to 1-- otherwise, the animation won’t play! You can also set it to anything else, if you want to blend with animations from “lower” layers like Additive or Base.

Once your Action animation is exiting, make sure you set the Playable weight back to zero.

Oh, yeah! You should probably read about Animation parameters. They’re pretty simple-- they’re basically variables that animators can read and do things based on their value. You can also write to a few of them with the Avatar Parameter Driver State Behavior, which you can read about in our documentation. That’s more complex, though. Don’t worry about that for now.

Anyways, here’s a quick example of an animation in Action using the AFK param to detect when the VR headset is off, or when you press the End key in Desktop.

But wait! There’s MORE!

In order for the AFK animation to “take over” the character, you have to disable input from things like IK. You don’t want to track your hands when you’re AFK. For that, we’ll need to use another State Behavior. This one is called VRCAnimatorTrackingControl. This is what it looks like.


Setting these to Animation will cause VRChat to ignore the tracking data being sent in for that particular body part.

My AFK animation uses basically all my body parts, so I want to ignore all tracking-- including eye movement/blink, because I also detect AFK state in the FX layer, and change my face shape. I put them on the same states I’m using to blend the Playable layer in and out.

Don’t attempt to use VRCAnimatorTrackingControl in multiple Playable Layers at the same time. I did this while trying to set up my eyes to close when I go AFK-- in addition to overriding tracking in Action, I did it in FX, too. I got weird behavior because I was setting and unsetting a bunch of things “simultaneously”, giving me unpredictable results.

Final tip: This is a lot like the PlayableLayerControl, where you have to unset these settings back to default (all false) upon exiting the animation. This applies in all layers.

FX Playable Layer

The FX playable layer is only for non-transform animations. Don’t put transform animations into FX, and don’t put non-transform animations elsewhere. This does mean you’ll need to split animations if you’ve got blendshapes and transforms in the same animation. This is easy to do with a little Ctrl-X, Ctrl-V magic-- you can select entire keyframe sequences and separate them out easily.

If you don’t do this split, then you’ll get weird behavior in mirrors.

There’s not too much else special here, aside from that! That being said, we expect people to use the FX layer quite heavily, as people like to do stuff other than move transforms around. Don’t worry if your FX Playable gets heavy, that’s kinda how its supposed to work! Just keep adding layers. :wink:

So, with all that knowledge, here’s what we want you to try. Using the same cube that you added to your hip in AV3 Walkthrough - Part 2 - Playable Layers, make it spin instead. Now that you know what layers are intended for what, we’ll let you figure out which Playable Layer you should put it on. Hint: It isn’t Base! Well, it could be. You could totally put it on Base, but that Playable Layer is a bit spooky. Careful in there.

You should use Masks to ensure only the cube spins-- even if you’ve been careful with your animation.

For extra credit, make it so you can turn the spinning on and off with the Expression menu. But… we’ll get to that.


The use of masks is somewhat complicated by the fact that the Gesture playable layer assumes that you have a mask on the base animator layer. If you don’t, you’ll get an error and have problems.

In other words, to use the Gesture playable layer, you must have a mask in the base animator layer that is the sum total of all the masks in use in the gesture playable layer.

That being said, you don’t need to use the Gesture layer for this walk-through step. Action will work fine. Masks aren’t necessary-- and in fact, you don’t need to use masks at all if the object you’re animating is outside of the original rig of the model. It’s designed to localize animations to a body part on the avatar (which is defined by that original FBX). If you have an object outside of that, you can’t mask it.

1 Like