Struct Animation

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

Overview

Animation allows you to change properties of arbitrary entities at runtime using a set of key frames. Animation consists of multiple tracks, where each track is bound to a property of an entity. A track can animate any numeric properties, starting from numbers (including bool) end ending by 2/3/4 dimensional vectors. Each component (number, x/y/z/w vector components) is stored in a parametric curve (see crate::core::math::curve::Curve docs for more info). Every parametric curve contains zero or more key frames. Graphically this could be represented like so:

                                         Timeline
                                            v
  Time   > |---------------|------------------------------------>
           |               |
  Track1 > | node.position |
           |   X curve     |..1..........5...........10..........
           |   Y curve     |..2.........-2..................1....  < Curve key frames
           |   Z curve     |..1..........9......................4
           |_______________|
  Track2   | node.property |
           | ............  |.....................................
           | ............  |.....................................
           | ............  |.....................................

Each key frame is just a real number with interpolation mode. Interpolation mode tells the engine how to calculate intermediate values between key frames. There are three kinds of interpolation used in animations (you can skip “boring math” if you want):

• Constant - intermediate value will be calculated using leftmost value of two. Constant “interpolation” is usually used to create step-like behaviour, the most common case is to “interpolate” two boolean values.
• Linear - intermediate value will be calculated using linear interpolation i = left + (right - left) / t, where t = (time_position - left) / (right - left). t is always in 0..1 range. Linear interpolation is usually used to create “straight” transitions between two values.
• Cubic - intermediate value will be calculated using Hermite cubic spline: i = (2t^3 - 3t^2 + 1) * left + (t^3 - 2t^2 + t) * left_tangent + (-2t^3 + 3t^2) * right + (t^3 - t^2) * right_tangent, where t = (time_position - left) / (right - left) (t is always in 0..1 range), left_tangent and right_tangent is usually a tan(angle). Cubic interpolation is usually used to create “smooth” transitions between two values.

Track binding

Each track is always bound to a property in a node, either by its name or by a special binding. The name is used to fetch the property using reflection, the special binding is a faster way of fetching built-in properties. It is usually used to animate position, scale and rotation (these are the most common properties available in every scene node).

Time slice and looping

While key frames on the curves can be located at arbitrary position in time, animations usually plays a specific time slice. By default, each animation will play on a given time slice infinitely - it is called animation looping, it works in both playback directions.

Speed

You can vary playback speed in wide range, by default every animation has playback speed multiplier set to 1.0. The multiplier tells how faster (>1) or slower (<1) the animation needs to be played. Negative speed multiplier values will reverse playback.

Enabling or disabling animations

Sometimes there’s a need to disable/enable an animation or check if it is enabled or not, you can do this by using the pair of respective methods - Animation::set_enabled and Animation::is_enabled.

Signals

Signal is a named marker on specific time position on the animation timeline. Signal will emit an event if the animation playback time passes signal’s position from left-to-right (or vice versa depending on playback direction). Signals are usually used to attach some specific actions to a position in time. For example, you can have a walking animation and you want to emit sounds when character’s feet touch ground. In this case you need to add a few signals at times when each foot touches the ground. After that all you need to do is to fetch animation events one-by-one and emit respective sounds. See AnimationSignal docs for more info and examples.

Examples

Usually, animations are created from the editor or some external tool and then imported in the engine. However, sometimes there’s a need for procedural animations. Use the following example code as a guide only if you need to create procedural animations:

fn create_animation(target: ErasedHandle) -> Animation<ErasedHandle> {
    let mut frames_container = TrackDataContainer::new(TrackValueKind::Vector3);

    // We'll animate only X coordinate (at index 0).
    frames_container.curves_mut()[0] = Curve::from(vec![
        CurveKey::new(0.5, 2.0, CurveKeyKind::Linear),
        CurveKey::new(0.75, 1.0, CurveKeyKind::Linear),
        CurveKey::new(1.0, 3.0, CurveKeyKind::Linear),
    ]);

    // Create a track that will animate the node using the curve above.
    let mut track = Track::new(frames_container, ValueBinding::Position);

    // Finally create an animation and set its time slice and turn it on.
    let mut animation = Animation::default();
    animation.add_track_with_binding(TrackBinding::new(target), track);
    animation.set_time_slice(0.0..1.0);
    animation.set_enabled(true);

    animation
}

// Create the animation.
let mut animation = create_animation(Default::default());

// Emulate some ticks (like it was updated from the main loop of your game).
for _ in 0..10 {
    animation.tick(1.0 / 60.0);
}

The code above creates a simple animation that moves a node along X axis in various ways. The usage of the animation is only for the sake of completeness of the example. In the real games you need to add the animation to an animation player scene node and it will do the job for you.

Implementations

impl<T> Animation<T>

where T: EntityId,

pub const NAME: &'static str = "name"

