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.

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 SoftBodyCellModel.COROTATIONAL and SoftBodyCellModel.NEO_HOOKEAN models): the SoftBodyCellModel.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 (SoftBody.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 property of a soft-body is a live view of its material (a SoftBodyMaterial): setting one of its fields changes the body directly. Assigning a whole SoftBodyMaterial to it replaces the material, and its copy method gives a detached copy:

# The jelly has elastic (corotational) cells: the plasticity of `VOLUME` cells has no effect.
jelly = world.soft_bodies[jelly_handle]
# A live view of the material: setting one of its fields changes the body.
material = jelly.material
# 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 = rp.SoftEdgePlasticFlow.COMPRESSION
# Every permanent deformation can be undone at once.
jelly.reset_plasticity()

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 (SoftBodyBuilder.edge_tear_resistance) or by cluster:

The optional thresholds of the material (tear_strain, tear_force, and min_piece) are disabled when they are set to None. As for the plasticity, they are set through the live view of the material of the soft-body:

material = world.soft_bodies[cloth_handle].material
# An edge tears past 40% of stretch, or past a force of 50 along its direction (`None`
# disables a threshold).
material.tear_strain = 0.4
material.tear_force = 50.0
# The load is smoothed over 0.1 second, so a single impact spike doesn't tear.
material.tear_smoothing = 0.1
# Undamaged interior elements are twice as tough: tears start from the surface.
material.interior_strength = 2.0
# A tear never splits off a piece smaller than 10 elements.
material.min_piece = 10

The tear resistance of the edges is given to the builder as a list of (edge index, resistance) pairs. It can also be changed after the insertion, for the edges and the cells with SoftBody.set_edge_tear_resistance and SoftBody.set_cell_tear_resistance, and for the clusters with SoftBody.set_cluster_tear_resistance:

# A perforation line: these edges tear at half the load of the others (1.0 restores the
# threshold of the material).
perforated = rp.SoftBody.rope((0.0, 6.0, -3.0), (3.0, 6.0, -3.0), 30).edge_tear_resistance(
    [(14, 0.5), (15, 0.5)]
)
perforated_handle = world.add_soft_body(perforated)
# The same, after the insertion.
cloth = world.soft_bodies[cloth_handle]
for edge in (30, 31, 32):
    cloth.set_edge_tear_resistance(edge, 0.5)
# Every element of the root cluster of the jelly (i.e., of the whole body) is twice as
# tough, and its first cell three times as tough.
jelly = world.soft_bodies[jelly_handle]
jelly.set_cluster_tear_resistance(0, 2.0)
jelly.set_cell_tear_resistance(0, 3.0)

A tear can also be requested explicitly, either edge by edge (SoftBody.tear_edge, tear_cell), or all at once along a set of edges and through a set of cells (PhysicsWorld.tear_soft_body). Finally, a body can be cut (PhysicsWorld.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:

PhysicsWorld.tear_soft_body and PhysicsWorld.cut_soft_body (or SoftBodySet.tear and SoftBodySet.cut when the sets are used directly) return a SoftBodyTearEvent, or None if the tear or the cut changed nothing:

• soft_body is the torn soft-body, and bodies() the soft-bodies it is now made of: the torn body alone if nothing was split off, or its pieces otherwise. The pieces property lists these pieces (empty if nothing was split off), the piece keeping the handle of the torn body first, each SoftBodyPiece giving its soft_body and its particles (i.e., their indices in the torn body).
• particle_destination(i) tells in which soft-body a particle of the torn body is now, and what its index is there, as a (handle, index) tuple (or None if the particle has no destination).
• torn_edges, torn_cells, and removed_edges give the particles of the elements involved in the change of topology as NumPy arrays. split_particles gives the particles the tear duplicated, as (copy, source) pairs, and inserted_particles the particles it inserted.
• clusters and moved_joints give the clusters the tear split, and the joints it moved from a cluster proxy to another.

A soft-body split off by a tear remembers the body it comes from (SoftBody.origin), and the torn body lists the ones split off it (SoftBody.pieces). Finally, SoftBody.topology_version 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.
world.soft_bodies[cloth_handle].tear_edge(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.
event = world.tear_soft_body(cloth_handle, [11, 12], [])
if event is not None:
    print(f"{len(event.torn_edges)} edges torn")
# Cut along a blade (a triangle), without removing material.
blade = ((-0.1, -10.0, -10.0), (-0.1, 10.0, 0.0), (-0.1, -10.0, 10.0))
event = world.cut_soft_body(cloth_handle, blade)
if event is not None:
    for piece in event.pieces:
        print(f"piece {piece.soft_body} has {len(piece.particles)} particles")
    # Where a particle of the torn body went.
    destination = event.particle_destination(n * n - 1)
    if destination is not None:
        body, index = destination
        print(f"particle {n * n - 1} is now particle {index} of {body}")
# The connectivity of the cloth changed: its render mesh must be rebuilt.
assert world.soft_bodies[cloth_handle].topology_version > 0

note

Tearing one edge with SoftBody.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 PhysicsWorld 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 SoftBodyCellModel.VOLUME model will only tear along its edges, and a material with a tear strain should be combined with the SoftBodyCellModel.COROTATIONAL or the SoftBodyCellModel.NEO_HOOKEAN cell model if you expect it to be torn apart.