Avian Physics Engine

In v0.2, CollisionLayers no longer defaults to "all memberships, all filters". Instead, colliders only belong to the first layer by default (bit 0b0001).

If you use the PhysicsLayer derive macro, you must implement Default for your enum and use the #[default] attribute to specify which variant represents the default layer 0b0001.

#[derive(PhysicsLayer, Default)]
enum GameLayer {
    #[default]
    Default,
    Player,
    Enemy,
    Ground,
}

Joints have undergone significant changes in v0.4:

• Location: Joint APIs moved from dynamics::solver::joints to dynamics::joints.
• Trait: The Joint trait is removed; use the EntityConstraint trait or joint-specific helper methods.
• Naming:
  • entity1/entity2 $\rightarrow$ body1/body2.
  • PrismaticJoint::free_axis $\rightarrow$ slider_axis.
  • RevoluteJoint::aligned_axis $\rightarrow$ hinge_axis.
  • with_local_anchor_1/2 $\rightarrow$ with_local_anchor1/2 (returns Option).
• Components: Damping and force properties are removed from joint types. Use JointDamping and JointForces components instead.
• Constraint: Each entity can only hold one type of joint component. To attach a rigid body to multiple bodies, each joint must reside on its own entity.

The BroadPhasePlugin has been replaced by two separate plugins. To implement broad phase collision detection, you must now use both:

• BroadPhaseCorePlugin: Sets up necessary resources, system sets, and diagnostics.
• BvhBroadPhasePlugin: Implements the Bounding Volume Hierarchy (BVH) for efficient AABB overlap detection.

Note that BroadPhaseSystems::UpdateStructures has been removed. Acceleration structures are now updated by the ColliderTreePlugin via ColliderTreeSystems::UpdateAabbs.

To isolate benchmarks for a specific dimension, disable default features and enable either the 2d or 3d feature flag.

# List all 2D benchmarks
cargo run --no-default-features --features 2d -- --list

# Run all 3D benchmarks with default options
cargo run --no-default-features --features 3d

Avian 0.4 overhauls the force APIs. The components ExternalForce, ExternalTorque, ExternalImpulse, and ExternalAngularImpulse have been removed.

• Persistent forces/torques: Use ConstantForce and ConstantTorque.
• Non-persistent forces (cleared automatically): Use the Forces helper QueryData.
• Impulses: Impulses can no longer be persistent; use persistent forces instead.

Note: The ForcePlugin must be enabled (included in PhysicsPlugins by default) for forces to function.

The ContactReportingPlugin and PhysicsStepSet::ReportContacts have been removed. Contact reporting is now handled directly by NarrowPhasePlugin.

Collision Events

• The Collision event no longer exists. Use the Collisions resource or the CollidingEntities component.
• CollisionStarted and CollisionEnded events are only sent if at least one entity in the collision has the CollisionEventsEnabled component.
• To restore old behavior (events for all entities), register CollisionEventsEnabled as a required component for Collider:

app.register_required_components::<Collider, CollisionEventsEnabled>();

Contact APIs have been updated for clarity and accuracy:

• Impulses: ContactPoint::normal_impulse now represents the total normal impulse applied at a contact point (not just the warm-starting impulse). To get force, divide by the time step.
• Warm Starting: Old warm-starting impulses are now stored in warm_start_normal_impulse and warm_start_tangent_impulse.
• Contact Points: local_point1/local_point2 are removed. Use world-space anchor1/anchor2 (relative to center of mass) or the midpoint point.
• Contact Graph:
  • iter/iter_mut $\rightarrow$ iter_active/iter_active_mut or iter_sleeping/iter_sleeping_mut.
  • collisions_with $\rightarrow$ contact_pairs_with.
  • add_pair $\rightarrow$ add_edge.
  • remove_pair $\rightarrow$ remove_edge.

Add the appropriate crate to your Cargo.toml dependencies based on your application's dimension. Use version 0.7 for Bevy 0.19.

To use the most up-to-date version from the main branch, use the git dependency format.

# For 2D applications:
[dependencies]
avian2d = "0.7"

# For 3D applications:
[dependencies]
avian3d = "0.7"

# If you want to use the most up-to-date version, you can follow the main branch:
[dependencies]
avian3d = { git = "https://github.com/avianphysics/avian", branch = "main" }