Struct Machine

pub struct Machine<T>
where
    T: EntityId,
{ /* private fields */ }

Animation blending state machine is used to blend multiple animation as well as perform automatic smooth transitions between states.

Terminology

Node - is a part of sub-graph that backs states with animations. Typical nodes are PlayAnimation, BlendAnimations, BlendAnimationsByIndex, etc. Nodes can be connected forming a tree, some node could be marked as output - its animation will be used in parent state. State - is a final source of animation for blending. There could be any number of states, for example typical states are: run, idle, jump etc. A state could be marked as entry state - it will be active at the first frame when using the machine. There is always one state active. Transition - is a connection between states that has transition time, a link to a parameter that defines whether the transition should be performed or not. Transition is directional; there could be any number of transitions between any number of states (loops are allowed). Parameter - is a named variable of a fixed type (see Parameters section for more info). Layer - is a separate state graph, there could be any number of layers - each with its own mask. Mask - a set of handles to nodes which will be excluded from animation on a layer. Pose - a final result of blending multiple animation into one.

Summarizing everything of this, we can describe animation blending state machine as a state graph, where each state has its own sub-graph (tree) that provides animation for blending. States can be connected via transitions.

Parameters

Parameter is a named variable of a fixed type. Parameters are used as a data source in various places in the animation blending state machines. There are three main types of parameters:

Rule - boolean value that used as a trigger for transitions. When transition is using some rule, it checks the value of the parameter and if it is true transition starts. Weight - real number (f32) that is used a weight when you blending multiple animations into one. Index - natural number (i32) that is used as an animation selector.

Each parameter has a name, it could be pretty much any string.

Layers

Layer is a separate state graph. Layers mainly used to animate different parts of humanoid (but not only) characters. For example there could a layer for upper body and a layer for lower body. Upper body layer could contain animations for aiming, melee attacks while lower body layer could contain animations for standing, running, crouching, etc. This gives you an ability to have running character that could aim or melee attack, or crouching and aiming, and so on with any combination. Both layers use the same set of parameters, so a change in a parameter will affect all layers that use it.

Examples

Let have a quick look at simple state machine graph with a single layer:

                                                 +-------------+
                                                 |  Idle Anim  |
                                                 +------+------+
                                                        |
          Walk Weight                                   |
+-----------+      +-------+           Walk->Idle Rule  |
| Walk Anim +------+       |                            |
+-----------+      |       |      +-------+         +---+---+
                   | Blend |      |       +-------->+       |
                   |       +------+ Walk  |         |  Idle |
+-----------+      |       |      |       +<--------+       |
| Aim Anim  +------+       |      +--+----+         +---+---+
+-----------+      +-------+         |                  ^
          Aim Weight                 | Idle->Walk Rule  |
                                     |                  |
                      Walk->Run Rule |    +---------+   | Run->Idle Rule
                                     |    |         |   |
                                     +--->+   Run   +---+
                                          |         |
                                          +----+----+
                                               |
                                               |
                                        +------+------+
                                        |  Run Anim   |
                                        +-------------+

Here we have Walk, Idle, Run states which uses different sources of poses:

• Run and Idle both directly uses respective animations as a pose source.
• Walk - is the most complex here - it uses result of blending between Aim and Walk animations with different weights. This is useful if your character can only walk or can walk and aim at the same time. Desired pose determined by Walk Weight and Aim Weight parameters combination (see Parameters section for more info). Note: Such blending is almost never used on practice, instead you should use multiple animation layers. This serves only as an example that the machine can blend animations.

There are four transitions between three states each with its own rule. Rule is just Rule parameter which can have boolean value that indicates that transition should be activated. The machine on the image above can be created using code like so:

use fyrox_animation::{
    machine::{
        Machine, State, Transition, PoseNode,
        Parameter, PlayAnimation, PoseWeight, BlendAnimations, BlendPose
    },
    core::pool::Handle
};
use fyrox_core::pool::ErasedHandle;

// Assume that these are correct handles.
let idle_animation = Handle::default();
let walk_animation = Handle::default();
let aim_animation = Handle::default();

let mut machine = Machine::<ErasedHandle>::new();

let root_layer = &mut machine.layers_mut()[0];

let aim = root_layer.add_node(PoseNode::PlayAnimation(PlayAnimation::new(aim_animation)));
let walk = root_layer.add_node(PoseNode::PlayAnimation(PlayAnimation::new(walk_animation)));

// Blend two animations together
let blend_aim_walk = root_layer.add_node(PoseNode::BlendAnimations(
    BlendAnimations::new(vec![
        BlendPose::new(PoseWeight::Constant(0.75), aim),
        BlendPose::new(PoseWeight::Constant(0.25), walk)
    ])
));

let walk_state = root_layer.add_state(State::new("Walk", blend_aim_walk));

let idle = root_layer.add_node(PoseNode::PlayAnimation(PlayAnimation::new(idle_animation)));
let idle_state = root_layer.add_state(State::new("Idle", idle));

root_layer.add_transition(Transition::new("Walk->Idle", walk_state, idle_state, 1.0, "WalkToIdle"));
root_layer.add_transition(Transition::new("Idle->Walk", idle_state, walk_state, 1.0, "IdleToWalk"));

This creates a machine with a single animation layer, fills it with some states that are backed by animation sources (either simple animation playback or animation blending). You can use multiple layers to animate a single model - for example one layer could be used for upper body of a character and other is lower body. This means that locomotion machine will take control over lower body and combat machine will control upper body.

Complex state machines quite hard to create from code, you should use ABSM editor instead whenever possible.

Implementations

impl<T> Machine<T>

where T: EntityId,

pub const PARAMETERS: &'static str = "parameters"

