Animation State Manager
Animation State Manager is a custom component that provides a simple way to manage your animation states, blend between animations, and configure transitions when certain conditions are met.
It is available for installation in the Lens Studio Asset Library.
Video guide
Please check out this guide for a setup of the Animation State Manager from scratch.
Inputs
Animation Player - the Animation Player to control.
Animation States
Animation States - This section defines a set of animation states that your animated object can be in. Additionally, there are several built-in states such as Entry and Exit, which allow you to create initial and final transitions.
Enabled - When checked, allows editing of the Animation States section.
Create from Clips - Enable this option to generate states from animation clips that are added to the referenced Animation Player. This is a simple option if you're not using blend trees or are using clips for multiple states.
Custom States - Define a list of states on top of the existing clips.
- Name - The Animation State name, used for referencing in scripts or in the Transitions section.
- Source - The type of state, which can either be From Single Clip or From Blend Tree.
A Custom State from the Blend Tree allows you to blend multiple animations based on a float parameter. For example, this could be used to smoothly transition between Idle, Walk, and Run animations, or between running forward, right, and left.
A parameter used for a blend tree must be defined in the Parameters section, described below.
Each blend tree clip is an structure of:
Clip Name - The name of a clip used for a blend tree. In the screenshot example, it blends between 3 animations: idle, walk, and run. The diagram below shows which animation is playing at a given moment.
Threshold - The value of the parameter that corresponds to the current animation clip being at full effect.
Normalize Clip Duration - Use normalized clip time for blending. Useful for looped animations like walk or run cycles that often have different duration.
Blend Parameter - a name of parameter used to control a blend tree.
Parameters
The Parameters section allows you to define variables that control animations and transitions. For example, you can set a character to crawl or stand based on whether a boolean parameter is true
or false
. You can also trigger an animation using a trigger parameter, or switch between equivalent states when an integer parameter changes.
- Enabled: Enables editing of the Parameters section.
- Parameters: An array of parameters that control the state manager. Each element includes:
- Name: The parameter's name.
- Type: The parameter type, which can be
Float
,Int
,Boolean
, orTrigger
. - Value: The initial value of the parameter.
Transitions
The Transition section allows you to specify when and how to transition between states.
The Transitions section defines how the system moves between animation states.
- Enabled: When checked, allows editing of the Transitions section.
- Transitions: An array of transitions, where each transition is structured as follows:
- Enabled: Enable or disable the current transition.
- From: The state from which the transition starts. Possible values include:
- Entry: The initial entry state, used to initialize the default animation.
- Any: A transition that can occur from any state.
- Specific State: A named state from which the transition begins.
- To: The state to which the transition leads. Possible values include:
- Specific State: A named state to transition to.
- Exit: Stops all animations.
- Duration: The transition duration in seconds.
- Has Exit Time: If enabled, the transition occurs automatically after the animation completes.
- Exit Time - a normalized time [0, 1] of a from animation when the transition should start.
Conditions: A list of conditions that must be satisfied for the transition to occur. Each condition forms a logical expression applied to one of the parameters—such as "is less" or "is greater" for a float parameter, or "is true" for a boolean parameter. The transition begins when all conditions are true simultaneously. Each condition is defined by the following fields:
- Name: The name of the parameter.
- Type: The type of the parameter, which must match the one specified above.
- Function:(Optional) The logical operator applied to the parameter (e.g., "is less," "is more," "is true"). This depends on the parameter type.
- Value: (Optional) The value to compare against the parameter.
Scripting
Next come some of the custom component api description.
You can add a parameter to control animations by calling the addParameter
method with the parameter name and default value.
//@input Component.ScriptComponent animManager
script.animManager.addParameter('speed', 1.0);
To set the value of a parameter, use the setParameter method with the parameter name and the new value.
script.animManager.setParameter('speed', 1.5);
Set a trigger by calling setTrigger with the trigger name.
script.animManager.setTrigger('jump');
Reset a trigger by calling resetTrigger with the trigger name.
script.animManager.resetTrigger('jump');
Get a state to add callbacks or query its status using getState.
let state = {
stateName: 'Run',
type: script.animManager.StateType.Specific,
source: script.animManager.StateSource.SingleClip,
clipName: 'Idle',
};
Force a state change immediately or with a transition duration by calling setState.
script.animManager.setState('Idle', 0); // Immediately change to Idle state
script.animManager.setState('Run', 0.5); // Transition to Run state over 0.5 seconds
Define a new state from a configuration object using addStateFromConfig.
let state = {
stateName: 'Run',
source: 0, // From Single Clip
clipName: 'RunAnimationClip',
};
script.addStateFromConfig(state);
Triggering transitions with Behavior Script
If you prefer not to script, the Animation State Manager API functions are easily accessible from the Behavior script.
- Select -
Call Object API
Response. - Set
Call Type
toCall Function
. - Set
Function Name
tosetParameter
orsetTrigger
- Set
Argument 1
Type
tostring
and value to your parameter name. - Optionally set
Argument 2
to the desired type and value of your parameter.
Debugging
Please check the logger for warning messages. Additionally you can utilize the Show Debug checkbox and plug in a Text component to display current state, parameters and their values.