Skip to main content

soft_body_tearing

A soft-body can deform permanently in two ways:

  • Plasticity changes the rest shape of the body, without any change of its topology: a metal sheet folding on impact, a piece of clay being modeled, the chassis of a car denting.
  • Tearing changes its topology: pieces of the body physically disconnect from each other, e.g., a piece of fabric torn in two, or a jelly sliced by a blade.

Plasticity and tearing

Both are supported by the constraints solver and by the FEM solver. Note that with the constraints solver, the quality of the plastic deformations follows the convergence of the solver: more iterations result in more convincing permanent deformations.

Plasticity​

Plasticity is configured by the material of the body, separately for its cells and for its edges:

  • A cell strained past its plastic yield (plastic_yield) absorbs the strain in excess into its rest shape, at the rate of its plastic creep (plastic_creep, per second), up to a total permanent deformation of its plastic max (plastic_max). This flow preserves the volume of the cell, and an inverted cell never flows. Note that this only applies to the elastic cells (the Corotational and NeoHookean models): the Volume cells never flow.
  • An edge strained past its edge plastic yield (edge_plastic_yield compared to |length / rest_length - 1|) sees its rest length flow toward its current length at the rate of its edge plastic creep (edge_plastic_creep), up to a total permanent set of its edge plastic max (edge_plastic_max, as a fraction of its initial length). Its edge plastic flow (edge_plastic_flow, a SoftEdgePlasticFlow) selects whether that happens when it is squeezed, when it is stretched, or both.

A plastic deformation can be undone at any time (RapierSoftBody::reset_plasticity), the particles springing back elastically from there. Note that the tear thresholds of the edges are always measured on their initial length, not on their plastic one:

The material is modified through the SoftBodyMaterial component of the soft-body entity:

fn configure_plasticity(
    mut context: WriteRapierContext,
    jelly: Single<(Entity, &mut SoftBodyMaterial), With<Jelly>>,
) -> Result {
    // The jelly has elastic (corotational) cells: the plasticity of `Volume` cells has no effect.
    let (entity, mut material) = jelly.into_inner();
    // Cells: the rest shape flows toward the current one past 5% strain, at a rate of 20 per
    // second, up to a total permanent deformation of 50%.
    material.plastic_yield = 0.05;
    material.plastic_creep = 20.0;
    material.plastic_max = 0.5;
    // Edges: the rest length flows past 10% strain, up to half the initial length, but only
    // when squeezed (a dent stays, a stretch springs back).
    material.edge_plastic_yield = 0.1;
    material.edge_plastic_creep = 10.0;
    material.edge_plastic_max = 0.5;
    material.edge_plastic_flow = SoftEdgePlasticFlow::Compression;
    // Every permanent deformation can be undone at once.
    if let Some(soft_body) = context.single_mut()?.soft_body_mut(entity) {
        soft_body.reset_plasticity();
    }
    Ok(())
}

Tearing​

Tearing is configured by the material of the body as well. An element tears at the end of the timestep during which its load goes beyond one of the two thresholds of the material:

  • The tear strain (tear_strain) applies to the edges (a fraction of their initial rest length) and to the elastic cells (their largest tensile strain). Note that volume cells never tear.
  • The tear force (tear_force) applies to the edges only: an edge tears if its force along its direction exceeds it.

The other settings of the material shape how a tear propagates:

  • The tear smoothing (tear_smoothing) is the time constant (in seconds) over which the load of an element is smoothed before being tested, so that a single impact spike doesn't tear.
  • The interior strength (interior_strength) makes the undamaged interior elements (without any particle on the surface or on an earlier tear) that many times tougher, so that tears start from the surface or from an existing damage, and run inward.
  • The max tears per step (max_tears_per_step) bounds how many edges may tear during one step, the most loaded going first, which paces the cracks of a taut sheet (an edge loaded past twice its threshold always tears).
  • The min piece (min_piece) is the smallest piece (in elements) a tear may split off, any tear leaving a smaller piece waiting until it doesn't.

Individual edges can be made tougher (or weaker, e.g., a perforation line) with their tear resistance, given to the builder (edge_tear_resistance) or by cluster:

