Skip to main content

Animator Parameters

warning

This document requires knowledge about Unity's Animator Controllers and Animation Parameters.

You can use animator parameters in your avatar's Playable Layers to control or affect your avatar's animator states.

tip

You should assume that parameters can always change. Avoid "dead ends" - if your states don't have an exit, your avatar's animator may break.

Built-in Parameters​

You can access VRChat's built-in avatar parameters by adding them to your avatar's Playable Layers. If you add one of these parameters, VRChat automatically updates its value based on what's happening in VRChat. For example, if you add the VelocityMagnitude parameter, its value updates based the player's current speed.

All built-in parameters are read-only. You cannot change them with an Expressions Menu or OSC.

The list below contains all of VRChat's built-in parameters, their description, their type, and their sync type.

NameDescriptionTypeSync
IsLocalTrue if the avatar is being worn locally, false otherwiseBoolNone
PreviewModeReturns 1 if the avatar is being previewed, 0 if it is notIntNone
VisemeOculus viseme index (0-14). When using Jawbone/Jawflap, range is 0-100 indicating volumeIntSpeech
VoiceMicrophone volume (0.0-1.0)FloatSpeech
GestureLeftGesture from L hand control (0-7)IntIK
GestureRightGesture from R hand control (0-7)IntIK
GestureLeftWeightAnalog trigger L (0.0-1.0)1FloatPlayable
GestureRightWeightAnalog trigger R (0.0-1.0)1FloatPlayable
AngularYAngular velocity on the Y axisFloatIK
VelocityXLateral move speed in m/sFloatIK
VelocityYVertical move speed in m/sFloatIK
VelocityZForward move speed in m/sFloatIK
VelocityMagnitudeTotal magnitude of velocityFloatIK
UprightHow "upright" you are. 0 is prone, 1 is standing straight upFloatIK
GroundedTrue if player touching groundBoolIK
SeatedTrue if player in stationBoolIK
AFKIs player unavailable (HMD proximity sensor / End key)BoolIK
TrackingTypeSee description belowIntPlayable
VRModeReturns 1 if the user is in VR, 0 if they are notIntIK
MuteSelfReturns true if the user has muted themselves, false if unmutedBoolPlayable
InStationReturns true if the user is in a station, false if notBoolIK
EarmuffsReturns true if the user's Earmuff feature is on, false if notBoolPlayable
IsOnFriendsListReturns true if the user viewing the avatar is friends with the user wearing it. false locally.BoolOther
AvatarVersionReturns 3 if the avatar was built using VRChat's SDK3 (2020.3.2) or later, 0 if not.IntIK
IsAnimatorEnabledReturns false one frame before the avatar's animator is disabled, and true when it's enabled.BoolNone

Eye and face tracking parameters​

Use these built-in parameters to choose animator states based on the user's tracking availability:

NameDescriptionTypeSync
UserEyeTrackingReturns true when eye tracking data is available. Automatic eye movement alone does not set this to true.BoolOther
UserFaceTrackingReturns true when face tracking is allowed and a face tracking source is active.BoolOther

Add these parameters as Bool parameters in your Animator Controller. You do not need to add them to your Expression Parameters asset, and they do not use your custom synced parameter budget. For example, use UserFaceTracking to switch between tracked facial expressions and gesture-driven expressions.

For your own avatar, VRChat calculates these values from your active tracking sources and tracking settings. Eye tracking can come from tracked eye look, tracked eyelids, or a source that supplies eye blendshapes directly, such as OSC face tracking.

For remote avatars, VRChat calculates these values from received tracking data rather than synchronizing the two booleans directly. Both values are true while native face tracking playback is active. Otherwise, received eye look or eyelid data sets UserEyeTracking, and legacy face tracking data sets UserFaceTracking. Both values are false when no visible tracking is available. Remote values can therefore differ from the wearer's local values.

These parameters describe the user's tracking, not whether the avatar supports the Face Tracking system. External applications can read them through OSC tracking status outputs.

