State Behaviors

🚧

Unity Knowledge Required

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

When you've got a specific state selected in the Animator view, you'll be able to add State Behaviors. They're a bit like components for states. They do different things. Try adding them, and you'll see what they can do!

All state behaviors run on the first frame of the transition into that state.

State behaviors should run no matter how long the state machine remains in the state containing the state behavior.

🚧

The term "should" is deliberately used here, as in the Unity documentation does not define any guarantee that state behaviors will execute given very small transition or state durations.

If you wanted to be completely safe, ensure the total time spent in the state containing the state behavior and any transitions directly to that state is a minimum of 0.02 seconds-- although in practice, this doesn't seem to be required.

Animator Layer Controller

589589

The Animator Layer Control allows you to blend the weight of a specific Animator Layer inside any given Playable Layer over any given time.

If the state is exited mid-blend duration, the target layer is immediately set to the goal weight.

The layer weight will remain until some other state runs this State Behavior again and resets it.

Property Name

Purpose

Playable

Allows you to select which Playable Layer you're affecting.

Layer

The Index of the Playable Layer you wish to affect. You can't change the weight of the 0th (base) layer-- it is always set to 1.0 weight.

Goal Weight

Define the weight you want to blend to.

Blend Duration

Define the time period (in seconds) that you want the blend to take. 0 means instant.

Debug String

When this StateBehavior runs, this string will be printed to the output log. Useful for debugging.

Animator Locomotion Control

590590

The Animator Locomotion Control allows you to disable locomotion in a given state of an animator.

The Locomotion state will remain until some other state runs this State Behavior again and resets it.

Property Name

Purpose

Disable Locomotion

If set to True, locomotion (moving with the controls) will be disabled. Roomscale movement will still be possible. If set to False, will enable locomotion.

Debug String

When this StateBehavior runs, this string will be printed to the output log. Useful for debugging.

Animator Temporary Pose Space

615615

The Animator Temporary Pose Space control allows you to move the viewpoint of the person wearing the avatar to the head at that given point of the animator state.

The view will remain set until some other state runs this State Behavior again and resets or clears it.

This behavior is executed when the delay time has elapsed.

Animator Temporary Pose Space should only be used when the view height needs to update due to a posture change, like sitting or laying on the ground. It cannot be used to "scale" the avatar being worn, and will cause major breaking problems if used in this manner.

❗️

This state behavior will not execute if the state this behavior is on is exited or interrupted before Delay Time elapses!

Pose Space

Enter or exit. Enter sets the pose space, exit will clear it to default.

Fixed Delay

Should the delay time be a fixed period of time, or a percentage of the state's duration?

Delay Time

If given a value, the viewpoint will be set after a delay. Useful if you're blending into an animation over a certain time.

Debug String

When this StateBehavior runs, this string will be printed to the output log. Useful for debugging.

Animator Tracking Control

577577

The Animator Tracking Control allows you to enable or disable IK or simulated movement on various different parts of the avatar body. Setting the option to "No Change" will not change the body part from its current value. "Tracking" will set it to following IK or simulated movement. "Animation" will force that body part to respect values as given by the avatar's Animator.

If you set all IK tracking points to Animation, your animation will play as the Animation remotely, instead of being translated through Networked IK. For the various types of tracking, these "IK tracking points" are:

  • Desktop: Head, Left Hand, Right Hand
  • 3pt Tracking: Head, Left Hand, Right Hand
  • 6pt / FBT Tracking: Head, Left Hand, Right Hand, Hip, Left Foot, Right Foot

📘

All parts are IK-driven, aside from the Eyes and Eyelid, which are simulated. Mouth and Jaw are driven by visemes.

As an example, setting Left and Right Hand to Animation will ignore the position of the hands (and arms) as defined by IK, and will instead use any currently-active state's motion to define the position of the hands and arms. Setting them back to Tracking will use IK instead.

Setting Eyes & Eyelid to Animation will disable eye movement and eyelid blinking. Setting Eyes & Eyelid to Tracking will re-enable the simulated eye movement and blinking.

Setting Mouth and Jaw to Animation will disable visemes, although viseme parameters will still be sent. Setting Mouth and Jaw will re-enable visemes.

The Tracking setting will be kept until some other state runs this State Behavior again and resets it.

Property Name

Purpose

Tracking Control

See description above.

Debug String

When this StateBehavior runs, this string will be printed to the output log. Useful for debugging.

Avatar Parameter Driver

761761

The Avatar Parameter Driver can manipulate Animator Parameters in a variety of ways. A single Avatar Parameter can perform multiple operations, and they are done in order from top to bottom. These operations are completed once upon entry to the State upon which the behavior resides.

Local Only will cause the driver to only operate locally, as a shortcut instead of detecting isLocal.

Clicking "Add" will add a new operation to the Driver. The first type (which is selected by default) is "Set".

If modifying a synced parameter (anything defined in the VRCExpressionParameters object) those values will be clamped to their maximum range. Int [0,255] Float [-1,1].

However, Parameters only defined in the Animation Controller (aka, "local parameters") can still be modified by a parameter driver. Those values aren't clamped.

You also cannot drive any of the VRChat-defined Animator Parameters.

Set, Add, Random, and Copy work for float and int. Set, Random, and Copy work for bool.

Set

Set will simply set the Value to the named Parameter in Destination.

772772

Add

Add will add the Value to the named Parameter in Destination.

As the component points out, using Add may not produce the same result when run on a remote instance of the avatar. When using Add, it is suggested to use a synced Destination Parameter and only run the driver locally.

774774

Random

Random will set the Destination Parameter to a random number between Min Value and Max Value.

As the component points out, using Random may not produce the same result when run on a remote instance of the avatar. When using Random, it is suggested to use a synced Destination Parameter and only run the driver locally.

777777

Copy

Copy will set the value of the Destination Parameter to the Source Parameter. This can be used to set one float to match another float, to remap one float into a different range, or to convert between two different types entirely.

766766

Converting between types

When converting from a bool, False counts as 0 and True counts as 1.

When converting to a bool, 0 is False and anything else is True.
When converting to an int, it will always round down to the nearest whole number.
When converting to a float, it will directly copy the value, even if it goes outside the range that it is capable of syncing to other players.

Custom Ranges

You can also use the Convert Range checkbox to enable some additional UI that allows you to set custom conversion ranges. This can be used to remap values or to have more control over exactly how it converts from one type to another type.

845845

Playable Layer Control

580580

The Playable Layer Control allows you to blend the weight of the entire Playable Layer to a specified value over specified duration. Very similar to Animator Layer Control, but instead controls the entire Playable Layer.

The Action Playable layer will use this State Behavior often, as the Action layer has weight zero by default, and should always be blended back to zero after the animation is complete.

If the state is exited mid-blend duration, the playable layer is immediately set to the goal weight.

Property Name

Purpose

Layer

The Playable Layer to affect.

Goal Weight

The Playable layer weight to target after blending is complete.

Blend Duration

The amount of time to take to blend to the layer. Zero is instant.

Debug String

When this StateBehavior runs, this string will be printed to the output log. Useful for debugging.


Did this page help you?