Struct PhysicsInterpolationPlugin

pub struct PhysicsInterpolationPlugin { /* private fields */ }

A plugin for Transform interpolation and extrapolation for rigid bodies.

Overview

To make behavior deterministic and independent of frame rate, Avian runs physics at a fixed timestep in FixedPostUpdate by default. However, when this timestep doesn’t match the display frame rate, movement can appear choppy, especially on displays with high refresh rates.

The conventional solution is to ease transforms in between physics ticks to smooth out the visual result. This can be done using either interpolation or extrapolation.

Interpolation

Transform interpolation computes a Transform that is somewhere in between the current position and the position from the previous physics tick. This produces smooth and accurate movement.

The downside of interpolation is that it causes rendering to be slightly behind the physics simulation. This can make movement feel slightly delayed, but this is rarely noticeable unless using a very small physics tick rate.

Extrapolation

Transform extrapolation computes a Transform that is somewhere in between the current position and a future position predicted based on velocity. This produces movement that looks smooth and feels very responsive.

The downside of extrapolation is that it can be less accurate. When the prediction is wrong, the rendered positions may jump to correct the mispredictions. This can be noticeable when the entity changes direction or speed rapidly.

Extrapolation is primarily inteded for cases where low latency and high responsiveness are crucial for gameplay, such as first-person shooters and racing games. For most other games, interpolation is often the better choice.

Usage

The PhysicsInterpolationPlugin is included in the PhysicsPlugins by default, so most apps don’t need to add it manually.

Transform interpolation and extrapolation can be enabled for individual entities using the TransformInterpolation and TransformExtrapolation components respectively:

use avian3d::prelude::*;
use bevy::prelude::*;

fn setup(mut commands: Commands) {
    // Enable interpolation for this rigid body.
    commands.spawn((
        RigidBody::Dynamic,
        Transform::default(),
        TransformInterpolation,
    ));

    // Enable extrapolation for this rigid body.
    commands.spawn((
        RigidBody::Dynamic,
        Transform::default(),
        TransformExtrapolation,
    ));
}

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

Transform properties can also be interpolated individually by adding the TranslationInterpolation, RotationInterpolation, and ScaleInterpolation components, and similarly for extrapolation.

fn setup(mut commands: Commands) {
    // Only interpolate translation.
    commands.spawn((Transform::default(), TranslationInterpolation));
     
    // Only interpolate rotation.
    commands.spawn((Transform::default(), RotationInterpolation));
     
    // Only interpolate scale.
    commands.spawn((Transform::default(), ScaleInterpolation));
     
    // Mix and match!
    // Extrapolate translation and interpolate rotation.
    commands.spawn((
        Transform::default(),
        TranslationExtrapolation,
        RotationInterpolation,
    ));
}

If you want all rigid bodies to be interpolated or extrapolated by default, you can use PhysicsInterpolationPlugin::interpolate_all() or PhysicsInterpolationPlugin::extrapolate_all():

fn main() {
   App::new()
      .add_plugins(PhysicsPlugins::default().set(PhysicsInterpolationPlugin::interpolate_all()))
      // ...
      .run();
}

When interpolation or 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, NoRotationEasing, and NoScaleEasing 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 interpolation for the entity for the remainder of that fixed timestep.

Hermite Interpolation

By default, linear interpolation (lerp) is used for easing translation and scale, and spherical linear interpolation (slerp) is used for easing rotation. This is computationally efficient and works well for most cases.

However, linear interpolation doesn’t consider velocity, which can make trajectories look less smooth at low tick rates. Very high angular velocities (ex: for car wheels or fan blades) can be especially problematic, as slerp always takes the shortest path between two rotations, which can sometimes cause entities to rotate in the opposite direction.

Unlike linear interpolation, Hermite interpolation uses both position and velocity information to estimate the trajectories of entities, producing smoother results. To enable it for interpolation or extrapolation, add the TransformHermiteEasing component or the individual TranslationHermiteEasing and RotationHermiteEasing components:

fn setup(mut commands: Commands) {
    // Enable Hermite interpolation for this rigid body.
    commands.spawn((
        RigidBody::Dynamic,
        Transform::default(),
        TransformInterpolation,
        TransformHermiteEasing,
    ));
}

Hermite interpolation is more expensive than linear interpolation, so it is generally recommended to only use it when it produces noticeable benefits. For most cases, linear interpolation should be sufficient.

Note that scale interpolation is always linear, and does not support Hermite interpolation.

General Interpolation or Extrapolation

Avian uses bevy_transform_interpolation for interpolation and extrapolation. It is not limited to physics entities, so it is actually possible to use the components shown here for interpolating the Transform of any entity!

Refer to the bevy_transform_interpolation documentation for more information on how to use it.

Implementations

impl PhysicsInterpolationPlugin

pub const fn interpolate_all() -> Self

Enables interpolation of translation and rotation for all rigid bodies.

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

pub const fn interpolate_translation_all() -> Self

Enables interpolation of translation for all rigid bodies.

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

pub const fn interpolate_rotation_all() -> Self

Enables interpolation of rotation for all rigid bodies.

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

pub const fn extrapolate_all() -> Self

Enables extrapolation of translation and rotation for all rigid bodies.

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

pub const fn extrapolate_translation_all() -> Self

Enables extrapolation of translation for all rigid bodies.

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

pub const fn extrapolate_rotation_all() -> Self

Enables extrapolation of rotation for all rigid bodies.

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

Trait Implementations

impl Debug for PhysicsInterpolationPlugin

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

Formats the value using the given formatter.

impl Default for PhysicsInterpolationPlugin

fn default() -> PhysicsInterpolationPlugin

Returns the “default value” for a type.

impl Plugin for PhysicsInterpolationPlugin

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

Configures the App to which this plugin is added.

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 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 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.