pub const LAYERS: &'static str = "layers"

impl<T> Machine<T>

where T: EntityId,

pub fn new() -> Machine<T>

Creates a new animation blending state machine with a single animation layer.

pub fn set_parameter( &mut self, id: &str, new_value: Parameter, ) -> &mut Machine<T>

Sets a value for existing parameter with given id or registers new parameter with given id and provided value. The method returns a reference to the machine, so the calls could be chained:

use fyrox_animation::machine::{Machine, Parameter};
use fyrox_core::pool::ErasedHandle;

let mut machine = Machine::<ErasedHandle>::new();

machine
    .set_parameter("Run", Parameter::Rule(true))
    .set_parameter("Jump", Parameter::Rule(false));

pub fn parameters(&self) -> &ParameterContainer

Returns a shared reference to the container with all parameters used by the animation blending state machine.

pub fn parameters_mut(&mut self) -> &mut ParameterContainer

Returns a mutable reference to the container with all parameters used by the animation blending state machine.

pub fn add_layer(&mut self, layer: MachineLayer<T>)

Adds a new layer to the animation blending state machine.

pub fn remove_layer(&mut self, index: usize) -> MachineLayer<T>

Removes a layer at given index. Panics if index is out-of-bounds.

pub fn insert_layer(&mut self, index: usize, layer: MachineLayer<T>)

Inserts a layer at given position, panics in index is out-of-bounds.

pub fn pop_layer(&mut self) -> Option<MachineLayer<T>>

Removes last layer from the list.

pub fn layers(&self) -> &[MachineLayer<T>]

Returns a shared reference to the list of layers.

pub fn layers_mut(&mut self) -> &mut [MachineLayer<T>]

Returns a mutable reference to the list of layers.

pub fn find_layer_by_name_ref<S>( &self, name: S, ) -> Option<(usize, &MachineLayer<T>)>

where S: AsRef<str>,

Tries to find a layer by its name. Returns index of the layer and its reference.

pub fn find_by_name_mut<S>( &mut self, name: S, ) -> Option<(usize, &mut MachineLayer<T>)>

where S: AsRef<str>,

Tries to find a layer by its name. Returns index of the layer and its reference.

pub fn pose(&self) -> &AnimationPose<T>

Returns final pose of the machine.

pub fn evaluate_pose( &mut self, animations: &mut AnimationContainer<T>, dt: f32, ) -> &AnimationPose<T>

Computes final animation pose that could be then applied to a set of entities graph. This method will update all the animations used by the machine automatically. Make sure to not update the animations in the container before using this method. Otherwise your animations will be updated more than once, and they’ll play at higher speed and performance will also be decreased.

Trait Implementations

impl<T> Clone for Machine<T>

where T: Clone + EntityId,

fn clone(&self) -> Machine<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Machine<T>

where T: Debug + EntityId,

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

Formats the value using the given formatter.

impl<T> Default for Machine<T>

where T: Default + EntityId,

fn default() -> Machine<T>

Returns the “default value” for a type.

impl<T> PartialEq for Machine<T>

where T: PartialEq + EntityId,

fn eq(&self, other: &Machine<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Reflect for Machine<T>

where T: EntityId, Machine<T>: 'static, ParameterContainer: Reflect, Vec<MachineLayer<T>>: Reflect,

fn source_path() -> &'static str

fn type_name(&self) -> &'static str

fn doc(&self) -> &'static str

fn assembly_name(&self) -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn type_assembly_name() -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn fields_info(&self, func: &mut dyn FnMut(&[FieldInfo<'_, '_>]))

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

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

fn as_any(&self, func: &mut dyn FnMut(&(dyn Any + 'static)))

fn as_any_mut(&mut self, func: &mut dyn FnMut(&mut (dyn Any + 'static)))

fn as_reflect(&self, func: &mut dyn FnMut(&(dyn Reflect + 'static)))

fn as_reflect_mut(&mut self, func: &mut dyn FnMut(&mut (dyn Reflect + 'static)))

fn fields(&self, func: &mut dyn FnMut(&[&(dyn Reflect + 'static)]))

fn fields_mut( &mut self, func: &mut dyn FnMut(&mut [&mut (dyn Reflect + 'static)]), )

fn field( &self, name: &str, func: &mut dyn FnMut(Option<&(dyn Reflect + 'static)>), )

fn field_mut( &mut self, name: &str, func: &mut dyn FnMut(Option<&mut (dyn Reflect + 'static)>), )

fn set_field( &mut self, field: &str, value: Box<dyn Reflect>, func: &mut dyn FnMut(Result<Box<dyn Reflect>, Box<dyn Reflect>>), )

Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

fn as_array(&self, func: &mut dyn FnMut(Option<&(dyn ReflectArray + 'static)>))

fn as_array_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectArray + 'static)>), )

fn as_list(&self, func: &mut dyn FnMut(Option<&(dyn ReflectList + 'static)>))

fn as_list_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectList + 'static)>), )

fn as_inheritable_variable( &self, func: &mut dyn FnMut(Option<&(dyn ReflectInheritableVariable + 'static)>), )

fn as_inheritable_variable_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectInheritableVariable + 'static)>), )

fn as_hash_map( &self, func: &mut dyn FnMut(Option<&(dyn ReflectHashMap + 'static)>), )

fn as_hash_map_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectHashMap + 'static)>), )

impl<T> Visit for Machine<T>

where T: EntityId, ParameterContainer: Visit, Vec<MachineLayer<T>>: Visit,

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> Result<(), VisitError>

Read or write this value, depending on whether Visitor::is_reading() is true or false.

impl<T> StructuralPartialEq for Machine<T>

where T: EntityId,