Struct avian3d::PhysicsPlugins

pub struct PhysicsPlugins { /* private fields */ }

A plugin group containing all of Avian’s plugins.

By default, the following plugins will be added:

Plugin	Description
PhysicsSchedulePlugin	Sets up the physics engine by initializing the necessary schedules, sets and resources.
PhysicsTypeRegistrationPlugin	Registers physics types to the TypeRegistry resource in bevy_reflect.
PreparePlugin	Runs systems at the start of each physics frame. Initializes rigid bodies and updates components.
ColliderBackendPlugin	Handles generic collider backend logic, like initializing colliders and AABBs and updating related components.
ColliderHierarchyPlugin	Handles transform propagation and ColliderParent updates for colliders.
BroadPhasePlugin	Collects pairs of potentially colliding entities into BroadCollisionPairs using AABB intersection checks.
NarrowPhasePlugin	Computes contacts between entities and sends collision events.
ContactReportingPlugin	Sends collision events and updates CollidingEntities.
IntegratorPlugin	Handles motion caused by velocity, and applies external forces and gravity.
SolverPlugin	Manages and solves contacts, joints, and other constraints.
CcdPlugin	Performs sweep-based Continuous Collision Detection for bodies with the SweptCcd component.
SleepingPlugin	Manages sleeping and waking for bodies, automatically deactivating them to save computational resources.
SpatialQueryPlugin	Handles spatial queries like raycasting and shapecasting.
SyncPlugin	Keeps Position and Rotation in sync with Transform.
PhysicsDebugPlugin	Renders physics objects and events like AABBs and contacts for debugging purposes (only with debug-plugin feature enabled).

Refer to the documentation of the plugins for more information about their responsibilities and implementations.

World scale

The PhysicsLengthUnit resource is a units-per-meter scaling factor that adjusts the engine’s internal properties to the scale of the world. It is recommended to configure the length unit to match the approximate length of the average dynamic object in the world to get the best simulation results.

For example, a 2D game might use pixels as units and have an average object size of around 100 pixels. By setting the length unit to 100.0, the physics engine will interpret 100 pixels as 1 meter for internal thresholds, improving stability.

The length unit can be set by inserting the resource like normal, but it can also be specified through the PhysicsPlugins plugin group.

use avian2d::prelude::*;
use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            // A 2D game with 100 pixels per meter
            PhysicsPlugins::default().with_length_unit(100.0),
        ))
        .run();
}

Custom schedule

You can run the PhysicsSchedule in any schedule you want by specifying the schedule when adding the plugin group:

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

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, PhysicsPlugins::new(FixedUpdate)))
        .run();
}

Note that using FixedUpdate with a fixed physics timestep can produce unexpected results due to two separate fixed timesteps. However, using FixedUpdate can be useful for networking usage when you need to keep the client and server in sync.

Custom plugins

First, create a new plugin. If you want to run your systems in the engine’s schedules, get either the PhysicsSchedule or the SubstepSchedule. Then you can add your systems to that schedule and control system ordering with system sets like PhysicsStepSet, SolverSet, or SubstepSolverSet.

Here we will create a custom broad phase plugin that will replace the default BroadPhasePlugin:

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

pub struct CustomBroadPhasePlugin;

impl Plugin for CustomBroadPhasePlugin {
    fn build(&self, app: &mut App) {
        // Make sure the PhysicsSchedule is available
        let physics_schedule = app
            .get_schedule_mut(PhysicsSchedule)
            .expect("add PhysicsSchedule first");

        // Add the system into the broad phase system set
        physics_schedule.add_systems(collect_collision_pairs.in_set(PhysicsStepSet::BroadPhase));
    }
}

fn collect_collision_pairs() {
    // Implementation goes here
}

Next, when creating your app, simply disable the default BroadPhasePlugin and add your custom plugin:

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

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

    app.add_plugins(DefaultPlugins);

    // Add PhysicsPlugins and replace default broad phase with our custom broad phase
    app.add_plugins(
        PhysicsPlugins::default()
            .build()
            .disable::<BroadPhasePlugin>()
            .add(CustomBroadPhasePlugin),
    );

    app.run();
}

You can find a full working example here.

Implementations

impl PhysicsPlugins

pub fn new(schedule: impl ScheduleLabel) -> Self

Creates a PhysicsPlugins plugin group using the given schedule for running the PhysicsSchedule.

The default schedule is PostUpdate.

pub fn with_length_unit(self, unit: Scalar) -> Self

Sets the value used for the PhysicsLengthUnit, a units-per-meter scaling factor that adjusts the engine’s internal properties to the scale of the world.

For example, a 2D game might use pixels as units and have an average object size of around 100 pixels. By setting the length unit to 100.0, the physics engine will interpret 100 pixels as 1 meter for internal thresholds, improving stability.

Note that this is not used to scale forces or any other user-facing inputs or outputs. Instead, the value is only used to scale some internal length-based tolerances, such as SleepingThreshold::linear and NarrowPhaseConfig::default_speculative_margin, as well as the scale used for debug rendering.

Choosing the appropriate length unit can help improve stability and robustness.

Example

use avian2d::prelude::*;
use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            // A 2D game with 100 pixels per meter
            PhysicsPlugins::default().with_length_unit(100.0),
        ))
        .run();
}

Trait Implementations

impl Default for PhysicsPlugins

fn default() -> Self

Returns the “default value” for a type.

impl PluginGroup for PhysicsPlugins

fn build(self) -> PluginGroupBuilder

Configures the Plugins that are to be added.

fn name() -> String

Configures a name for the PluginGroup which is primarily used for debugging.

fn set<T>(self, plugin: T) -> PluginGroupBuilder

where T: Plugin,

Sets the value of the given Plugin, if it exists