Skip to main content

soft_body_settings

A few settings are shared by every soft-body of the world. They are part of the integration parameters (the integration_parameters.soft_bodies field of the RapierContextSimulation component) (the softBodies field of R3IntegrationParameters) (the soft_bodies property of IntegrationParameters, a SoftBodiesSettings), so they can be changed between two steps:

  • The re-sweep strain (resweep_strainsoftBodiesResweepStrainr3SoftBodiesSetResweepStrainresweep_strain) is the strain beyond which a constraint is solved once more after the contacts of every substep. This is what keeps a light body buried under heavier ones from being torn apart by them.
  • The maximum number of extra substeps (max_extra_substepssoftBodiesMaxExtraSubstepsr3SoftBodiesSetMaxExtraSubstepsmax_extra_substeps) is the number of substeps a soft-body is allowed to ask for while it is hit fast. Those substeps bound the motion of its particles, and the motion of the rigid-bodies approaching them, by about one particle radius per substep. Giving zero disables them.
  • The contact stiffening (contact_stiffeningsoftBodiesContactStiffeningr3SoftBodiesSetContactStiffeningcontact_stiffening) multiplies the natural frequencies of the contacts involving a soft-body. Those contacts run stiffer than the rigid ones because the mass behind one contact is the mass of a few particles, and not the mass of the whole body.

In addition, the detection of the penetrations and of the tangles, as well as the way the bodies recover from them, are configured by the recovery settings (recovery, a SoftRecoverySettingssoftBodiesRecovery, a SoftRecoverySettingsrecovery, an R3SoftRecoverySettingsrecovery, a SoftRecoverySettings), where every mechanism can be switched off individually (see the contacts section for the ones to look at first). The tuning of the linear solves of the FEM solver lives there as well (fem, a SoftFemParametersthe softBodiesFem* parametersfem, an R3SoftFemParametersfem, a SoftFemParameters):

// Settings shared by every soft body of the world.
let settings = &mut world.integration_parameters.soft_bodies;
// Strain beyond which a constraint is re-solved after the contacts of every substep.
// Default: 0.75
settings.resweep_strain = 0.75;
// Extra substeps a soft body requests while it is hit fast; 0 disables them.
// Default: 4
settings.max_extra_substeps = 4;
// Stiffening of the soft-body contacts relative to the rigid ones.
// Default: 4.0
settings.contact_stiffening = 4.0;
// The tangle detection and recovery stack can be switched off mechanism by mechanism.
settings.recovery.crossing_repulsion = true;

Those settings are plain fields of the integration parameters of the world. Note that softBodiesRecovery gives back a copy of the recovery settings, which is assigned back to the integration parameters to apply it:

// Settings shared by every soft body of the world.
// Strain beyond which a constraint is re-solved after the contacts of every substep.
// Default: 0.75
world.integrationParameters.softBodiesResweepStrain = 0.75;
// Extra substeps a soft body requests while it is hit fast; 0 disables them.
// Default: 4
world.integrationParameters.softBodiesMaxExtraSubsteps = 4;
// Stiffening of the soft-body contacts relative to the rigid ones.
// Default: 4.0
world.integrationParameters.softBodiesContactStiffening = 4.0;
// The tangle detection and recovery stack can be switched off mechanism by mechanism; the
// getter gives back a copy, so the settings are assigned back after being changed.
let recovery = world.integrationParameters.softBodiesRecovery;
recovery.crossingRepulsion = true;
world.integrationParameters.softBodiesRecovery = recovery;
 
fn configure_soft_bodies(
    mut simulation: Single<&mut RapierContextSimulation, With<DefaultRapierContext>>,
) {
    // Settings shared by every soft-body of the physics context.
    let settings = &mut simulation.integration_parameters.soft_bodies;
    // Strain beyond which a constraint is re-solved after the contacts of every substep.
    // Default: 0.75
    settings.resweep_strain = 0.75;
    // Extra substeps a soft-body requests while it is hit fast; 0 disables them.
    // Default: 4
    settings.max_extra_substeps = 4;
    // Stiffening of the soft-body contacts relative to the rigid ones.
    // Default: 4.0
    settings.contact_stiffening = 4.0;
    // The tangle detection and recovery stack can be switched off mechanism by mechanism.
    settings.recovery.crossing_repulsion = true;
}

Each of these settings has its own getter and setter, named after its field: e.g., r3SoftBodiesResweepStrain and r3SoftBodiesSetResweepStrain, r3RecoveryCrossingRepulsion and r3RecoverySetCrossingRepulsion, or r3FemLinearTolerance and r3FemSetLinearTolerance. All of them can also be read at once with r3IntegrationParameters, which returns a copy of the integration parameters of the world: that copy is modified, then written back with r3SetIntegrationParameters. Note that the fem field, as well as the r3Fem* functions, only exist when the library is built with the fem feature:

// Settings shared by every soft-body of the world.
// Strain beyond which a constraint is re-solved after the contacts of every substep.
// Default: 0.75
r2SoftBodiesSetResweepStrain(world, 0.75);
// Extra substeps a soft-body requests while it is hit fast; 0 disables them.
// Default: 4
r2SoftBodiesSetMaxExtraSubsteps(world, 4);
// Stiffening of the soft-body contacts relative to the rigid ones.
// Default: 4.0
r2SoftBodiesSetContactStiffening(world, 4.0);
// The tangle detection and recovery stack can be switched off mechanism by mechanism.
r2RecoverySetCrossingRepulsion(world, 1);
// The settings can also be read all at once (as a copy), modified, and written back.
R2IntegrationParameters params = r2IntegrationParameters(world);
params.softBodies.recovery.selfStandDown = 1;
r2SetIntegrationParameters(world, &params);

The soft_bodies property of the integration parameters of the world is a live view of the settings, and so are its recovery and fem properties: setting one of their fields changes the world directly. Assigning a whole SoftBodiesSettings replaces them all, and their copy method gives a detached copy, e.g., to keep them aside before an experiment:

# Settings shared by every soft body of the world (a live view of the integration parameters).
settings = world.integration_parameters.soft_bodies
# Strain beyond which a constraint is re-solved after the contacts of every substep.
# Default: 0.75
settings.resweep_strain = 0.75
# Extra substeps a soft body requests while it is hit fast; 0 disables them.
# Default: 4
settings.max_extra_substeps = 4
# Stiffening of the soft-body contacts relative to the rigid ones.
# Default: 4.0
settings.contact_stiffening = 4.0
# The tangle detection and recovery stack can be switched off mechanism by mechanism.
settings.recovery.crossing_repulsion = True