Struct PhysicsPlugins

pub struct PhysicsPlugins { /* private fields */ }

A plugin group containing Avian’s plugins.

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.
ColliderBackendPlugin	Handles generic collider backend logic, like initializing colliders and AABBs and updating related components.
ColliderHierarchyPlugin	Manages ColliderOf relationships based on the entity hierarchy.
ColliderTransformPlugin	Propagates and updates transforms for colliders.
BroadPhasePlugin	Finds pairs of entities with overlapping AABBs to reduce the number of potential contacts for the narrow phase.
NarrowPhasePlugin	Manages contacts and generates contact constraints.
SolverPlugins	A plugin group for the physics solver’s plugins. See the plugin group’s documentation for more information.
JointPlugin	A plugin for managing and initializing joints. Does not include the actual joint solver.
MassPropertyPlugin	Manages mass properties of dynamic rigid bodies.
ForcePlugin	Manages and applies external forces, torques, and acceleration for rigid bodies. See the module-level documentation.
SpatialQueryPlugin	Handles spatial queries like raycasting and shapecasting.
PhysicsInterpolationPlugin	Transform interpolation and extrapolation for rigid bodies.
PhysicsTransformPlugin	Manages physics transforms and synchronizes them with Transform.

Optional additional plugins include:

Plugin	Description
[PhysicsPickingPlugin]	Enables a physics picking backend for bevy_picking (only with bevy_picking feature enabled).
PhysicsDebugPlugin	Renders physics objects and events like AABBs and contacts for debugging purposes (only with debug-plugin feature enabled).
[PhysicsDiagnosticsPlugin]	Writes physics diagnostics to the DiagnosticsStore (only with bevy_diagnostic feature enabled).
[PhysicsDiagnosticsUiPlugin]	Displays physics diagnostics with a debug UI overlay (only with diagnostic_ui 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()
        // Run physics at a variable timestep in `PostUpdate`.
        .add_plugins((DefaultPlugins, PhysicsPlugins::new(PostUpdate)))
        .run();
}

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 PhysicsStepSystems, SolverSystems, or SubstepSolverSystems.

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(PhysicsStepSystems::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 FixedPostUpdate.

pub fn with_collision_hooks<H: CollisionHooks + 'static>( self, ) -> PhysicsPluginsWithHooks<H>

where for<'w, 's> SystemParamItem<'w, 's, H>: CollisionHooks,

Adds the given CollisionHooks for user-defined contact filtering and modification.

Returns a PhysicsPluginsWithHooks plugin group, which wraps the original PhysicsPlugins, and applies the provided hooks. Only one set of collision hooks can be defined per application.

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