Struct AnimationGraph

Source

pub struct AnimationGraph {
    pub graph: Graph<AnimationGraphNode, ()>,
    pub root: NodeIndex,
    pub mask_groups: HashMap<AnimationTargetId, u64>,
}

Expand 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.

Fields§

§graph: Graph<AnimationGraphNode, ()>

The petgraph data structure that defines the animation graph.

§root: NodeIndex

The index of the root node in the animation graph.

§mask_groups: HashMap<AnimationTargetId, u64>

The mask groups that each animation target (bone) belongs to.

Each value in this map is a bitfield, in which 0 in bit position N indicates that the animation target doesn’t belong to mask group N, and a 1 in position N indicates that the animation target does belong to mask group N.

Animation targets not in this collection are treated as though they don’t belong to any mask groups.

Struct AnimationGraph Copy item path

Fields§

Implementations§

impl AnimationGraph

pub fn new() -> AnimationGraph

pub fn from_clip(clip: Handle<AnimationClip>) -> (AnimationGraph, NodeIndex)

pub fn from_clips<'a, I>(clips: I) -> (AnimationGraph, Vec<NodeIndex>)where I: IntoIterator<Item = Handle<AnimationClip>>, <I as IntoIterator>::IntoIter: 'a,

pub fn add_clip( &mut self, clip: Handle<AnimationClip>, weight: f32, parent: NodeIndex, ) -> NodeIndex

pub fn add_clip_with_mask( &mut self, clip: Handle<AnimationClip>, mask: u64, weight: f32, parent: NodeIndex, ) -> NodeIndex

pub fn add_clips<'a, I>( &'a mut self, clips: I, weight: f32, parent: NodeIndex, ) -> impl Iterator<Item = NodeIndex> + 'awhere I: IntoIterator<Item = Handle<AnimationClip>>, <I as IntoIterator>::IntoIter: 'a,

pub fn add_blend(&mut self, weight: f32, parent: NodeIndex) -> NodeIndex

pub fn add_blend_with_mask( &mut self, mask: u64, weight: f32, parent: NodeIndex, ) -> NodeIndex

pub fn add_additive_blend( &mut self, weight: f32, parent: NodeIndex, ) -> NodeIndex

pub fn add_additive_blend_with_mask( &mut self, mask: u64, weight: f32, parent: NodeIndex, ) -> NodeIndex

pub fn add_edge(&mut self, from: NodeIndex, to: NodeIndex)

pub fn remove_edge(&mut self, from: NodeIndex, to: NodeIndex) -> bool

pub fn get(&self, animation: NodeIndex) -> Option<&AnimationGraphNode>

pub fn get_mut( &mut self, animation: NodeIndex, ) -> Option<&mut AnimationGraphNode>

pub fn nodes(&self) -> impl Iterator<Item = NodeIndex>

pub fn save<W>(&self, writer: &mut W) -> Result<(), AnimationGraphLoadError>where W: Write,

pub fn add_target_to_mask_group( &mut self, target: AnimationTargetId, mask_group: u32, )

Trait Implementations§

impl Clone for AnimationGraph

fn clone(&self) -> AnimationGraph

fn clone_from(&mut self, source: &Self)

impl Debug for AnimationGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl Default for AnimationGraph

fn default() -> AnimationGraph

impl From<AnimationGraph> for SerializedAnimationGraph

fn from(animation_graph: AnimationGraph) -> SerializedAnimationGraph

fn from_reflect( reflect: &(dyn PartialReflect + 'static), ) -> Option<AnimationGraph>

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

fn get_type_registration() -> TypeRegistration

fn register_type_dependencies(registry: &mut TypeRegistry)

impl Index<NodeIndex> for AnimationGraph

type Output = AnimationGraphNode

fn index( &self, index: NodeIndex, ) -> &<AnimationGraph as Index<NodeIndex>>::Output

impl IndexMut<NodeIndex> for AnimationGraph

fn index_mut( &mut self, index: NodeIndex, ) -> &mut <AnimationGraph as Index<NodeIndex>>::Output

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

fn try_apply( &mut self, value: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

fn reflect_kind(&self) -> ReflectKind

fn reflect_ref(&self) -> ReflectRef<'_>

fn reflect_mut(&mut self) -> ReflectMut<'_>

fn reflect_owned(self: Box<AnimationGraph>) -> ReflectOwned

fn try_into_reflect( self: Box<AnimationGraph>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

fn into_partial_reflect(self: Box<AnimationGraph>) -> Box<dyn PartialReflect>

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

fn reflect_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

fn clone_value(&self) -> Box<dyn PartialReflect>

fn to_dynamic(&self) -> Box<dyn PartialReflect>

fn reflect_hash(&self) -> Option<u64>

fn is_dynamic(&self) -> bool

fn into_any(self: Box<AnimationGraph>) -> Box<dyn Any>

fn as_any(&self) -> &(dyn Any + 'static)

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

fn into_reflect(self: Box<AnimationGraph>) -> Box<dyn Reflect>

fn as_reflect(&self) -> &(dyn Reflect + 'static)

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

impl Serialize for AnimationGraph

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>where __S: Serializer,

fn field(&self, name: &str) -> Option<&(dyn PartialReflect + 'static)>

fn field_mut( &mut self, name: &str, ) -> Option<&mut (dyn PartialReflect + 'static)>

fn field_at(&self, index: usize) -> Option<&(dyn PartialReflect + 'static)>

fn field_at_mut( &mut self, index: usize, ) -> Option<&mut (dyn PartialReflect + 'static)>

fn name_at(&self, index: usize) -> Option<&str>

fn field_len(&self) -> usize

fn iter_fields(&self) -> FieldIter<'_>

fn to_dynamic_struct(&self) -> DynamicStruct

fn clone_dynamic(&self) -> DynamicStruct

fn get_represented_struct_info(&self) -> Option<&'static StructInfo>

impl TypePath for AnimationGraphwhere AnimationGraph: Any + Send + Sync,

Struct AnimationGraph

pub fn from_clips<'a, I>(clips: I) -> (AnimationGraph, Vec<NodeIndex>)
where I: IntoIterator<Item = Handle<AnimationClip>>, <I as IntoIterator>::IntoIter: 'a,

pub fn add_clips<'a, I>( &'a mut self, clips: I, weight: f32, parent: NodeIndex, ) -> impl Iterator<Item = NodeIndex> + 'a
where I: IntoIterator<Item = Handle<AnimationClip>>, <I as IntoIterator>::IntoIter: 'a,

pub fn save<W>(&self, writer: &mut W) -> Result<(), AnimationGraphLoadError>
where W: Write,

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

impl TypePath for AnimationGraph
where AnimationGraph: Any + Send + Sync,

impl<T> Any for T
where T: 'static + ?Sized,

impl<T, U> AsBindGroupShaderType<U> for T
where U: ShaderType, &'a T: for<'a> Into<U>,

impl<A> AssetContainer for A
where A: Asset,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T> CloneToUninit for T
where T: Clone,

impl<T> Downcast for T
where T: Any,

impl<T> DowncastSend for T
where T: Any + Send,

impl<T> DynamicTypePath for T
where T: TypePath,

impl<T> DynamicTyped for T
where T: Typed,

impl<T> FromWorld for T
where T: Default,

impl<S> GetField for S
where S: Struct,

fn get_field<T>(&self, name: &str) -> Option<&T>
where T: Reflect,