Bevy Rapier

To measure timings with detailed information using the standalone benchmark binary, run the bench binary in release mode. This binary executes different scene setups, gathers information, and outputs the results at the end.

cargo run --release --bin bench

For short-lived benchmarks that rely on statistical analysis, use the divan bench harness by running cargo bench for the bevy_rapier_benches3d package.

cargo bench -p bevy_rapier_benches3d

The modify_solver_contacts hook in BevyPhysicsHooks provides a ContactModificationContextView to manipulate how the constraints solver sees contacts. This is useful for:

• Conveyor Belts: Setting the surface_velocity of a solver contact.
• Variable Materials: Modifying friction and restitution coefficients based on contact features.
• One-way Platforms: Modifying the contact normal.
• Disabling Contacts: Calling context.solver_contacts.clear() to ignore all contacts in a manifold.

Each contact manifold also provides context.user_data, a u32 that is persistent between timesteps as long as the manifold exists.

When working with 3D meshes and the async-collider feature, use AsyncCollider or AsyncSceneCollider. These components act as placeholders that will be replaced by actual collider shapes once the Bevy mesh assets are loaded and processed.

ComputedColliderShape

Defines how the mesh should be converted into a collider:

• TriMesh(TriMeshFlags): A triangle mesh.
• ConvexHull: A convex hull of the mesh.
• ConvexDecomposition(VHACDParameters): A convex decomposition (VHACD).

By default, Collider uses the scale from the entity's GlobalTransform. You can override this behavior using the ColliderScale component:

• ColliderScale::Relative(Vect): Multiplies the GlobalTransform scale by this value.
• ColliderScale::Absolute(Vect): Replaces the GlobalTransform scale with this value.

The Rapier physics pipeline is organized into three main execution phases, represented by the PhysicsSet enum. These sets ensure that data is synchronized between Bevy and the Rapier backend in the correct order:

1. PhysicsSet::SyncBackend: Synchronizes and initializes backend data structures (like Rapier's internal rigid body sets) with current Bevy component state. This includes handling entity additions, removals, and transform changes.
2. PhysicsSet::StepSimulation: Advances the actual physics simulation and updates the internal state for scene queries.
3. PhysicsSet::Writeback: Writes the results of the simulation (e.g., new positions, velocities, and collision events) back into Bevy components and GlobalTransforms.

TypedJoint is a wrapper enum that allows you to treat different specific joint types uniformly. It provides implementations for AsRef<GenericJoint> and AsMut<GenericJoint>, allowing you to access the underlying GenericJoint data regardless of the specific joint type used.

Supported joint types within TypedJoint include:

• FixedJoint
• GenericJoint
• PrismaticJoint
• RevoluteJoint
• RopeJoint
• SpringJoint
• SphericalJoint (available when the dim3 feature is enabled)

The RigidBody component determines how an entity interacts with the physics engine. Use the following variants:

• RigidBody::Dynamic: Affected by all external forces (gravity, impulses, etc.).
• RigidBody::Fixed: Cannot be affected by external forces; acts as a static object.
• RigidBody::KinematicPositionBased: Cannot be affected by external forces but can be controlled by the user via position. It provides one-way interaction (it can push dynamic bodies, but cannot be pushed by them).
• RigidBody::KinematicVelocityBased: Cannot be affected by external forces but can be controlled by the user via velocity. It also provides one-way interaction.

Note: A RigidBody's trajectory is independent of any contacts or joints when using kinematic types.

To manage the mass of a RigidBody, use these components:

• AdditionalMassProperties: Use this to set additional mass.
  • AdditionalMassProperties::Mass(f32): Adds a specific mass value to the body.
  • AdditionalMassProperties::MassProperties(MassProperties): Adds custom mass, center of mass, and inertia.
• ReadMassProperties: Use this to read the total mass properties (including contributions from attached colliders). Modifying this component does not affect the actual physics simulation; use AdditionalMassProperties instead.

MassProperties contains:

• local_center_of_mass: The center of mass in local space.
• mass: The total mass.
• principal_inertia: The principal angular inertia (scalar in 2D, Vect in 3D).
• principal_inertia_local_frame: The principal vectors of the local angular inertia tensor (3D only).

A SpringJoint is integrated implicitly. This means that even an undamped spring will be subject to some amount of numerical damping and will eventually come to rest.

To achieve more realistic results and reduce the effect of numerical damping, you should:

1. Increase the number of solver iterations.
2. Use smaller timesteps.