fn configure_tearing(mut commands: Commands, sheet: Single<Entity, With<Sheet>>) {
    commands
        .entity(*sheet)
        .insert(SoftBodyMaterial(RapierSoftBodyMaterial {
            // An edge tears past 40% of stretch, or past a force of 50 along its direction.
            tear_strain: Some(0.4),
            tear_force: Some(50.0),
            // The load is smoothed over 0.1 second, so a single impact spike doesn't tear.
            tear_smoothing: 0.1,
            // Undamaged interior elements are twice as tough: tears start from the surface.
            interior_strength: 2.0,
            // A tear never splits off a piece smaller than 10 elements.
            min_piece: Some(10),
            ..RapierSoftBodyMaterial::uniform(SpringCoefficients::new(30.0, 1.0))
        }));
}

A tear can also be requested explicitly, either edge by edge (RapierSoftBody::tear_edge, tear_cell), or all at once along a set of edges and through a set of cells (RapierContextMut::tear_soft_body). Finally, a body can be cut (RapierContextMut::cut_soft_body) along a blade, i.e., a segment in 2D or a triangle in 3D, which is the most convenient way of slicing a body with the weapon of a player. Note that the cuts ignore the min piece threshold.

Tearing and cutting lose no material: the particles are duplicated along the tear instead of being removed, so the area (2D) or the volume (3D) of the body is preserved. The pieces a tear disconnects become soft-bodies of their own, which keep the material and the settings of the body they come from, the deformable meshes and the joints following the pieces they were attached to. Therefore the particles of the torn body are renumbered, and the returned event tells where each of them went:

The largest piece keeps the torn soft-body and its entity, whereas a new entity is spawned for each other piece. That entity receives a clone of the components of the torn entity (its material, its mesh synchronization, its render components, your own components, etc.) during the next writeback of the physics state, except for the components referring to the particles by index (SoftBodyPinnedParticles, SoftBodyKinematicTargets, SoftBodyAttachments, SoftBodyExternalForce, and SoftBodyExternalImpulse): these are remapped to the renumbered particles, the entries of the particles moved to a piece being moved to the entity of that piece. The particles pinned by the builder of the SoftBody component (restored when the SoftBodyPinnedParticles component is removed) are remapped the same way. Similarly, the cluster entities follow the pieces holding their particles, and a new cluster entity is spawned for each piece of a split cluster that is given a proxy of its own. That entity inherits the SoftBodyClusterPinned, SoftBodyClusterKinematicTarget (shifted so that the particles keep their targets), SoftBodyClusterShapeMatching, and SoftBodyClusterMaterial components of the entity of the split cluster.

The pieces of the tears generated by the simulation get their entities during the writeback of the physics state, whereas tear_soft_body and cut_soft_body spawn the entities of the pieces right away with the Commands they are given. These are returned in a SoftBodyTearResult (the first piece being the torn entity itself), next to the event of Rapier (its raw field) which identifies the pieces by their handle. Note however that these entities only receive their components during the next writeback, when the SoftBodyTearEvent message described in the next section is sent (and the entities of the split clusters are only spawned then):

fn tear_sheet(
    mut commands: Commands,
    mut context: WriteRapierContext,
    sheet: Single<Entity, With<Sheet>>,
) -> Result {
    let mut context = context.single_mut()?;
    // Elements tear on their own past the material's thresholds; a tear can also be requested.
    if let Some(soft_body) = context.soft_body_mut(*sheet) {
        soft_body.tear_edge(10); // Applied at the end of the next step.
    }
    // Tear at once along edges and through cells. The pieces the tear disconnects become soft
    // bodies of their own, which entities are spawned right away with `commands`.
    if let Some(tear) = context.tear_soft_body(&mut commands, *sheet, &[11, 12], &[]) {
        println!("{} edges torn", tear.raw.torn_edges.len());
    }
    // Cut along a blade (a world-space segment in 2D), without removing material.
    let blade = [Vec2::new(-3.0, -10.0), Vec2::new(-3.0, 10.0)];
    if let Some(tear) = context.cut_soft_body(&mut commands, *sheet, &blade) {
        // The entities of the pieces (the first one being the torn entity) are known right away,
        // but they only get their components during the next writeback of the physics state.
        for (entity, piece) in tear.pieces.iter().zip(&tear.raw.pieces) {
            println!("piece {entity} has {} particles", piece.particles.len());
        }
    }
    Ok(())
}
note

Tearing one edge with RapierSoftBody::tear_edge only marks it: the tear is applied at the end of the next step, together with the tears the simulation generates itself. The methods of the RapierContextMut tear and cut immediately, which is why they are the ones giving back an event.

warning

Volume cells never tear. Therefore a body which cells use the Volume model will only tear along its edges, and a material with a tear strain should be combined with the Corotational or the NeoHookean cell model if you expect it to be torn apart.