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 (plasticYield) absorbs the strain in excess into its rest shape, at the rate of its plastic creep (plasticCreep, per second), up to a total permanent deformation of its plastic max (plasticMax). This flow preserves the volume of the cell, and an inverted cell never flows. Note that this only applies to the elastic cells (the R3_SOFT_CELL_COROTATIONAL and R3_SOFT_CELL_NEO_HOOKEAN models): the R3_SOFT_CELL_VOLUME cells never flow.
  • An edge strained past its edge plastic yield (edgePlasticYield compared to |length / rest_length - 1|) sees its rest length flow toward its current length at the rate of its edge plastic creep (edgePlasticCreep), up to a total permanent set of its edge plastic max (edgePlasticMax, as a fraction of its initial length). Its edge plastic flow (edgePlasticFlow, 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 (r3SoftBody_ResetPlasticity), 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 read with r3SoftBody_Material, which gives back a copy of the material of the body. That copy is modified, then applied with r3SoftBody_SetMaterial:

// The jelly has elastic (corotational) cells: the plasticity of volume cells has no effect.
R2SoftBodyMaterial plastic_material = r2SoftBody_Material(jelly);
// 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%.
plastic_material.plasticYield = 0.05;
plastic_material.plasticCreep = 20.0;
plastic_material.plasticMax = 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).
plastic_material.edgePlasticYield = 0.1;
plastic_material.edgePlasticCreep = 10.0;
plastic_material.edgePlasticMax = 0.5;
plastic_material.edgePlasticFlow = R2_SOFT_EDGE_PLASTIC_FLOW_COMPRESSION;
r2SoftBody_SetMaterial(jelly, &plastic_material);
// Every permanent deformation can be undone at once.
r2SoftBody_ResetPlasticity(jelly);

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 (tearStrain) 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 (tearForce) 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 (tearSmoothing) 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 (interiorStrength) 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 (maxTearsPerStep) 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 (minPiece) 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 (the edgeTearResistance field of R3SoftBodyDesc) or by cluster:

The optional thresholds of the material (tearStrain, tearForce, and minPiece) are only used when the enabled field of their R3OptionalReal or R3OptionalU32 is set. The tear resistance of the edges and of the clusters can also be changed after the insertion, with r3SoftBody_SetEdgeTearResistance and r3SoftBody_SetClusterTearResistance:

R2SoftBodyMaterial tear_material = r2SoftBody_Material(sheet);
// An edge tears past 40% of stretch, or past a force of 50 along its direction.
tear_material.tearStrain = (R2OptionalReal){1, 0.4};
tear_material.tearForce = (R2OptionalReal){1, 50.0};
// The load is smoothed over 0.1 second, so a single impact spike doesn't tear.
tear_material.tearSmoothing = 0.1;
// Undamaged interior elements are twice as tough: tears start from the surface.
tear_material.interiorStrength = 2.0;
// A tear never splits off a piece smaller than 10 elements.
tear_material.minPiece = (R2OptionalU32){1, 10};
r2SoftBody_SetMaterial(sheet, &tear_material);

A tear can also be requested explicitly, either edge by edge (r3SoftBody_TearEdge, r3SoftBody_TearCell), or all at once along a set of edges and through a set of cells (r3SoftBody_Tear). Finally, a body can be cut (r3CutSoftBody) 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 event returned by r3SoftBody_Tear and r3CutSoftBody is an owned R3SoftBodyTearEvent, to be freed with r3FreeSoftBodyTearEvent, or NULL if the tear or the cut changed nothing. It is read with the following functions:

  • r3SoftBodyTearEvent_SoftBody gives the torn soft-body, and r3SoftBodyTearEvent_Bodies the soft-bodies it is now made of: the torn body alone if nothing was split off, or its pieces otherwise, the piece keeping the handle of the torn body first (r3SoftBodyTearEvent_PieceCount gives their number). The particles of the i-th of them (i.e., their indices in the torn body) are given by r3SoftBodyTearEvent_PieceParticles.
  • r3SoftBodyTearEvent_TryParticleDestination tells in which soft-body a particle of the torn body is now, and what its index is there (r3SoftBodyTearEvent_ParticleDestination does the same, but reports the particles without any destination as an R3_NOT_FOUND error).
  • r3SoftBodyTearEvent_TornEdges, r3SoftBodyTearEvent_TornCells, r3SoftBodyTearEvent_RemovedEdges, r3SoftBodyTearEvent_SplitParticles, and r3SoftBodyTearEvent_InsertedParticles give the details of the change of topology, as flat arrays of particle indices.
  • r3SoftBodyTearEvent_Clusters and r3SoftBodyTearEvent_MovedJoints give the clusters the tear split, and the joints it moved from a cluster proxy to another.

The arrays are copied with the usual output-buffer protocol: each function returns the number of elements, and copies them into the given buffer only if its capacity is large enough (a NULL buffer with a capacity of zero gives that number first). Finally, r3SoftBody_TopologyVersion changes whenever the connectivity of the particles of a body changes, which is a convenient way of knowing when the render meshes must be rebuilt:

// Elements tear on their own past the material's thresholds; a tear can also be requested.
r2SoftBody_TearEdge(sheet, 10); // Applied at the end of the next step.
// Tear at once along edges and through cells; pieces the tear disconnects become soft
// bodies of their own. The event is NULL if nothing changed.
uint32_t torn_edges[] = {11, 12};
R2SoftBodyTearEvent *tear = r2SoftBody_Tear(sheet, torn_edges, 2, NULL, 0);
if (tear != NULL) {
    printf("%zu edges torn\n", r2SoftBodyTearEvent_TornEdges(tear, NULL, 0) / 2);
    r2FreeSoftBodyTearEvent(tear);
}
// Cut along a blade (a segment in 2D), without removing material.
R2Vector blade[2] = {{-3.0, -10.0}, {-3.0, 10.0}};
R2SoftBodyTearEvent *cut = r2CutSoftBody(sheet, blade);
if (cut != NULL) {
    // The soft-bodies the sheet is now made of, the one keeping its handle first.
    size_t num_pieces = r2SoftBodyTearEvent_PieceCount(cut);
    R2SoftBodyHandle *pieces = malloc(num_pieces * sizeof(R2SoftBodyHandle));
    r2SoftBodyTearEvent_Bodies(cut, pieces, num_pieces);
    for (size_t i = 0; i < num_pieces; i++) {
        size_t num_piece_particles = r2SoftBodyTearEvent_PieceParticles(cut, i, NULL, 0);
        printf("piece %u has %zu particles\n", pieces[i].index, num_piece_particles);
    }
    free(pieces);
    // Where a particle of the torn body went.
    R2OptionalParticleDestination destination = r2SoftBodyTearEvent_TryParticleDestination(cut, n * n - 1);
    if (destination.found) {
        printf("particle %u is now particle %u of %u\n", n * n - 1, destination.index,
               destination.body.index);
    }
    r2FreeSoftBodyTearEvent(cut);
}
note

Tearing one edge with r3SoftBody_TearEdge 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 world (r3SoftBody_Tear and r3CutSoftBody) 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 R3_SOFT_CELL_VOLUME model will only tear along its edges, and a material with a tear strain should be combined with the R3_SOFT_CELL_COROTATIONAL or the R3_SOFT_CELL_NEO_HOOKEAN cell model if you expect it to be torn apart.