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.

Example 2D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
let rigid_body = RigidBodyBuilder::dynamic()
    // Extra substeps run for the whole island component this body belongs to.
    .additional_solver_iterations(4)
    // Extra internal PGS iterations run per substep for that same component.
    .additional_pgs_iterations(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.
    .soft_ccd_prediction(0.5)
    // Let the body exceed the angular speed cap, e.g. for a wheel.
    .allow_fast_rotation(true)
    .build();

Example 3D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
let rigid_body = RigidBodyBuilder::dynamic()
    // Extra substeps run for the whole island component this body belongs to.
    .additional_solver_iterations(4)
    // Extra internal PGS iterations run per substep for that same component.
    .additional_pgs_iterations(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.
    .soft_ccd_prediction(0.5)
    // Let the body exceed the angular speed cap, e.g. for a wheel.
    .allow_fast_rotation(true)
    // Gyroscopic forces give more realistic behaviors, e.g. the precession of a spinning top.
    .gyroscopic_forces_enabled(true)
    .build();

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(),
));

Example 2D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
let solverBodyDesc = RAPIER.RigidBodyDesc.dynamic()
    // Extra substeps run for the whole island component this body belongs to.
    .setAdditionalSolverIterations(4)
    // 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.
    .setSoftCcdPrediction(0.5);
let solverBody = world.createRigidBody(solverBodyDesc);

Example 3D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
let solverBodyDesc = RAPIER.RigidBodyDesc.dynamic()
    // Extra substeps run for the whole island component this body belongs to.
    .setAdditionalSolverIterations(4)
    // 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.
    .setSoftCcdPrediction(0.5);
let solverBody = world.createRigidBody(solverBodyDesc);

These settings are given by the additionalSolverIterations, additionalPgsIterations, softCcdPrediction, and allowFastRotation fields of R3RigidBodyDesc. After the creation of the rigid-body, they can be modified with r3RigidBody_SetAdditionalSolverIterations, r3RigidBody_SetAdditionalPgsIterations, r3RigidBody_SetSoftCcdPrediction, and r3RigidBody_SetAllowFastRotation (and read with r3RigidBody_AdditionalSolverIterations, r3RigidBody_AdditionalPgsIterations, r3RigidBody_SoftCcdPrediction, and r3RigidBody_IsFastRotationAllowed).

Example 2D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
R2RigidBodyDesc rigid_body = r2DynamicRigidBodyDesc();
// Extra substeps run for the whole island component this body belongs to.
rigid_body.additionalSolverIterations = 4;
// Extra internal PGS iterations run per substep for that same component.
rigid_body.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.
rigid_body.softCcdPrediction = 0.5;
// Let the body exceed the angular speed cap, e.g. for a wheel.
rigid_body.allowFastRotation = 1;

Example 3D

/* Give a rigid-body more solver accuracy than the rest of the scene. */
R3RigidBodyDesc rigid_body = r3DynamicRigidBodyDesc();
// Extra substeps run for the whole island component this body belongs to.
rigid_body.additionalSolverIterations = 4;
// Extra internal PGS iterations run per substep for that same component.
rigid_body.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.
rigid_body.softCcdPrediction = 0.5;
// Let the body exceed the angular speed cap, e.g. for a wheel.
rigid_body.allowFastRotation = 1;
// Gyroscopic forces give more realistic behaviors, e.g. the precession of a spinning top.
rigid_body.gyroscopicForcesEnabled = 1;

These settings are given by the additional_solver_iterations, additional_pgs_iterations, soft_ccd_prediction, and allow_fast_rotation methods of the RigidBodyBuilder. After the creation of the rigid-body, they can be read and modified with the RigidBody properties of the same names.

# Give a rigid-body more solver accuracy than the rest of the scene.
rigid_body = (
    rp.RigidBody.dynamic()
    # Extra substeps run for the whole island component this body belongs to.
    .additional_solver_iterations(4)
    # Extra internal PGS iterations run per substep for that same component.
    .additional_pgs_iterations(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.
    .soft_ccd_prediction(0.5)
    # Let the body exceed the angular speed cap, e.g. for a wheel.
    .allow_fast_rotation(True)
    # Gyroscopic forces give more realistic behaviors, e.g. the precession of a spinning top.
    .gyroscopic_forces(True)
    .build()
)

note

In 3D, the gyroscopic forces of a rigid-body can be disabled as well. When enabled (the default), 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.

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.

note

In 3D, the gyroscopic forces of a rigid-body can be disabled as well by setting the gyroscopicForcesEnabled field of its R3RigidBodyDesc to 0, or with r3RigidBody_SetGyroscopicForcesEnabled after its creation. When enabled (the default), 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.

note

The gyroscopic forces of a rigid-body can be disabled as well with RigidBodyBuilder.gyroscopic_forces(False), or by setting its RigidBody.gyroscopic_forces_enabled property to False after its creation. When enabled (the default), 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.