Struct bevy_xpbd_3d::plugins::PhysicsPlugins

pub struct PhysicsPlugins { /* private fields */ }

A plugin group containing all of Bevy XPBD’s plugins.

By default, the following plugins will be added:

• PhysicsSetupPlugin: Sets up the physics engine by initializing the necessary schedules, sets and resources.
• PreparePlugin: Runs systems at the start of each physics frame; initializes rigid bodies and colliders and updates components.
• ColliderBackendPlugin: Handles generic collider backend logic, like initializing colliders and AABBs and updating related components.
• 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: Integrates Newton’s 2nd law of motion, applying forces and moving entities according to their velocities.
• SolverPlugin: Solves positional and angular constraints, updates velocities and solves velocity constraints (dynamic friction and restitution).
• SleepingPlugin: Controls when bodies should be deactivated and marked as Sleeping to improve performance.
• 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.

You can also find more information regarding the engine’s general plugin architecture here.

Custom schedule

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

use bevy::prelude::*;
use bevy_xpbd_3d::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 PhysicsSet or SubstepSet.

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

use bevy::prelude::*;
use bevy_xpbd_3d::{prelude::*, PhysicsSchedule, PhysicsStepSet};

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 bevy::prelude::*;
use bevy_xpbd_3d::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.

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 [Plugin]s 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