rigid_body_solver_settings

The accuracy of the constraints solver is configured for the whole world by the integration parameters. However, in some cases, part of the simulation might need more fine-grained control. For example, an articulated robot, or a stack involving large mass ratios, might require more solver iterations. This is why a rigid-body can ask for additional solver iterations (either substeps, or internal steps) resulting in the island it belongs to (the bodies it is connected to by contacts and joints) to run with a higher accuracy without hurting the performances of other islands.

Two other settings affect how a rigid-body is integrated. The soft-CCD prediction distance makes the body generate predictive contacts ahead of its own path, which is a cheaper alternative to CCD for the objects that are thin or moderately fast (large values impact the performances badly by increasing significantly the number of collision pairs). Finally, the fast-rotation flag lets the body exceed the angular speed cap, which is enabled by default to keep CCD reliable.

These settings are given by the AdditionalSolverIterations, AdditionalPgsIterations, SoftCcd, and AllowFastRotation components. Removing them restores the default behavior.

Example 2D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
commands.spawn((
    RigidBody::Dynamic,
    // Extra substeps run for the whole island this body belongs to.
    AdditionalSolverIterations(4),
    // Extra internal PGS iterations run per substep for that same island.
    AdditionalPgsIterations(2),
    // Predictive contacts generated up to that distance ahead of the body's path: a cheaper
    // alternative to CCD for slow-but-thin or moderately fast objects.
    SoftCcd { prediction: 0.5 },
    // Let the body exceed the angular speed cap, e.g. for a wheel.
    AllowFastRotation,
));

Example 3D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
commands.spawn((
    RigidBody::Dynamic,
    // Extra substeps run for the whole island this body belongs to.
    AdditionalSolverIterations(4),
    // Extra internal PGS iterations run per substep for that same island.
    AdditionalPgsIterations(2),
    // Predictive contacts generated up to that distance ahead of the body's path: a cheaper
    // alternative to CCD for slow-but-thin or moderately fast objects.
    SoftCcd { prediction: 0.5 },
    // Let the body exceed the angular speed cap, e.g. for a wheel.
    AllowFastRotation,
    // Gyroscopic forces give more realistic behaviors, e.g. the precession of a spinning top.
    // Default: enabled (even without this component).
    GyroscopicForces::enabled(),
));

note

In 3D, the gyroscopic forces of a rigid-body can be disabled as well by giving it the GyroscopicForces::disabled() component. When enabled (the default, even without this component), they give the more realistic behaviors of a spinning solid, e.g., the precession of a spinning top or the Dzhanibekov effect. Disabling them is only recommended if they represent a measurable overhead in your simulation.