1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
use crate::math::Real; /// Parameters for a time-step of the physics engine. #[derive(Copy, Clone)] #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))] pub struct IntegrationParameters { /// The timestep length (default: `1.0 / 60.0`) pub 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. pub min_ccd_dt: Real, /// The Error Reduction Parameter in `[0, 1]` is the proportion of /// the positional error to be corrected at each time step (default: `0.2`). pub erp: Real, /// The Error Reduction Parameter for joints in `[0, 1]` is the proportion of /// the positional error to be corrected at each time step (default: `0.2`). pub joint_erp: Real, /// Each cached impulse are multiplied by this coefficient in `[0, 1]` /// when they are re-used to initialize the solver (default `1.0`). pub warmstart_coeff: Real, /// Correction factor to avoid large warmstart impulse after a strong impact (default `10.0`). pub warmstart_correction_slope: Real, /// 0-1: how much of the velocity to dampen out in the constraint solver? /// (default `1.0`). pub velocity_solve_fraction: Real, /// 0-1: multiplier for how much of the constraint violation (e.g. contact penetration) /// will be compensated for during the velocity solve. /// If zero, you need to enable the positional solver. /// If non-zero, you do not need the positional solver. /// A good non-zero value is around `0.2`. /// (default `0.0`). pub velocity_based_erp: Real, /// Amount of penetration the engine wont attempt to correct (default: `0.005m`). pub allowed_linear_error: Real, /// The maximal distance separating two objects that will generate predictive contacts (default: `0.002`). pub prediction_distance: Real, /// Amount of angular drift of joint limits the engine wont /// attempt to correct (default: `0.001rad`). pub allowed_angular_error: Real, /// Maximum linear correction during one step of the non-linear position solver (default: `0.2`). pub max_linear_correction: Real, /// Maximum angular correction during one step of the non-linear position solver (default: `0.2`). pub max_angular_correction: Real, /// Maximum number of iterations performed by the velocity constraints solver (default: `4`). pub max_velocity_iterations: usize, /// Maximum number of iterations performed by the position-based constraints solver (default: `1`). pub max_position_iterations: usize, /// Minimum number of dynamic bodies in each active island (default: `128`). pub min_island_size: usize, /// Maximum number of substeps performed by the solver (default: `1`). pub max_ccd_substeps: usize, } impl IntegrationParameters { /// Creates a set of integration parameters with the given values. #[deprecated = "Use `IntegrationParameters { dt: 60.0, ..Default::default() }` instead"] pub fn new( dt: Real, erp: Real, joint_erp: Real, warmstart_coeff: Real, allowed_linear_error: Real, allowed_angular_error: Real, max_linear_correction: Real, max_angular_correction: Real, prediction_distance: Real, max_velocity_iterations: usize, max_position_iterations: usize, max_ccd_substeps: usize, ) -> Self { IntegrationParameters { dt, erp, joint_erp, warmstart_coeff, allowed_linear_error, allowed_angular_error, max_linear_correction, max_angular_correction, prediction_distance, max_velocity_iterations, max_position_iterations, max_ccd_substeps, ..Default::default() } } /// The current time-stepping length. #[inline(always)] #[deprecated = "You can just read the `IntegrationParams::dt` value directly"] pub fn dt(&self) -> Real { self.dt } /// The inverse of the time-stepping length, i.e. the steps per seconds (Hz). /// /// This is zero if `self.dt` is zero. #[inline(always)] pub fn inv_dt(&self) -> Real { if self.dt == 0.0 { 0.0 } else { 1.0 / self.dt } } /// Sets the time-stepping length. #[inline] #[deprecated = "You can just set the `IntegrationParams::dt` value directly"] pub fn set_dt(&mut self, dt: Real) { assert!(dt >= 0.0, "The time-stepping length cannot be negative."); self.dt = dt; } /// Sets the inverse time-stepping length (i.e. the frequency). /// /// This automatically recompute `self.dt`. #[inline] pub fn set_inv_dt(&mut self, inv_dt: Real) { if inv_dt == 0.0 { self.dt = 0.0 } else { self.dt = 1.0 / inv_dt } } /// Convenience: `velocity_based_erp / dt` #[inline] pub(crate) fn velocity_based_erp_inv_dt(&self) -> Real { self.velocity_based_erp * self.inv_dt() } } impl Default for IntegrationParameters { fn default() -> Self { Self { dt: 1.0 / 60.0, min_ccd_dt: 1.0 / 60.0 / 100.0, // multithreading_enabled: true, erp: 0.2, joint_erp: 0.2, velocity_solve_fraction: 1.0, velocity_based_erp: 0.0, warmstart_coeff: 1.0, warmstart_correction_slope: 10.0, allowed_linear_error: 0.005, prediction_distance: 0.002, allowed_angular_error: 0.001, max_linear_correction: 0.2, max_angular_correction: 0.2, max_velocity_iterations: 4, max_position_iterations: 1, // FIXME: what is the optimal value for min_island_size? // It should not be too big so that we don't end up with // huge islands that don't fit in cache. // However we don't want it to be too small and end up with // tons of islands, reducing SIMD parallelism opportunities. min_island_size: 128, max_ccd_substeps: 1, } } }