Struct rapier3d::dynamics::IntegrationParameters

pub struct IntegrationParameters {

    pub dt: Real,
    pub min_ccd_dt: Real,
    pub erp: Real,
    pub damping_ratio: Real,
    pub joint_erp: Real,
    pub joint_damping_ratio: Real,
    pub warmstart_coefficient: Real,
    pub length_unit: Real,
    pub normalized_allowed_linear_error: Real,
    pub normalized_max_penetration_correction: Real,
    pub normalized_prediction_distance: Real,
    pub num_solver_iterations: NonZeroUsize,
    pub num_additional_friction_iterations: usize,
    pub num_internal_pgs_iterations: usize,
    pub num_internal_stabilization_iterations: usize,
    pub min_island_size: usize,
    pub max_ccd_substeps: usize,
}

Parameters for a time-step of the physics engine.

Fields

dt: Real

The timestep length (default: 1.0 / 60.0)

min_ccd_dt: Real

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.

erp: Real

0-1: multiplier for how much of the constraint violation (e.g. contact penetration) will be compensated for during the velocity solve. (default 0.1).

damping_ratio: Real

0-1: the damping ratio used by the springs for Baumgarte constraints stabilization. Lower values make the constraints more compliant (more “springy”, allowing more visible penetrations before stabilization). (default 20.0).

joint_erp: Real

0-1: multiplier for how much of the joint violation will be compensated for during the velocity solve. (default 1.0).

joint_damping_ratio: Real

The fraction of critical damping applied to the joint for constraints regularization. (default 1.0).

warmstart_coefficient: Real

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. Can be set to 0 if using a large Self::erp value. (default 1.0).

length_unit: Real

The approximate size of most dynamic objects in the scene.

This value is used internally to estimate some length-based tolerance. In particular, the values IntegrationParameters::allowed_linear_error, IntegrationParameters::max_penetration_correction, IntegrationParameters::prediction_distance, [RigidBodyActivation::linear_threshold] are scaled by this value implicitly.

This value can be understood as the number of units-per-meter in your physical world compared to a human-sized world in meter. For example, in a 2d game, if your typical object size is 100 pixels, set the [Self::length_unit] parameter to 100.0. The physics engine will interpret it as if 100 pixels is equivalent to 1 meter in its various internal threshold. (default 1.0).

normalized_allowed_linear_error: Real

Amount of penetration the engine won’t attempt to correct (default: 0.001m).

This value is implicitly scaled by IntegrationParameters::length_unit.

normalized_max_penetration_correction: Real

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

This value is implicitly scaled by IntegrationParameters::length_unit.

normalized_prediction_distance: Real

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

This value is implicitly scaled by IntegrationParameters::length_unit.

num_solver_iterations: NonZeroUsize

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

num_additional_friction_iterations: usize

Number of addition friction resolution iteration run during the last solver sub-step (default: 4).

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: 2).

min_island_size: usize

Minimum number of dynamic bodies in each active island (default: 128).

max_ccd_substeps: usize

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

Implementations

impl IntegrationParameters

pub fn inv_dt(&self) -> Real

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: Real)

👎Deprecated: You can just set the IntegrationParams::dt value directly

Sets the time-stepping length.

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

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

This automatically recompute self.dt.

pub fn erp_inv_dt(&self) -> Real

The ERP coefficient, multiplied by the inverse timestep length.

pub fn joint_erp_inv_dt(&self) -> Real

The joint ERP coefficient, multiplied by the inverse timestep length.

pub fn cfm_factor(&self) -> Real

The CFM factor to be used in the constraints resolution.

pub fn joint_cfm_coeff(&self) -> Real

The CFM (constraints force mixing) coefficient applied to all joints for constraints regularization

pub fn allowed_linear_error(&self) -> Real

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

pub fn max_penetration_correction(&self) -> Real

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

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

pub fn prediction_distance(&self) -> Real

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

pub fn tgs_soft() -> Self

Initialize the simulation parameters with settings matching the TGS-soft solver with warmstarting.

This is the default configuration, equivalent to IntegrationParameters::default().

pub fn tgs_soft_without_warmstart() -> Self

Initialize the simulation parameters with settings matching the TGS-soft solver without warmstarting.

The IntegrationParameters::tgs_soft() configuration should be preferred unless warmstarting proves to be undesirable for your use-case.

pub fn pgs_legacy() -> Self

Initializes the integration parameters to match the legacy PGS solver from Rapier version <= 0.17.

This exists mainly for testing and comparison purpose.

Trait Implementations

impl Clone for IntegrationParameters

fn clone(&self) -> IntegrationParameters

Returns a copy of the value.

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

Performs copy-assignment from source.

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<'de> Deserialize<'de> for IntegrationParameters

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for IntegrationParameters

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for IntegrationParameters