Avatar Scaling Parameters​

Your Playable Layer can react to the player's current avatar scale by using the parameters below:

NameDescriptionTypeSync
ScaleModifiedReturns true if the user is scaled using avatar scaling, false if the avatar is at its default size.BoolPlayable
ScaleFactorRelation between the avatar's default height and the current height. An avatar with a default eye-height of 1m scaled to 2m will report 2.FloatPlayable
ScaleFactorInverseInverse relation (1/x) between the avatar's default height and the current height. An avatar with a default eye-height of 1m scaled to 2m will report 0.5. Might be inaccurate at extremes.FloatPlayable
EyeHeightAsMetersThe avatar's eye height in meters.FloatPlayable
EyeHeightAsPercentRelation of the avatar's eye height in meters relative to the default scaling limits (0.2-5.0). An avatar scaled to 2m will report (2.0 - 0.2) / (5.0 - 0.2) = 0.375.FloatPlayable

GestureLeft and GestureRight Values​

GestureLeft and GestureRight use these as their values:

IndexGesture
0Neutral
1Fist
2HandOpen
3FingerPoint
4Victory
5RockNRoll
6HandGun
7ThumbsUp

Viseme Values​

We use the Oculus viseme index, top to bottom, where sil is 0. For reference:

Viseme ParameterViseme
0sil
1pp
2ff
3th
4dd
5kk
6ch
7ss
8nn
9rr
10aa
11e
12i
13o
14u

AFK State​

The AFK state is triggered by:

  • The user removing the headset and the HMD proximity sensor returning that the headset is not being worn
  • A system menu is open. This depends on how the platform you're using delivers data when system menus are up-- for example, the Oculus Dash doesn't register as AFK, but SteamVR's menu does register as AFK. This is kind of a knock-on, and not a designed behavior.
  • The user has pressed the End key, toggling the AFK state.

TrackingType Parameter​

TrackingType indicates a few pieces of information.

If the value is 3, 4, or 6 while VRMode is 1, the value is indicating how many tracked points the wearer of the avatar has enabled and currently tracked. This value can change! If a user in 6-point tracking removes their extra three points of tracking, they will go from a value of 6 to a value of 3. Take this into account when you design your animator.

If the value is 0, 1, or 2 while VRMode is 1, the value indicates that the avatar is still initializing. You should not design animators to branch based off this combination of values, and it should instead wait for a "valid" value of 3, 4, or 6.

Account for changes

During avatar initialization, this value may change! Ensure that your animator accounts for possible changes, and that it doesn't "dead-end" into any branch.

ParameterDescription
0Uninitialized. Usually only occurs when the user is switching avatars and their IK isn't sending yet.
1Generic rig. The user might have tracking of any kind on, but the avatar is rigged as Generic,so tracking is ignored. Might be a desktop user if VRMode is 0.
2Only occurs with AV2,and therefore isn't a state you should expect to be in for very long for AV3 controllers on avatars. May still occur with SDK3 stations.
Hands-only tracking with no fingers. This will only occur in states that are transitions-- as in, you should expect TrackingType to change again, and the avatar should not stay in this state.
3Head and hands tracking. If VRMode is 1, this user is in 3-point VR. If VRMode is 0, this is a Desktop user in a humanoid avatar.
44-point VR user. Head, hands, and hip.
55-point VR user. Head, hands and feet tracked. Basically full Body Tracking but without the hip.
6Full Body Tracking VR user. Head, hands, hip, and feet tracked.

Custom Parameters​

You can add your own parameters to your avatar's Playable Layers.

You must create a Expression Parameters asset, which allows you to control parameters in VRChat. For example, you can set up an expressions menu and allow users to customize your avatar in VRChat.

Expression Parameters Asset​

An Expression Parameters asset contains the list of custom parameters that your Playable Layers can use. Each parameter has a name, type, and default value. You can also choose whether the parameter should be synchronized for other players, which allows other players to see changes caused by the animator and custom parameters.

