Struct IntegrationParameters 

pub struct IntegrationParameters {

    pub dt: f32,
    pub min_ccd_dt: f32,
    pub contact_softness: SpringCoefficients<f32>,
    pub static_contact_softness: SpringCoefficients<f32>,
    pub warmstart_coefficient: f32,
    pub length_unit: f32,
    pub normalized_allowed_linear_error: f32,
    pub normalized_max_corrective_velocity: f32,
    pub normalized_prediction_distance: f32,
    pub normalized_max_linear_velocity: f32,
    pub num_solver_iterations: usize,
    pub num_internal_pgs_iterations: usize,
    pub num_internal_stabilization_iterations: usize,
    pub max_ccd_substeps: usize,
    pub contact_clustering: bool,
    pub contact_recycling: bool,
    pub normalized_contact_recycle_distance: f32,
    pub friction_in_bias_pass: bool,
    pub warmstart_joints: bool,
}

Configuration parameters that control the physics simulation quality and behavior.

These parameters affect how the physics engine advances time, resolves collisions, and maintains stability. The defaults work well for most games, but you may want to adjust them based on your specific needs.

Key parameters for beginners

• dt: Timestep duration (default: 1/60 second). Most games run physics at 60Hz.
• num_solver_iterations: More iterations = more accurate but slower (default: 4)
• length_unit: Scale factor if your world units aren’t meters (e.g., 100 for pixel-based games)

Example

// Standard 60 FPS physics with default settings
let mut integration_params = IntegrationParameters::default();

// For a more accurate (but slower) simulation:
integration_params.num_solver_iterations = 8;

// For pixel-based 2D games where 100 pixels = 1 meter:
integration_params.length_unit = 100.0;

Most other parameters are advanced settings for fine-tuning stability and performance.

Fields

dt: f32

The timestep length - how much simulated time passes per physics step (default: 1.0 / 60.0).

Set this to 1.0 / your_target_fps. For example:

• 60 FPS: 1.0 / 60.0 ≈ 0.0167 seconds
• 120 FPS: 1.0 / 120.0 ≈ 0.0083 seconds

Smaller timesteps are more accurate but require more CPU time per second of simulated time.

min_ccd_dt: f32

Minimum timestep size when using CCD with multiple substeps (default: 1.0 / 60.0 / 100.0).

When CCD with multiple substeps is enabled, the timestep is subdivided into smaller pieces. This timestep subdivision won’t generate timestep lengths smaller than min_ccd_dt.

Setting this to a large value will reduce the opportunity to performing CCD substepping, resulting in potentially more time dropped by the motion-clamping mechanism. Setting this to an very small value may lead to numerical instabilities.

contact_softness: SpringCoefficients<f32>

Softness coefficients for contact constraints.

static_contact_softness: SpringCoefficients<f32>

Softness coefficients for contact constraints where one side is a fixed body.

Stiffer than Self::contact_softness by default so bodies are held firmly against static walls/floors; set equal to Self::contact_softness to disable.

warmstart_coefficient: f32

The coefficient in [0, 1] applied to warmstart impulses, i.e., impulses that are used as the initial solution (instead of 0) at the next simulation step.

This should generally be set to 1.

(default 1.0).

length_unit: f32

The scale factor for your world if you’re not using meters (default: 1.0).

Rapier is tuned for human-scale objects measured in meters. If your game uses different units, set this to how many of your units equal 1 meter in the real world.

Examples:

• Your game uses meters: length_unit = 1.0 (default)
• Your game uses centimeters: length_unit = 100.0 (100 cm = 1 m)
• Pixel-based 2D game where typical objects are 100 pixels tall: length_unit = 100.0
• Your game uses feet: length_unit = 3.28 (approximately)

This automatically scales various internal tolerances and thresholds to work correctly with your chosen units.

normalized_allowed_linear_error: f32

Geometric slop distance (default: 0.005), e.g. the standoff kept by the CCD clamp. NOT a deadzone on the position-correction bias: penetrations are corrected all the way to zero; a deadzone would keep loaded piles wedging and creeping.

This value is implicitly scaled by IntegrationParameters::length_unit.

normalized_max_corrective_velocity: f32

Maximum speed at which contact penetration is pushed out by the biased solve (default: 3.0).

Capping this recovery velocity keeps deep penetrations from being resolved explosively. This value is implicitly scaled by IntegrationParameters::length_unit.

normalized_prediction_distance: f32

The maximal distance separating two objects that will generate predictive contacts (default: 0.002m).

This value is implicitly scaled by IntegrationParameters::length_unit.

normalized_max_linear_velocity: f32

Maximum linear velocity a body may have after each solver substep (default: 400.0 m/s). Bounding per-step travel keeps CCD and speculative contacts reliable (a body cannot be flung or crushed to an arbitrary speed); set to Real::MAX to disable.