pub const TRACKS_DATA: &'static str = "tracks_data"

pub const TRACK_BINDINGS: &'static str = "track_bindings"

pub const TIME_POSITION: &'static str = "time_position"

pub const TIME_SLICE: &'static str = "time_slice"

pub const SPEED: &'static str = "speed"

pub const LOOPED: &'static str = "looped"

pub const ENABLED: &'static str = "enabled"

pub const SIGNALS: &'static str = "signals"

pub const ROOT_MOTION_SETTINGS: &'static str = "root_motion_settings"

pub const MAX_EVENT_CAPACITY: &'static str = "max_event_capacity"

impl<T> Animation<T>

where T: EntityId,

pub fn get_max_event_capacity(&self) -> usize

Gets the maximum capacity of events.

pub fn set_max_event_capacity(&mut self, max_event_capacity: usize)

Sets the maximum capacity of events.

pub fn set_name<S>(&mut self, name: S)

where S: AsRef<str>,

Sets a new name for the animation. The name then could be used to find the animation in a container.

pub fn name(&self) -> &str

Returns current name of the animation.

pub fn set_tracks_data(&mut self, resource: Resource<AnimationTracksData>)

Sets a new source of data for animation tracks. Keep in mind, that all existing track bindings stored in the animation could become invalid, if the new resource does not have tracks with the same ids that the bindings has.

pub fn tracks_data(&self) -> &Resource<AnimationTracksData>

Returns a reference to the current animation tracks resource.

pub fn fit_length_to_content(&mut self)

Calculates new length of the animation based on the content of its tracks. It looks for the most “right” curve key in all curves of all tracks and treats it as length of the animation. The method could be used in case if you formed animation from code using just curves and don’t know the actual length of the animation.

pub fn set_time_position(&mut self, time: f32) -> &mut Animation<T>

Sets new time position of the animation. The actual time position the animation will have after the call, can be different in two reasons:

• If the animation is looping and the new time position is outside of the time slice of the animation, then the actual time position will be wrapped to fit the time slice. For example, if you have an animation that has 0.0..5.0s time slice and you trying to set 7.5s position, the actual time position will be 2.5s (it wraps the input value on the given time slice).
• If the animation is not looping and the new time position is outside of the time slice of the animation, then the actual time position will be clamped to the time clice of the animation.

pub fn set_time_slice(&mut self, time_slice: Range<f32>)

Sets new time slice of the animation in seconds. It defines a time interval in which the animation will be played. Current playback position will be clamped (or wrapped if the animation is looping) to fit to new bounds.

pub fn time_slice(&self) -> Range<f32>

Returns current time slice of the animation.

pub fn rewind(&mut self) -> &mut Animation<T>

Rewinds the animation to the beginning.

pub fn length(&self) -> f32

Returns length of the animation in seconds.

pub fn tick(&mut self, dt: f32)

Performs a single update tick and calculates an output pose. This method is low level, you should not use it in normal circumstances - the engine will call it for you.

pub fn set_root_motion_settings( &mut self, settings: Option<RootMotionSettings<T>>, )

Sets new root motion settings.

pub fn root_motion_settings_ref(&self) -> Option<&RootMotionSettings<T>>

Returns a reference to the root motion settings (if any).

pub fn root_motion_settings_mut(&mut self) -> Option<&mut RootMotionSettings<T>>

Returns a reference to the root motion settings (if any).

pub fn root_motion(&self) -> Option<&RootMotion>

Returns a reference to the root motion (if any).

pub fn pop_event(&mut self) -> Option<AnimationEvent>

Extracts a first event from the events queue of the animation.

pub fn events_ref(&self) -> &VecDeque<AnimationEvent>

Returns a reference to inner events queue. It is useful when you need to iterate over the events, but don’t extract them from the queue.

pub fn events_mut(&mut self) -> &mut VecDeque<AnimationEvent>

Return a mutable reference to inner events queue. Provides you a full controls over animation events, you can even manually inject events in the queue.

pub fn take_events(&mut self) -> VecDeque<AnimationEvent>

Takes the events queue and returns it to the caller, leaving the internal queue empty.

pub fn time_position(&self) -> f32

Returns current time position of the animation. The time position is guaranteed to be in the range of current time slice of the animation.

pub fn set_speed(&mut self, speed: f32) -> &mut Animation<T>

Sets new speed multiplier for the animation. By default it is set to 1.0. Negative values can be used to play the animation in reverse.

pub fn speed(&self) -> f32

Returns speed multiplier of the animation.

pub fn set_loop(&mut self, state: bool) -> &mut Animation<T>

Enables or disables looping of the animation.

pub fn is_loop(&self) -> bool

Returns true if the animation is looping, false - otherwise.

pub fn has_ended(&self) -> bool

Returns true if the animation was played until the end of current time slice of the animation, false - otherwise. Looping animations will always return false.