If you tick "Show Advanced Options", you can also adjust each avatar's bit width (how many bits of space it takes up) and its representation (signed or unsigned). A label shows you the range of allowed values for the settings you've chosen.

What expression parameters look like by default.

tip

Learn how to create an Expression Paramaters asset by reading the Expressions Menu documentation.

How to Control Custom Parameters​

After setting up custom parameters in your avatar's Playable Layers and Expression Parameters asset, you can control them in the following ways:

  • Set up an Expressions Menu, which allows users to easily control the parameters in VRChat, e.g., switch between outfits or play custom animations. Expressions Menus are the easiest and most common method to control custom parameters.
  • You can attach the state behaviour Avatar Parameter Driver to states in your Playable Layer. It can automatically set, add, or randomize parameters that you defined in your Expression Parameters asset.
  • You can set up your avatar for OSC, allowing users and third-party tools to control parameters. For example, VRCFaceTracking uses face and eye tracking hardware to control an avatar's facial expression parameters.
  • You can use Face Tracking Parameter Behaviors with Forward to Animator to send calculated tracking, voice, or individual viseme strengths to named parameters.
    • These parameters usually do not need Synced enabled, because VRChat syncs face tracking data separately. See Face Tracking networking.

Default AV3 Aliasing​

There's a few "defaults" in use by the template AV3 VRChat controllers that you can use if you don't want to build out your own controllers. These won't collide with your own use (as long as you don't name them the same thing) thanks to aliasing.

In particular, the Default Action and FX layers use aliasing. You don't need to worry about using a Expression that is in these layers.

Actions use aliased parameters named VRCEmote, which is an Int with a range of 1 to 16.

FX uses aliased Float parameters called VRCFaceBlendH (-1,1) and VRCFaceBlendV (-1,1), if you want to try out your own menus to use them. The default FX layer requires that you have a skinned mesh named Body with mood_happy , mood_sad , mood_surprised , and mood_angry blendshapes.

To restate, if you have an avatar that you upload as an Avatar3 avatar without any custom Playable layers, you'll be able to use some built-in emotes with them as long as you've got the above-named blendshapes.

If you also have an eyes_closed blendshape, it'll close them when you use the default Die emote or go AFK.

Cross-Platform Parameter Sync​

When using an avatar that has both Quest and PC versions uploaded, parameters are synced by their position in the parameters list and their parameter type, not by the names of the parameters. For a given parameter to sync between PC and Quest, it has to be in the same position in the parameter list, and have the same parameter type.

Given this, you should always use the same Expression Parameters asset for both the PC and Quest versions of an avatar, even if one version doesn't make use of all the parameters.

Parameter Types​

You can define the following types of parameters in your Expression Parameters asset:

Parameter TypeDefault RangeDefault Memory UsageNotes
int0 to 2558 bitsUnsigned integer.
float-1.0 to 1.08 bitsSigned fixed-point decimal.
boolTrue or False1 bitA single binary value.

Each synced parameter uses a certain amount of parameter memory. VRChat can synchronize up to 256 bits of custom parameters. VRChat also limits your avatar to 8192 total custom Expression Parameters (synced and unsynced). Built-in parameters do not count toward these limits.

Remotely synced int values start with a memory usage of 8 bits, allowing for values from 0 to 255 inclusive.

  • If you don't need that full range, you can reduce the bit width to save some space in your avatar's 256 bit allowance while reducing the maximum range of numbers the integer can hold. The minimum bit width is 2 bits.
  • If you want to use negative values, you can mark the integer as signed instead of unsigned. This reduces the maximum value in exchange for being able to express negative numbers.

