Struct Tween 

pub struct Tween { /* private fields */ }

Single tweening animation description.

A tween is the basic building block of an animation. It describes a single tweening animation between two values, accessed through a given Lens. The animation is composed of one or more cycles, and can be played forward or backward. On completion, you can be notified via events, observers, or the execution of a one-shot system.

If you’re looking for the runtime representation of a tweenable animation, see TweenAnim instead.

Cycles

A tween can be configured to repeat multiple, or even an infinity, of times. Each repeat iteration is called a cycle. The duration of a single cycle is the cycle duration, and the duration of the entire tween animation including all cycles is the total duration.

An example tween with 5 cycles.

The number of cycles is configured through the RepeatCount.

• RepeatCount::Finite directly sets a number of cycles. The total duration is inferred from the cycle duration and number of cycles.
• RepeatCount::For selects a total duration for the animation, from which a number of cycles is derived. In that case, the number of cycles may be a fractional number; the last cycle is only partial, and may not reach the endpoint of the lens.
• RepeatCount::Infinite enables infinitely-repeating cycles. In that case the total duration of the animation is infinite, and the animation itself is said to be infinite.

The repeat strategy determines whether cycles are mirrored when they repeat. By default, all cycles produce a linear ratio monotonically increasing from 0 to 1. When mirrored, every other cycle instead produces a decreasing ratio from 1 to 0. The repeat strategy is configured with RepeatStrategy.

A tween with 5 cycles, using the mirrored repeat strategy.

Once the ratio in [0:1] has been calculated, it’s passed through the easing function to obtain the final interpolation factor that Lens::lerp() receives.

Elapsed time and playback direction

The elapsed time of an animation represents the current time since the start of the animation. This includes all cycles, and is bound by the total duration of the animation. This is a property of an active animation, and is available per instance from the TweenAnim representing the instance. So a tween itself, which describes an animation without a specific target to animate, doesn’t have an elapsed time. You can think of the elapsed time as the current time position on some animation timeline.

The tween however has a playback direction. By default, the playback direction is PlaybackDirection::Forward, and the animation plays forward as described above. By instead using PlaybackDirection::Backward, the tween plays in reverse from end to start. Practically, this means that the elapsed time decreases from its current value back to zero, and the animation completes at t=0. You can think of the playback direction as the direction in which the time position moves on some animation timeline. Note that as a result, because infinite animations (RepeatCount::Infinite) don’t have an end time, they cannot be rewinded when the playback direction is backward.

Completion events and one-shot systems

Sometimes, you want to be notified of the completion of an animation cycle, or the completion of the entire animation itself. To that end, the Tween supports several mechanisms:

• Each time a single cycle is completed, the tween can emit a CycleCompletedEvent. The event is emitted as a buffered event, to be read by another system through an EventReader. For component targets, observers are also triggered. Both of these are enabled through with_cycle_completed_event() and set_cycle_completed_event(). Per-cycle events are disabled by default.
• At the end of all cycles, when the animation itself completes, the tween emits an AnimCompletedEvent. This event is always emitted.

Implementations

impl Tween

pub fn new<T, L>( ease_method: impl Into<EaseMethod>, cycle_duration: Duration, lens: L, ) -> Self

where T: 'static, L: Lens<T> + Send + Sync + 'static,

Create a new tween animation.

The new animation is described by a given cycle duration, a repeat count which determines its total duration, as well as an easing function and a lens describing how the cycles affect the animation target. The target type is implicitly determined by the type T of the Lens<T> argument.

Example

let tween = Tween::new(
    EaseFunction::QuadraticInOut,
    Duration::from_secs(1),
    TransformPositionLens {
        start: Vec3::ZERO,
        end: Vec3::new(3.5, 0., 0.),
    },
);

pub fn with_repeat_count(self, count: impl Into<RepeatCount>) -> Self

Set the number of times to repeat the animation.

The repeat count determines the number of cycles of the animation. See the top-level Tween documentation for details.

pub fn set_repeat_count(&mut self, count: impl Into<RepeatCount>)

Set the number of times to repeat the animation.

The repeat count determines the number of cycles of the animation. See the top-level Tween documentation for details.

pub fn with_repeat_strategy(self, strategy: RepeatStrategy) -> Self

Configure how the cycles repeat.

This enables or disables cycle mirroring. See the top-level Tween documentation for details.

pub fn set_repeat_strategy(&mut self, strategy: RepeatStrategy)

Configure how the cycles repeat.

This enables or disables cycle mirroring. See the top-level Tween documentation for details.

pub fn with_repeat( self, count: impl Into<RepeatCount>, strategy: RepeatStrategy, ) -> Self

Configure the animation repeat parameters.

The repeat count determines the number of cycles of the animation. The repeat strategy enables or disables cycle mirrored repeat. See the top-level Tween documentation for details.

pub fn set_repeat( &mut self, count: impl Into<RepeatCount>, strategy: RepeatStrategy, )

