Struct TransformExtrapolationPlugin

pub struct TransformExtrapolationPlugin<LinVel: VelocitySource, AngVel: VelocitySource> {
    pub extrapolate_translation_all: bool,
    pub extrapolate_rotation_all: bool,
    /* private fields */
}

A plugin for Transform extrapolation, making movement in FixedUpdate appear smooth.

Transform extrapolation predicts future positions based on velocity, and applies easing between the current and predicted Transform in between fixed timesteps. This results in movement that looks smooth and feels responsive, but can stutter when the prediction is incorrect, such as when velocity changes abruptly.

This plugin requires the TransformEasingPlugin to function. It is automatically added if not already present in the app.

Note that unlike TransformInterpolationPlugin, this plugin does not support scale easing. However, the ScaleInterpolation component can still be used even when translation and rotation are extrapolated.

Usage

Transform extrapolation requires velocity to predict future positions. Instead of providing its own velocity components, the TransformExtrapolationPlugin lets you specify your own velocity components that you manage yourself.

First, make sure you have components for velocity, and implement the VelocitySource trait on a QueryData type:

use bevy::{ecs::query::QueryData, prelude::*};
use bevy_transform_interpolation::VelocitySource;

#[derive(Component, Default)]
struct LinearVelocity(Vec3);

#[derive(Component, Default)]
struct AngularVelocity(Vec3);

#[derive(QueryData)]
struct LinVelSource;

impl VelocitySource for LinVelSource {
    // Components storing the previous and current velocities.
    // Note: For extrapolation, the `Previous` component is not used, so we can make it the same as `Current`.
    type Previous = LinearVelocity;
    type Current = LinearVelocity;

    fn previous(start: &Self::Previous) -> Vec3 {
        start.0
    }

    fn current(end: &Self::Current) -> Vec3 {
        end.0
    }
}

#[derive(QueryData)]
struct AngVelSource;

impl VelocitySource for AngVelSource {
    type Previous = AngularVelocity;
    type Current = AngularVelocity;

    fn previous(start: &Self::Previous) -> Vec3 {
        start.0
    }

    fn current(end: &Self::Current) -> Vec3 {
        end.0
    }
}

Then, add the TransformExtrapolationPlugin to the app with the velocity sources:

use bevy::{ecs::query::QueryData, prelude::*};
use bevy_transform_interpolation::{prelude::*, VelocitySource};

fn main() {
   let mut app = App::new();

    app.add_plugins((
       TransformInterpolationPlugin::default(),
       TransformExtrapolationPlugin::<LinVelSource, AngVelSource>::default(),
   ));

   // Optional: Insert velocity components automatically for entities with extrapolation.
   app.register_required_components::<TranslationExtrapolation, LinearVelocity>();
   app.register_required_components::<RotationExtrapolation, AngularVelocity>();

   // ...

   app.run();
}

Transform extrapolation can now be enabled for a given entity by adding the TransformExtrapolation component:

fn setup(mut commands: Commands) {
    // Extrapolate translation and rotation.
    commands.spawn((
        Transform::default(),
        TransformExtrapolation,
    ));
}

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

Transform properties can also be extrapolated individually by adding the TranslationExtrapolation and RotationExtrapolation components.

fn setup(mut commands: Commands) {
    // Only extrapolate translation.
    commands.spawn((Transform::default(), TranslationExtrapolation));
     
    // Only extrapolate rotation.
    commands.spawn((Transform::default(), RotationExtrapolation));
}

If you want all entities with a Transform to be extrapolated by default, you can use TransformExtrapolationPlugin::extrapolate_all(), or set the extrapolate_translation_all and extrapolate_rotation_all fields.

fn main() {
   App::new()
      .add_plugins(TransformExtrapolationPlugin::<LinVelSource, AngVelSource> {
          // Extrapolate translation by default, but not rotation.
          extrapolate_translation_all: true,
          extrapolate_rotation_all: false,
      })
      // ...
      .run();
}

When extrapolation is enabled for all entities by default, you can still opt out of it for individual entities by adding the NoTransformEasing component, or the individual NoTranslationEasing and NoRotationEasing components.

Note that changing Transform manually in any schedule that doesn’t use a fixed timestep is also supported, but it is equivalent to teleporting, and disables extrapolation for the entity for the remainder of that fixed timestep.

Alternatives

For many applications, the stutter caused by mispredictions in extrapolation may be undesirable. In these cases, the TransformInterpolationPlugin can be a better alternative.

Transform interpolation eases between the previous and current Transform, resulting in movement that is always smooth and accurate. The downside is that the rendered positions can lag slightly behind the true positions, making movement feel delayed.

Easing Backends

By default, transform extrapolation uses linear interpolation (lerp) for easing translation, and spherical linear interpolation (slerp) for easing rotation.

If the previous and current velocities are also available, it is possible to use Hermite interpolation with the TransformHermiteEasingPlugin to get smoother and more accurate easing. To enable Hermite interpolation for extrapolation, add the TransformHermiteEasing component to the entity in addition to the extrapolation components.

Fields

extrapolate_translation_all: bool

If true, translation will be extrapolated for all entities with the Transform component by default.

This can be overridden for individual entities by adding the NoTranslationEasing or NoTransformEasing component.

extrapolate_rotation_all: bool

If true, rotation will be extrapolated for all entities with the Transform component by default.

This can be overridden for individual entities by adding the NoRotationEasing or NoTransformEasing component.

Implementations

impl<LinVel: VelocitySource, AngVel: VelocitySource> TransformExtrapolationPlugin<LinVel, AngVel>

pub fn extrapolate_all() -> Self

Enables extrapolation for translation and rotation for all entities with the Transform component.

This can be overridden for individual entities by adding the NoTransformEasing component, or the individual NoTranslationEasing and NoRotationEasing components.

Trait Implementations

impl<LinVel: Debug + VelocitySource, AngVel: Debug + VelocitySource> Debug for TransformExtrapolationPlugin<LinVel, AngVel>

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

Formats the value using the given formatter.

impl<LinVel: VelocitySource, AngVel: VelocitySource> Default for TransformExtrapolationPlugin<LinVel, AngVel>

fn default() -> Self

Returns the “default value” for a type.

impl<LinVel: VelocitySource, AngVel: VelocitySource> Plugin for TransformExtrapolationPlugin<LinVel, AngVel>

fn build(&self, app: &mut App)

Configures the App to which this plugin is added.

fn finish(&self, app: &mut App)

Finish adding this plugin to the App, once all plugins registered are ready. This can be useful for plugins that depends on another plugin asynchronous setup, like the renderer.

fn ready(&self, _app: &App) -> bool

Has the plugin finished its setup? This can be useful for plugins that need something asynchronous to happen before they can finish their setup, like the initialization of a renderer. Once the plugin is ready, finish should be called.

fn cleanup(&self, _app: &mut App)

Runs after all plugins are built and finished, but before the app schedule is executed. This can be useful if you have some resource that other plugins need during their build step, but after build you want to remove it and send it to another thread.

fn name(&self) -> &str

Configures a name for the Plugin which is primarily used for checking plugin uniqueness and debugging.

fn is_unique(&self) -> bool

If the plugin can be meaningfully instantiated several times in an App, override this method to return false.