AnimationGraph

AnimationGraph

  • graph : petgraph::graph::DiGraph<bevy_animation::graph::AnimationGraphNode, (), u32>
  • root : petgraph::graph::NodeIndex
  • mask_groups : bevy_utils::hashbrown::HashMap<bevy_animation::AnimationTargetId, u64, bevy_utils::hashbrown::hash_map::DefaultHashBuilder>

Description

A graph structure that describes how animation clips are to be blended together.

Applications frequently want to be able to play multiple animations at once and to fine-tune the influence that animations have on a skinned mesh. Bevy uses an animation graph to store this information. Animation graphs are a directed acyclic graph (DAG) that describes how animations are to be weighted and combined together. Every frame, Bevy evaluates the graph from the root and blends the animations together in a bottom-up fashion to produce the final pose.

There are three types of nodes: blend nodes, add nodes, and clip nodes, all of which can have an associated weight. Blend nodes and add nodes have no associated animation clip and combine the animations of their children according to those children's weights. Clip nodes specify an animation clip to play. When a graph is created, it starts with only a single blend node, the root node.

For example, consider the following graph:

┌────────────┐                                      
│            │                                      
│    Idle    ├─────────────────────┐                
│            │                     │                
└────────────┘                     │                
                                   │                
┌────────────┐                     │  ┌────────────┐
│            │                     │  │            │
│    Run     ├──┐                  ├──┤    Root    │
│            │  │  ┌────────────┐  │  │            │
└────────────┘  │  │   Blend    │  │  └────────────┘
                ├──┤            ├──┘                
┌────────────┐  │  │    0.5     │                   
│            │  │  └────────────┘                   
│    Walk    ├──┘                                   
│            │                                      
└────────────┘

In this case, assuming that Idle, Run, and Walk are all playing with weight 1.0, the Run and Walk animations will be equally blended together, then their weights will be halved and finally blended with the Idle animation. Thus the weight of Run and Walk are effectively half of the weight of Idle.

Nodes can optionally have a mask, a bitfield that restricts the set of animation targets that the node and its descendants affect. Each bit in the mask corresponds to a mask group, which is a set of animation targets (bones). An animation target can belong to any number of mask groups within the context of an animation graph.

When the appropriate bit is set in a node's mask, neither the node nor its descendants will animate any animation targets belonging to that mask group. That is, setting a mask bit to 1 disables the animation targets in that group. If an animation target belongs to multiple mask groups, masking any one of the mask groups that it belongs to will mask that animation target. (Thus an animation target will only be animated if all of its mask groups are unmasked.)

A common use of masks is to allow characters to hold objects. For this, the typical workflow is to assign each character's hand to a mask group. Then, when the character picks up an object, the application masks out the hand that the object is held in for the character's animation set, then positions the hand's digits as necessary to grasp the object. The character's animations will continue to play but will not affect the hand, which will continue to be depicted as holding the object.

Animation graphs are assets and can be serialized to and loaded from RON files. Canonically, such files have an .animgraph.ron extension.

The animation graph implements RFC 51. See that document for more information.

Functions