Configure the animation repeat parameters.

The repeat count determines the number of cycles of the animation. The repeat strategy enables or disables cycle mirrored repeat. See the top-level Tween documentation for details.

pub fn with_cycle_completed_event(self, send: bool) -> Self

Enable raising a event on cycle completion.

If enabled, the tween will raise a CycleCompletedEvent each time the tween completes a cycle (reaches or passes its cycle duration). In case of repeating tweens (repeat count > 1), the event is raised once per cycle. For mirrored repeats, a cycle is one travel from start to end or end to start, so the full loop start -> end -> start counts as 2 cycles and raises 2 events.

Example

let tween = Tween::new(
    // [...]
)
// Raise a CycleCompletedEvent each cycle
.with_cycle_completed_event(true);

fn my_system(mut reader: EventReader<CycleCompletedEvent>) {
    for ev in reader.read() {
        println!(
            "Tween animation {:?} raised CycleCompletedEvent for target {:?}!",
            ev.anim_entity, ev.target
        );
    }
}

pub fn set_cycle_completed_event(&mut self, send: bool)

Set whether the tween emits CycleCompletedEvent.

See with_cycle_completed_event() for details.

pub fn set_playback_direction(&mut self, direction: PlaybackDirection)

Set the playback direction of the tween.

The playback direction controls whether the internal animation clock, and therefore also the elapsed time, both move forward or backward.

Changing the direction doesn’t change any target state, nor the elapsed time of the tween. Only the direction of playback from this moment potentially changes.

pub fn with_playback_direction(self, direction: PlaybackDirection) -> Self

Set the playback direction of the tween.

See set_playback_direction() for details.

pub fn playback_direction(&self) -> PlaybackDirection

The current animation playback direction.

This is the value set by the user with with_playback_direction() and set_playback_direction(). This is never changed by the animation playback itself.

See PlaybackDirection for details.

pub fn then(self, tween: impl Tweenable + 'static) -> Sequence

Chain another Tweenable after this tween, making a Sequence with the two.

Example

let tween1 = Tween::new(
    EaseFunction::QuadraticInOut,
    Duration::from_secs(1),
    TransformPositionLens {
        start: Vec3::ZERO,
        end: Vec3::new(3.5, 0., 0.),
    },
);
let tween2 = Tween::new(
    EaseFunction::QuadraticInOut,
    Duration::from_secs(1),
    TransformRotationLens {
        start: Quat::IDENTITY,
        end: Quat::from_rotation_x(90.0_f32.to_radians()),
    },
);
let seq = tween1.then(tween2);

pub fn cycle_index(&self) -> u32

Get the elapsed cycle index (numbered from 0), accounting for finite endpoint.

If the elapsed time is equal to the total (finite) duration of the tween, then the cycle index is capped at the total number of cycles minus 1 (the tween doesn’t loop when reaching the end of its last cycle). This means that for a tween with N cycles, the index is always in 0..N, and therefore always index < N.

pub fn cycle_fraction(&self) -> f32

Get the elapsed cycle fraction, accounting for finite endpoint.

The elapsed cycle fraction is the fraction alonside one cycle where the tween currently is. This ignores any mirroring. If the elapsed time is equal to the total (finite) duration of the tween, then the cycle fraction is capped at 1.0 (the tween doesn’t loop when reaching the end of its last cycle).

The returned value is always in [0:1] for finite tweens, with the value 1.0 returned only when the last cycle is completed, and in [0:1) for infinite tweens as they never complete.

pub fn is_cycle_mirrored(&self) -> bool

Check if the current cycle is a mirrored cycle.

When the repeat strategy is RepeatStrategy::MirroredRepeat, every odd cycle index (numbered from 0) is mirrored when applying the tween’s lens. For any other strategy or single-cycle tween, this is always false.

Trait Implementations

impl From<Tween> for BoxedTweenable

fn from(t: Tween) -> Self

Converts to this type from the input type.

impl Tweenable for Tween

fn cycle_duration(&self) -> Duration

Get the duration of a single cycle of the animation.

fn total_duration(&self) -> TotalDuration

Get the total duration of the entire animation, including repeating.

fn set_elapsed(&mut self, elapsed: Duration)

Set the current animation playback elapsed time.

fn elapsed(&self) -> Duration

Get the current elapsed duration.

fn step( &mut self, _tween_id: Entity, delta: Duration, target: MutUntyped<'_>, target_type_id: &TypeId, notify_cycle_completed: &mut dyn FnMut(), ) -> (TweenState, bool)

Step the tweenable.

fn rewind(&mut self)

Rewind the animation to its starting state.

fn target_type_id(&self) -> Option<TypeId>

Get the TypeId this tweenable targets.

fn cycles_completed(&self) -> u32

Get the number of cycles completed.

fn cycle_fraction(&self) -> f32

Get the completion fraction in [0:1] of the current cycle.