Animation Graphs

Animation graphs are assets that control the transitioning and blending between different animations.

An animation graph is actually a collection of smaller graphs which are called layers. Within each layer are nodes and links that connect one node to another. At run-time, each layer has an active node which is the current state of the graph. The active node changes when the conditions on an outgoing link from the active node to another node are all true. The conditions can involve parameters which are external inputs to the animation graph from the game code.

Each node has an action associated with it, and the action determines how the final animation is computed. The most basic action is to play a single animation, but other actions exist to blend or layer multiple animations together.

Animation graphs are authored as animation_graph files which are in the SJSON format. During the build process, these files are converted to a more efficient format that's used at run-time.

File Format

The following fields can appear at the top level of the document:

parameters - an array of Parameters.

layers - an array of Layers

Parameters

name - string name of the parameter that will be used by code to set the value

type - one of number, bool, enum or trigger. enum value have one of a set of predefined values. triggers are boolean values that are automatically set to false when they are used in a condition.

values - for enum parameters, this array of strings specifies the valid values.

default_value - the initial value of the parameter.

min_value - for number parameters, this specifies the minimum value the parameter can take. The default is -infinity.

max_value - for number parameters, this specifies the maximum value the parameter can take. The default is infinity.

Layers

nodes - an array of Nodes in the layer.

links - an array of Links in the layer.

initial_node - the string id of the node which the graph will initially play.

Nodes

id - a unique string that's used to identify the Node when specifying the initial_node for a Layer or the start or end nodes of a Link. The ids only need to be unique within a Layer.

action - an Action specifying how the animation should be computed when the graph is in this node.

Actions

type - one of play, blend, layer and identity. play actions play a single animation. blend actions blends between two or more animations based on a parameter's value. layer actions plays multiple animations stacked on top of each other. identity actions produce no animation.

animation - for play actions, specifies the file name of the .animation file to play.

min - for blend actions, a number value which is used as the lower bound for blending (see the parameter field).

max - for blend actions, a number value which is used as the upper bound for blending (see the parameter field).

parameter - for blend actions, specifies the name of the parameter that's used to blend between the child actions. The value of this parameter is converted to a fraction between the min and max values and that value is used to determine which actions in the children array are blended between. For example if the children were [A, B, C], a fraction of 0.25 would blend between A and B.

children - for blend and layer actions, specifies an array of Actions.

start - the id of the node this link exits.

end - the id of the node this link enters.

conditions - an array of Conditions which must all be satisfied for the link to be crossed.

blend_time - the amount of time (in seconds) that the action of the start node will blend into the end node when the link is crossed.

Conditions

parameter - the name of one of the parameters or the predefined values playback and remaining.

operator - one of ==, !=, <, <=, >, >=. The specified operator is used in the condition as: parameter <op> value.

value - a value to compare with the parameter. If the parameter is an enum a string from the list of values can be specified. For other types of parameters, number and boolean values can be specified.