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

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

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

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

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

The Avatar Parameter Driver will set the value of any given parameter defined in this Playable Layer as defined. This is primarily meant for Expression parameters and their aliases.

You can use this State Behavior to drive local parameters, but they will not be synced across the network. You also cannot drive any of the VRChat-defined Animator Parameters.

Property Name

Purpose

Add Parameter (button)

Adds a parameter to drive with this State Behavior.

Name

Choose the Animation Parameter to drive with this State Behavior.

Value

Choose the value that the defined Animation Parameter will be driven to when this State Behavior runs.

Playable Layer Control

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?