AV3 Walkthrough - Part 4 - Animation Parameters

For this step, you should know about Animation Parameters. They’re actually pretty straight-forward-- basically, a variable that you can observe with transitions. You may have already messed with them, but let’s make it formal.

With Avatars 3.0, you’ve got access to a BUNCH of built-in parameters. Here’s the table from our docs:

Name Description Type Sync
IsLocal True if the avatar is being worn locally, false otherwise Bool None
Viseme Oculus viseme number (0-14) Int Speech
GestureLeft Gesture from L hand control (0-7) Int IK
GestureRight Gesture from R hand control (0-7) Int IK
GestureLeftWeight Analog trigger L (0.0-1.0) Float IK
GestureRightWeight Analog trigger R (0.0-1.0) Float IK
VelocityX lateral move speed in m/s Float IK
VelocityY vertical move speed in m/s Float IK
VelocityZ forward move speed in m/s Float IK
Grounded true if player touching ground Bool IK
Seated true if player in station Bool IK
AFK is player unavailable (HMD proximity sensor / End key) Bool IK
Stage1 - Stage16 user defined param, Int (0-255) or Float (-1.0-1.0) Int / Float IK or Playable

There’s some built-ins that are very useful, like:

  • GestureLeft and Right, which tell you what gesture you’re performing
  • VelocityX/Y/Z, which tell you your movement speed
  • AFK, which is true when a VR player has their headset off (HMD sensor doesn’t see your head) or when a Desktop player has pressed the End key

… and many more, as you can see!

There’s also ones that you can define yourself, and we’ve given you complete control over them.

Stage1-16 are user defined states. These are Int or Float variables with a range of 0-255 or -1.0 to 1.0. You can set them and use them however you want. If you’re not using them in a Puppet menu, they’re synced using the Playable sync-- about once per second. If you’re using them in a Puppet menu, they upgrade to IK sync, which is much faster.

You define Stage variable names and what type they are by using the Stage Parameters scriptable object.

As long as you’re somewhat familiar with animator transitions (they’re a base Unity feature, so hopefully you’ve read up on them!) you can use animation parameters quite easily. They’re what drive the logic of animators.

Custom Expressions Menus

So, how do you make your own menu to drive these parameters? Easy! You create a custom ExpressionsMenu object. Right click in a folder in your Project pane, click Create, then VRC Scriptable Objects, then finally Expressions Menu.

By default, there’s not much going on inside one of these:


Before we get started, we should probably fill that Stage Parameters slot! Same way as before-- click inside a folder in your Project pane, click Create, then VRC Scriptable Objects, then Stage Parameters. You’ll get a new asset that looks like this:

This is where you set up Stage parameter aliasing. Basically, you can name these whatever you want, and you can refer to these parameters by the aliased name. In fact, we pre-populate the first few fields with the requirements for the default controllers.

Aliasing helps keep things organized and self-documents what parameters do what! We’ll continue to refer to these as Stage variables, but you can name them whatever.

You also can set the type of these variables as well. You can use Int with a range of 0 to 255, or Float with a range of -1.0 to 1.0. Int is probably most useful for creating your own state machine that you can keep track of across Playable layers. Float is probably more useful for Puppet menus, but you could also use it for things like Hue adjustment on clothes. Of course, you can do what you want!

Here’s how I have mine set up:


Anyways, let’s slot the StageParams back into the Expression Menu object:


Now, let’s add a control! I’ve already got one added but uh, ignore that for a sec. :upside_down_face:


From here, you can set the name of the control, the icon for it, the type of control it is, and the order it will show up. Here’s one I made for some expressions, using the “Two Axis Puppet” control type:

There’s some new fields you’re seeing. “Parameter” lets me choose a single parameter that is set to the “Value” field’s value when I enter this control. I’m using the one I named MyState. This basically lets me switch my “mode” into FaceEmotions mode, so I can get into a “ready” state in my animator.

In short, entering the menu will set MyState to the value 1. As noted, I use this to enter a “waiting for expressions” state.

Pushing my joystick up will increase the value for PuppetMenuV towards 1.0. I’ve set up my animator to sit in the “ready” state until it detects my parameters passing a certain value (I used 0.5). Once it passes that value I’ve chosen in the transition condition, it’ll swap to that state, and play that animation! Repeat that logic 3 more times using PuppetMenuV and PuppetMenuH accounting for -1.0 and 1.0 on each axis, and I’ve mapped both of my axes.

Of course, I’ve set my own Icon for the Puppet menu, so I’ll see that icon when I go to select it in the Expressions menu. I can also set icons for each of the directions, if I choose. I’ve used some of the examples given in the SDK, but left Smug blank because I don’t have one yet.

There’s some other control types, too:

Button is pretty straightforward. It’ll set the value to the param as long as your cursor remains on that part of the Expression menu. When you release the cursor from that position, the parameter is reset to zero.

Toggle is a bit different-- it is basically a checkbox. Turning it on will set the Parameter you’ve defined to the Value you’ve defined. When you turn it off, the Parameter will be set to zero.

Submenu is pretty crazy. You get to set a parameter to a value if you’d like, but you can also open another custom Expressions menu. Of course, that custom Expressions menu can also have a Sub Menu. And so on. And so on, and so on, and so on… its turtles all the way down, baby!

When you go into a submenu, the parameter is set to the value you specify. When you exit out of that particular submenu, the parameter is set to zero.

We’ve already covered two-axis puppet, but here’s a pretty picture anyways.

Four-axis puppet is a little different-- you can set four variables instead of two! There’s a few cases where you’d want to use this over two-axis-- but none that I can personally think of with my experimentation so far. You can probably think of some better cases than I can!

Finally, we’ve got Radial Puppet. The “Parameter Rotation” describes how far you have “turned up” the outside bar. It’s kinda like a progress bar that you fill up yourself.

So, for this step, we want you to explore these custom Expression menus! You’ve got some choice here, but we’d like you to make one or two menus that control something on your avatar. You could be like me and make a menu that controls your expressions (UI on this GIF is a bit old, but you get the idea):

… you could make one that makes you blend between a bunch of dances, blend between face shapes, blend between colors on a part of your outfit, toggle on a jacket, summon different colored swords into your hand… whatever! The sky’s the limit, and this is where AV3 really starts opening up.

1 Like