Struct rapier2d::dynamics::IntegrationParameters

pub struct IntegrationParameters {

    pub dt: f32,
    pub min_ccd_dt: f32,
    pub contact_damping_ratio: f32,
    pub contact_natural_frequency: f32,
    pub joint_natural_frequency: f32,
    pub joint_damping_ratio: 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 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: f32

The timestep length (default: 1.0 / 60.0).

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_damping_ratio: f32

0: the damping ratio used by the springs for contact constraint stabilization.

Larger values make the constraints more compliant (allowing more visible penetrations before stabilization). (default 5.0).

contact_natural_frequency: f32

0: the natural frequency used by the springs for contact constraint regularization.

Increasing this value will make it so that penetrations get fixed more quickly at the expense of potential jitter effects due to overshooting. In order to make the simulation look stiffer, it is recommended to increase the Self::contact_damping_ratio instead of this value. (default: 30.0).

joint_natural_frequency: f32

0: the natural frequency used by the springs for joint constraint regularization.

Increasing this value will make it so that penetrations get fixed more quickly. (default: 1.0e6).

joint_damping_ratio: f32

The fraction of critical damping applied to the joint for constraints regularization.

Larger values make the constraints more compliant (allowing more joint drift before stabilization). (default 1.0).

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 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_corrective_velocity, IntegrationParameters::prediction_distance, RigidBodyActivation::normalized_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: f32

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

This value is implicitly scaled by IntegrationParameters::length_unit.

normalized_max_corrective_velocity: f32

Maximum amount of penetration the solver will attempt to resolve in one timestep (default: 10.0).

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.

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

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) -> 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 contact_angular_frequency(&self) -> f32

The contact’s spring angular frequency for constraints regularization.

pub fn contact_erp_inv_dt(&self) -> f32

The Self::contact_erp coefficient, multiplied by the inverse timestep length.

pub fn contact_erp(&self) -> f32

The effective Error Reduction Parameter applied for calculating regularization forces on contacts.

This parameter is computed automatically from Self::contact_natural_frequency, Self::contact_damping_ratio and the substep length.

pub fn joint_angular_frequency(&self) -> f32

The joint’s spring angular frequency for constraint regularization.

pub fn joint_erp_inv_dt(&self) -> f32

The Self::joint_erp coefficient, multiplied by the inverse timestep length.

pub fn joint_erp(&self) -> f32

The effective Error Reduction Parameter applied for calculating regularization forces on joints.

This parameter is computed automatically from Self::joint_natural_frequency, Self::joint_damping_ratio and the substep length.

pub fn contact_cfm_factor(&self) -> f32

The CFM factor to be used in the constraint resolution.

This parameter is computed automatically from Self::contact_natural_frequency, Self::contact_damping_ratio and the substep length.

pub fn joint_cfm_coeff(&self) -> f32

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

This parameter is computed automatically from Self::joint_natural_frequency, Self::joint_damping_ratio and the substep length.

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 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