Integration parameters

Various aspects of the physics simulation can be tuned by modifying the fields of the IntegrationParameters. Most of these parameters are somewhat advanced and should not be modified unless you know their meaning and effect. Several of them are about balancing efficiency and accuracy. They are given default values that work well in the context of video-games or animations. For more realistic simulations you may want to change those parameters to favor accuracy over performance.

dt

The timestep length used for each update of the physics engine. This is the time by which the physics simulation will be advanced. The default is $1 / 60$ seconds. This typically corresponds to a refresh rate of 60Hz. Smaller timesteps yield better accuracy. Large timesteps increase the negative effect of some approximations (linearization of various parts of the equations of motion) and may result in missed collisions (because of collisions that may occur in-between timesteps for fast-moving objects).

min_ccd_dt

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 and rigid-bodies remaining stuck in place.

erp

The Error Reduction Parameter in $[0, 1]$ is the proportion of the positional error to be corrected at each time step. An ERP set to 0 means that no penetration will be corrected, and an ERP set to 1 means all the penetrations between two solids will be corrected in a single timestep. While setting 1 may sound appealing, this will cause objects to jitter in practice because penetration correction may add or remove kinetic energy to the system.

joint_erp

This is the same as

warmstart_coeff

Each cached impulse are multiplied by this coefficient in $[0, 1]$ when they are re-used to initialize the constraints solver. The default is $1.0$. A high warm-start coefficient causes faster convergence but may add kinetic energy to the system (and cause jitters) for fast objects subject to non-elastic contacts. However $1.0$ still remains a good choice for practical applications as it allows convergence of the constraints solver even if the maximum number of solver iterations is small.

allowed_linear_error

Amount of penetration the engine won't attempt to fix. The default is $0.001$ meters. Setting this to 0 would cause jittering because contacts would start and stop being active at a high frequency for resting objects (due to inevitable numerical errors). A value too large would cause noticeable penetrations.

max_linear_correction

Maximum translation-based penetration correction performed by the non-linear position solver during a single iteration. The default is $100.0$. A value too small would prevent penetrations from being corrected fast enough while a large value could cause jittering due to the solver overshooting (i.e. applying a correction that is too large).

max_velocity_iterations

Maximum number of iterations performed by the velocity constraints solver for impulse computation. More iterations imply greater accuracy at the cost of increased computation times.

max_position_iterations

Maximum number of iterations performed by the position-based constraints solver for penetration correction. More iterations imply greater accuracy at the cost of increased computation times.