Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Animation controllers decide which animations to play and when. Each controller contains a list of states that play one or more animations, each of which can be blended by a Molang expression if so desired. Controller files are stored as JSON in the animation_controllers folder.
Note
If you haven't read the Introduction to Animation Controllers yet, check out that article first for a broader overview of the topic.
Animation Controller Format
{
"format_version": "1.17.30",
"animation_controllers": {
"controller.animation.sheep.move": {
"states": {
"default": {
"animations": [
{ "walk": "query.modified_move_speed" }
],
"transitions": [
{ "grazing": "query.is_grazing" }
]
},
"grazing": {
"animations": [ "grazing" ],
"transitions": [
{ "default": "query.all_animations_finished" }
]
}
}
}
}
}
States
A state defines a group of animations to process (each of which can have its blend value). Each state has an optional variables section, listing any number of variables that referenced animations can use. Each state also has one or more animations, using the name given in the entity's definition JSON.
State Blending
If you would like there to be a cross-fade between states when transitioning, simply set blend_transition to the time you would like the system to take in blending between the two states. This is done as a simple lerp between the two states over the time specified.
Example of State Blending
"controller.animation.tiger.move": {
"states": {
"default": {
"animations": [ "base_pose", "walk" ],
"transitions": [
{ "angry": "query.is_angry" } // transition to angry state if query.is_angry returns true
],
"blend_transition": 0.2 // when transitioning away from this state, cross-fade over 0.2 seconds
},
"angry": {
"animations": [ "roar", "extend_claws" ],
"transitions": [
{ "default": "query.any_animation_finished" } // transition back to default state when either the roar animation or extend_claws animation finishes
]
}
}
}
State Transitions
A state can specify any number of transition scripts, listed in order. Each transition has a target state to switch to, and a script for whether it should switch or not. For each transition in order, evaluate the script, and if it returns non-zero, switch to the specified state immediately.
Below, we use the crouch and stuck portions of the fox animation controller as an example that uses complex queries to define the animation state transitions.
Note
Only one transition will be processed per frame.
"animation_controllers" : {
"controller.animation.fox.move" : {
"initial_state" : "default",
"states" : {
"crouch" : {
"animations" : [
"look_at_target",
"crouch",
{
"walk" : "query.modified_move_speed"
}
],
"blend_transition" : 0.4,
"transitions" : [
{
"default" : "!query.is_stalking && !query.is_interested"
},
{
"wiggle" : "query.is_interested"
}
]
},
"stuck" : {
"animations" : [
"stuck",
{
"walk" : "math.cos(query.life_time * 20.0 * 53.7)"
}
],
"blend_transition" : 0.2,
"transitions" : [
{
"default" : "!query.is_stunned"
}
]
},
}
}
}
Example of State Transitions
"controller.animation.tiger.move": {
"states": {
"default": {
"animations": [ "base_pose", "walk" ],
"transitions": [
{ "angry": "query.is_angry" }, // transition to angry state if query.is_angry returns true
{ "tired": "variable.is_tired" } // transition to tired state if variable.is_tired returns true
]
},
"angry": {
"animations": [ "roar", "extend_claws" ],
"transitions": [
{ "default": "query.any_animation_finished" } // transition back to default state when either the roar animation or extend_claws animation finishes
]
},
"tired": {
"animations": [ "yawn", "stretch" ],
"transitions": [
{ "default": "query.all_animations_finished" } // transition back to default state when the yawn and stretch animations have both finished
]
}
}
}
State Variables
Variables are either set by the game or by a user-defined script that can be found in the entity definition JSON found in definitions/entity/<entity_name>.json. Variables have their value set by a Molang Expression. They can also have their value remapped via a linearly-interpolated curve.
State Variables Example
This defines a controller with a single state. It will create a variable variable.ground_speed_curve that lives on the entity only while processing the animation controller for that frame. It will take the value of query.ground_speed, then remap it to between 0.2 and 0.7 based on the value of query.ground_speed going from 0.0 to 1.0It will play one animation walk that will blend from 0.0 to 1.0 as the ground speed increases from stopped to 2.3 m/s. The remap curve can have any number of entries. The animation controller will then play the entity-referenced wiggle_nose animations, followed by the walk animation, scaling the latter by the value of variable.ground_speed_curve.
{
"format_version": "1.17.30",
"animation_controllers": {
"controller.animation.sheep.move": {
"states": {
"default": {
"variables": {
"ground_speed_curve": {
"input": "query.ground_speed",
"remap_curve": {
"0.0": 0.2,
"1.0": 0.7
}
}
},
"animations": [
"wiggle_nose",
{ "walk": "variable.ground_speed_curve" }
]
}
}
}
}
}
User-Defined Script Example
This script will set foo to the result of the sine of query.life_time to later be used in the animation or animation controller.
Note
pre_animation tells the script to figure out the values of those variables once a frame before animation occurs so that the animation can use those values in its formulas. If a variable didn't exist, it will create a new variable and its default value will be 0.0.
In definitions\entity\tiger.json:
{
"custom:tiger":{
"scripts":{
"pre_animation": {
"variable.foo = math.sin(query.life_time);"
}
}
}
}
Because foo is equal to a sin wave, its values will range from -1 to 1. This means that you will have a period from 0 to -1 to 0 where only base_pose will play and then an equal amount of time where walk will play on top of base_pose as foo goes from 0 to 1 back to 0. base_pose will have a blend value of 1.0.
"controller.animation.tiger.move": {
"states": {
"default": {
"animations": [
"base_pose",
{ "walk": "variable.foo > 0.0" }
]
}
}
}
Channels (Rotation, Position, Scale)
The engine tracks the animation of rotation, position, and scale separately. Within a channel, one or more keyframes are specified at arbitrary times, in seconds, from the start of the animation. If no keyframes are specified, a single keyframe is created at t=0.0 and all channel data is stored within that keyframe.
Channels sample
Listed below are common examples of how the Animation format is written in JSON. In the geometry format, units are in 1/16ths of meters.
This sample shows using integers for the leftarm rotation. The root bone uses a more complex Molang expression with calculations which allows a more complex and refined animation.
"animation.player.swim" : {
"animation_length" : 1.3,
"loop" : true,
"override_previous_animation" : true,
"bones" : {
"leftarm" : {
"rotation" : {
"0" : [ 0.0, 180.0, 180.0 ],
"0.7" : [ 0.0, 180.0, 287.2 ],
"1.1" : [ 90.0, 180.0, 180.0 ],
"1.3" : [ 0.0, 180.0, 180.0 ]
}
},
"rightarm" : {
"rotation" : {
"0" : [ 0.0, 180.0, -180.0 ],
"0.7" : [ 0.0, 180.0, -287.2 ],
"1.1" : [ 90.0, 180.0, -180.0 ],
"1.3" : [ 0.0, 180.0, -180.0 ]
}
},
"root" : {
"position" : [ 0.0, "(math.sin(query.target_x_rotation) * 24.0 + 3.0) * variable.swim_amount", "(math.cos(query.target_x_rotation) * 24.0 + 9.0) * variable.swim_amount" ],
"rotation" : [ "variable.swim_amount * (90 + query.target_x_rotation)", 0.0, 0.0 ]
}
}
}