pub fn set_enabled(&mut self, enabled: bool) -> &mut Animation<T>

Enables or disables the animation, disabled animations does not updated and their output pose will remain the same. By default every animation is enabled.

pub fn is_enabled(&self) -> bool

Returns true if the animation is enabled, false - otherwise.

pub fn add_track_with_binding(&mut self, binding: TrackBinding<T>, track: Track)

Adds a new track to the animation track data container and binds it with the specified target. Keep in mind, that this method will modify potentially shared track data container, which might affect other animations using it.

pub fn pop_track_with_binding(&mut self) -> Option<(TrackBinding<T>, Track)>

Removes last track from the current tracks data resource and the respective binding to it from the animation. This method will fail if the resource is not loaded, or if there’s no tracks in it. It will also fail if there’s no respective binding to the track in the animation.

Keep in mind, that this method modifies the tracks data resource, which might be used by some other animation.

pub fn remove_track_with_binding( &mut self, index: usize, ) -> Option<(TrackBinding<T>, Track)>

Removes the specified track from the current tracks data resource and the respective binding to it from the animation. This method will fail if the resource is not loaded, or if there’s no tracks in it. It will also fail if there’s no respective binding to the track in the animation.

Keep in mind, that this method modifies the tracks data resource, which might be used by some other animation.

pub fn insert_track_with_binding( &mut self, index: usize, binding: TrackBinding<T>, track: Track, )

Inserts a new track in the tracks data resource and creates a new binding to it.

Keep in mind, that this method modifies the tracks data resource, which might be used by some other animation.

pub fn add_signal(&mut self, signal: AnimationSignal) -> &mut Animation<T>

Adds a new animation signal to the animation. See AnimationSignal docs for more info and examples.

pub fn pop_signal(&mut self) -> Option<AnimationSignal>

Removes last animation signal from the container of the animation.

pub fn insert_signal(&mut self, index: usize, signal: AnimationSignal)

Inserts a new animation signal at given position.

pub fn remove_signal(&mut self, index: usize) -> AnimationSignal

Removes an animation signal at given index.

pub fn signals(&self) -> &[AnimationSignal]

Returns a reference to the animation signals container.

pub fn signals_mut(&mut self) -> &mut [AnimationSignal]

Returns a mutable reference to the inner animation signals container, allowing you to modify the signals.

pub fn set_node_track_enabled(&mut self, handle: T, enabled: bool)

Tries to find all tracks that refer to a given node and enables or disables them.

pub fn track_bindings( &self, ) -> &HashMap<Uuid, TrackBinding<T>, BuildHasherDefault<FxHasher>>

Returns a reference to the current set of track bindings used by the animation. The returned hash map contains (track_id -> binding) pairs.

pub fn track_bindings_mut( &mut self, ) -> &mut HashMap<Uuid, TrackBinding<T>, BuildHasherDefault<FxHasher>>

Returns a reference to the current set of track bindings used by the animation. The returned hash map contains (track_id -> binding) pairs.

pub fn find_signal_by_name_ref<S>( &self, name: S, ) -> Option<(usize, &AnimationSignal)>

where S: AsRef<str>,

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

pub fn find_signal_by_name_mut<S>( &mut self, name: S, ) -> Option<(usize, &mut AnimationSignal)>

where S: AsRef<str>,

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

pub fn has_signal<S>(&self, name: S, id: Uuid) -> bool

where S: AsRef<str>,

Returns true if there’s a signal with given name and id.

pub fn remove_tracks(&mut self)

Removes all tracks from the animation.

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

Returns current pose of the animation (a final result that can be applied to a scene graph).

Trait Implementations

impl<T> Clone for Animation<T>

where T: EntityId,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Animation<T>

where T: Debug + EntityId,

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

Formats the value using the given formatter.

impl<T> Default for Animation<T>

where T: EntityId,

fn default() -> Animation<T>

Returns the “default value” for a type.

impl<T> NameProvider for Animation<T>

where T: EntityId,

fn name(&self) -> &str

Returns a reference to the name of the entity.

impl<T> PartialEq for Animation<T>

where T: PartialEq + EntityId,

fn eq(&self, other: &Animation<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 Animation<T>

where T: EntityId, Animation<T>: 'static, ImmutableString: Reflect, Resource<AnimationTracksData>: Reflect, HashMap<Uuid, TrackBinding<T>, BuildHasherDefault<FxHasher>>: Reflect, f32: Reflect, Range<f32>: Reflect, bool: Reflect, Vec<AnimationSignal>: Reflect, Option<RootMotionSettings<T>>: Reflect, usize: 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<Animation<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> TypeUuidProvider for Animation<T>

where T: EntityId,

fn type_uuid() -> Uuid

Return type UUID.

impl<T> Visit for Animation<T>

where T: EntityId,

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 Animation<T>

where T: EntityId,