This value is implicitly scaled by IntegrationParameters::length_unit.

num_solver_iterations: usize

The number of solver iterations run by the constraints solver for calculating forces (default: 4).

Higher values produce more accurate and stable simulations at the cost of performance.

• 4 (default): Good balance for most games
• 8-12: Use for demanding scenarios (stacks of objects, complex machinery)
• 1-2: Use if performance is critical and accuracy can be sacrificed

num_internal_pgs_iterations: usize

Number of internal Project Gauss Seidel (PGS) iterations run at each solver iteration (default: 1).

num_internal_stabilization_iterations: usize

The number of stabilization iterations run at each solver iterations (default: 1).

max_ccd_substeps: usize

Maximum number of CCD substeps performed by the solver (default: 1).

Also the global CCD on/off switch: 0 disables all CCD for the world (including the automatic CCD of fast dynamic bodies vs fixed colliders).

contact_clustering: bool

If enabled, contact manifolds of a collider pair sharing (nearly) the same normal are merged into one “cluster” manifold before constraint generation (default: true, 3D only), so at most 4 contact points are solved per contact plane — a large solver win on composite shapes (meshes, heightfields, compounds, voxels) that emit one manifold per subshape. When clustering applies, read solver contacts/impulses from crate::geometry::ContactPair::solver_clusters, not crate::geometry::ContactPair::manifolds.

contact_recycling: bool

If enabled, a contact pair whose relative pose moved less than Self::contact_recycle_distance since its last full narrow-phase update skips contact determination and keeps its existing points (default: true) — a large speed-up for quasi-static scenes. Trade-offs: contact features and user-facing contact data (dist, is-new bits) may be stale by up to that distance, and per-step joint-based contact filtering is skipped until the pair moves. crate::pipeline::ActiveHooks pairs are never recycled.

normalized_contact_recycle_distance: f32

Maximum relative-pose drift (translation plus rotation-arc) below which a contact pair may be recycled instead of fully updated (default: 0.05, i.e. ten times the linear slop, multiplied by Self::length_unit). Only used when Self::contact_recycling is enabled.

friction_in_bias_pass: bool

If false, friction is only solved during the unbiased (relax) pass of each substep instead of both passes (default: false, the “no friction when applying bias” rule). This makes contact kernels much cheaper and is load-bearing for tall stacks: friction reacting to bias velocities pumps their coherent lean mode until they topple. If Self::num_internal_stabilization_iterations is zero there is no unbiased pass and this flag is ignored.

warmstart_joints: bool

If enabled, impulse-joint constraints are warm-started like contacts: impulses accumulated by the previous step are re-applied (scaled by Self::warmstart_coefficient) at the start of each substep instead of restarting from zero (default: false). This noticeably improves convergence of stiff joint assemblies. Multibody joints are unaffected.

Implementations

impl IntegrationParameters

pub fn inv_dt(&self) -> f32

The inverse of the time-stepping length, i.e. the steps per seconds (Hz).

This is zero if self.dt is zero.

pub fn set_dt(&mut self, dt: f32)

👎Deprecated:

You can just set the IntegrationParams::dt value directly

Sets the time-stepping length.

pub fn set_inv_dt(&mut self, inv_dt: f32)

Sets the inverse time-stepping length (i.e. the frequency).

This automatically recompute self.dt.

pub fn allowed_linear_error(&self) -> f32

Amount of penetration the engine won’t attempt to correct (default: 0.001 multiplied by Self::length_unit).

pub fn max_corrective_velocity(&self) -> f32

Maximum amount of penetration the solver will attempt to resolve in one timestep.

This is equal to Self::normalized_max_corrective_velocity multiplied by Self::length_unit.

pub fn prediction_distance(&self) -> f32

The maximal distance separating two objects that will generate predictive contacts (default: 0.002m multiped by Self::length_unit).

pub fn max_linear_velocity(&self) -> f32

Maximum linear velocity a body may have after each solver substep.

This is equal to Self::normalized_max_linear_velocity multiplied by Self::length_unit, or Real::MAX when the linear speed cap is disabled.

pub fn contact_recycle_distance(&self) -> f32

Maximum relative-pose drift below which a contact pair can be recycled instead of fully updated: Self::normalized_contact_recycle_distance multiplied by Self::length_unit. Only used when Self::contact_recycling is enabled.

Trait Implementations

impl Clone for IntegrationParameters

fn clone(&self) -> IntegrationParameters

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for IntegrationParameters

impl Debug for IntegrationParameters

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for IntegrationParameters

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for IntegrationParameters

fn eq(&self, other: &IntegrationParameters) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for IntegrationParameters