Remotely synced float values also start with a memory usage of 8 bits, which gives them a precision of 1/127 over the network. They can always store -1.0, 0.0, and 1.0 precisely. When updated locally, such as with OSC, float values are stored as native (32-bit) floating-point values in animators.

  • Similar to integers, you can reduce the bit width of floats to save space. This reduces the float's precision, so it should only be done when that precision isn't needed. The minimum bit width is 2 bits.
  • If you only want to express the values 0.0 to 1.0, you can mark the float as unsigned instead of signed. This reduces the range of the float in exchange for higher precision.

Parameter Interpolation​

If you enable interpolation, parameters change smoothly over a duration rather than instantly.

By default, parameters set by the local player do not interpolate. Instead, they snap immediately to their target values in the same frame they're set. Parameters that are set remotely (for example, someone else in the instance setting a new value for a synced parameter) interpolate over a short, automatically determined period. This helps smooth out sudden changes.

When setting up custom parameters, you can also configure a custom interpolation time for them. A parameter with a custom lerp time moves over that time from the old value to the new one whenever a new value is given. This same duration applies both locally and remotely.

Mismatched Parameter Type Conversion​

When you choose a parameter type in your animator, it's a good idea to choose the same type as the built-in parameter or custom parameter you're trying to use. For example: If you use VRChat's built-in AFK parameter in your animator, you should choose the type bool.

However, you can choose a mismatched type for your parameters. VRChat will try convert the parameter's value to the type used by the animator. For example, if you choose the type float for your AFK parameter, VRChat will automatically set AFK to 1.0 or 0.0 instead of true or false. This also allows you to use the AFK parameter in your Animator's Blend Tree.

The table below shows how converting a mismatched parameter changes it.

Source TypeAnimator TypeConversion BehaviorExample
intfloatDirectly converted to float.1 → 1.0
intbool0 is false, anything else is true1 → true
floatintRounded to closest int (same as Mathf.Round)0.5 → 0, 0.6 → 1, 1.5 → 2
floatbool0.0 is false, anything else is true0.5 → true
boolinttrue is 1, false is 0true → 1
boolfloattrue is 1.0, false is 0.0true → 1.0

Trigger Typed Parameters​

At this time we don't recommend using Trigger type parameters in your animation controllers. These values can become de-synced between versions of your avatar, including remote clients viewing your avatar or in special situations like viewing your avatar in the mirror. If you are going to represent the state of your avatar please use either Int, Float or Bool typed parameters.

Sync Types​

VRChat synchronizes most built-in parameters with other players in the instance, and you can enable synchronization for your own custom parameters.

The sync type determines how VRChat syncs each parameter. Parameters use one of the following sync types:

  • Speech
    • Only used for visemes.
    • Driven Oculus Lipsync output parameters depending on your speech.
    • Updated locally, not directly synced (because its driven by audio)
  • Playable
    • A slower sync mode meant to synchronize longer-running animation states.
    • Updates every 0.1 to 1 seconds as needed based on parameter changes (1 to 10 updates per second), but you shouldn't rely on it for fast sync.
  • IK
    • A faster sync mode meant to synchronize frequently-changing values.
    • Updates continuously every 0.1 seconds (10 updates per second), and interpolates float values locally for remote users.
    • Depending on the parameter, this may also just be calculated based on the avatar's locally rendered IK state.
  • None
    • This parameter is not synchronized with other player.
    • For example, IsLocal is always true for the local player's avatar and false for the avatars of other players.

If you enable synchronization for your custom parameters, VRChat usually uses the Playable sync type. However, when you control a parameter with a Puppet control, VRChat switches from Playable to IK sync, improving the update rate smooth interpolation. When you close the Puppet control, it returns to Playable sync.

Footnotes​

  1. GestureLeftWeight and GestureRightWeight go from 0.0 to 1.0 in various gestures depending on the trigger pull. For example, if you make a fist but don't pull the trigger on the left hand, GestureLeft will be 1, but GestureLeftWeight will be 0.0. When you start pulling the trigger, it will climb from 0.0 towards 1.0. This can be used to create "analog" gestures or conditionally detect various things. ↩ ↩2