Crate bevy_transform_interpolation

bevy_transform_interpolation

A drop-in Transform interpolation solution for fixed timesteps for the Bevy game engine.

Features

• Automatically smooth out movement in FixedPreUpdate, FixedUpdate, and FixedPostUpdate.
• Support for both Transform interpolation and extrapolation.
• Granularly ease individual Transform properties to reduce unnecessary computation.
• Apply easing to specific entities or to all entities.
• Works out of the box with physics engines using fixed timesteps.
• Optional Hermite interpolation to produce more natural and accurate movement that considers velocity.
• Extensible with custom easing backends.

Getting Started

First, add bevy_transform_interpolation as a dependency in your Cargo.toml:

[dependencies]
bevy_transform_interpolation = "0.1"

To enable Transform interpolation, add the TransformInterpolationPlugin to your app:

use bevy::prelude::*;
use bevy_transform_interpolation::prelude::*;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, TransformInterpolationPlugin::default()))
        // ...other plugins, resources, and systems
        .run();
}

By default, interpolation is only performed for entities with the TransformInterpolation component:

fn setup(mut commands: Commands) {
    // Interpolate the entire transform: translation, rotation, and scale.
    commands.spawn((
        Transform::default(),
        TransformInterpolation,
    ));
}

Now, any changes made to the Transform of the entity in FixedPreUpdate, FixedUpdate, or FixedPostUpdate will automatically be interpolated in between fixed timesteps.

If you want all entities with a Transform to be interpolated by default, you can use TransformInterpolationPlugin::interpolate_all():

fn main() {
   App::new()
      .add_plugins(TransformInterpolationPlugin::interpolate_all())
      // ...
      .run();
}

See the documentation of the TransformInterpolationPlugin for a more detailed overview of what it can do.

Advanced Usage

For a lot of applications, the functionality shown in the Getting Started guide might be all you need! However, bevy_transform_interpolation has a lot more to offer:

• Granularly ease individual properties of the transform with TranslationInterpolation, RotationInterpolation, and ScaleInterpolation.
• Opt out of transform easing for individual entities with NoTranslationEasing, NoRotationEasing, and NoScaleEasing.
• Use extrapolation instead of interpolation with the TransformExtrapolationPlugin and its related components.
• Use Hermite interpolation for more natural and accurate movement with the TransformHermiteEasingPlugin.
• Implement custom easing backends for your specific needs.

How Does It Work?

Internally, bevy_transform_interpolation simply maintains components that store the start and end of the interpolation. For example, translation uses the following component for easing the movement:

pub struct TranslationEasingState {
    pub start: Option<Vec3>,
    pub end: Option<Vec3>,
}

The states are updated by the TransformInterpolationPlugin or TransformExtrapolationPlugin depending on whether the entity has TransformInterpolation or TransformExtrapolation components.

If interpolation is used:

• In FixedFirst, start is set to the current Transform.
• In FixedLast, end is set to the current Transform.

If extrapolation is used:

• In FixedLast, start is set to the current Transform, and end is set to the Transform predicted based on velocity.

At the start of the FixedFirst schedule, the states are reset to None. If the Transform is detected to have changed since the last easing run but outside of the fixed timestep schedules, the easing is also reset to None to prevent overwriting the change.

The actual easing is performed in RunFixedMainLoop, right after FixedMain, before Update. By default, linear interpolation (lerp) is used for translation and scale, and spherical linear interpolation (slerp) is used for rotation.

However, thanks to the modular and flexible architecture, other easing methods can also be used. The TransformHermiteEasingPlugin provides an easing backend using Hermite interpolation, overwriting the linear interpolation for specific entities with the NonlinearTranslationEasing and NonlinearRotationEasing marker components. Custom easing solutions can be implemented using the same pattern.

Modules

• extrapolation
  Transform extrapolation, making movement in FixedUpdate appear smooth by easing between the current and predicted Transform in between fixed timesteps.
• hermite
  Hermite interpolation for Transform easing.
• interpolation
  Transform interpolation, making movement in FixedUpdate appear smooth by easing between the old and current Transform in between fixed timesteps.
• prelude
  The prelude.

Structs

• LastEasingTick
  A resource that stores the last tick when easing was performed.
• NoRotationEasing
  Explicitly marks this entity as having no rotation easing, disabling interpolation and/or extrapolation.
• NoScaleEasing
  Explicitly marks this entity as having no scale easing, disabling interpolation and/or extrapolation.
• NoTransformEasing
  Explicitly marks this entity as having no transform easing, disabling interpolation and/or extrapolation.
• NoTranslationEasing
  Explicitly marks this entity as having no translation easing, disabling interpolation and/or extrapolation.
• NonlinearRotationEasing
  A marker component that indicates that the entity has non-linear rotation easing, and linear easing should not be applied.
• NonlinearTranslationEasing
  A marker component that indicates that the entity has non-linear translation easing, and linear easing should not be applied.
• RotationEasingState
  Stores the start and end states used for interpolating the rotation of an entity. The change in rotation is smoothed from start to end in between FixedUpdate runs.
• ScaleEasingState
  Stores the start and end states used for interpolating the scale of an entity. The change in scale is smoothed from start to end in between FixedUpdate runs.
• TransformEasingPlugin
  A plugin for applying easing to Transform changes, making movement in FixedUpdate appear smooth.
• TranslationEasingState
  Stores the start and end states used for interpolating the translation of an entity. The change in translation is smoothed from start to end in between FixedUpdate runs.

Enums

• TransformEasingSet
  A system set for easing transform.

Traits

• VelocitySource
  A QueryData type for specifying the components that store velocity for easing. Required for TransformExtrapolationPlugin and TransformHermiteEasingPlugin.

Functions

• reset_easing_states_on_transform_change
  Resets the easing states to None when Transform is modified outside of the fixed timestep schedules or interpolation logic. This makes it possible to “teleport” entities in schedules like Update.