Skip to main content

Soft-bodies

For a high-level overview of the methods behind our soft-body implementation, see our blog-post.

Rigid-bodies can't deform in any way, which is precisely what makes them cheap and easy to control. Soft-bodies, aka. deformable bodies, are made for everything that must bend, stretch, or squash: ropes, cloth, jelly, balloons, the chassis of a car denting on impact, etc. They live in the same world as the rigid-bodies and the colliders, and interact with all the other features of the engine with little to no restriction:

info

In Bevy, a soft-body is an entity with a SoftBody component, and most of its properties are controlled by components too. The conventions linking the entity to the soft-body (its transform, the rigid-bodies and the colliders it stands for, etc.) are detailed in the soft-bodies and entities section. Note that the FEM solver requires the fem feature of bevy_rapier.

Definition of a soft-body​

A rigid-body is a single moving frame: the position and the velocity of any of its points follow from one translation and one rotation. This is precisely what a deformable body can't be, because its parts must be able to move (somewhat) independently of each other. Instead, a soft-body is made of particles, aka. mass points, i.e., points without any orientation, each having 2 degrees of freedom in 2D and 3 in 3D. The more particles a body is made of, the more detailed its deformations can be, and the more expensive it is to simulate.

The particles are kept together by a lattice made of up to three kinds of elements:

  • The particles are the only mandatory element, i.e., the positions the SoftBodyBuilder (wrapped by the SoftBody component) is built from. They carry the mass and the velocity of the body.
  • The edges (edges) connect two particles. The structural edges resist the stretching (and the compression) of the body, whereas the bending edges (bend_edges) and the dihedral constraints (dihedrals, 3D) resist its bending.
  • The cells (cells) connect three particles in 2D (triangles) and four in 3D (tetrahedra). They resist the deformation of the area (2D) or of the volume (3D) they cover.

Soft-body lattice: particles, edges, and cells

Two more concepts describe how the body interacts with the rest of the world. The surface (surface) is the boundary of the body (segments in 2D, triangles in 3D): this is what the body collides with, and what the preservation of its volume integrates over. A body without any surface, e.g., a cloud of particles, collides with nothing at all, unless it is given wire segments (wire), in which case it collides as a polyline, which is what a 3D rope does. Finally, a skin (skin) is a mesh which vertices follow the cells without being particles themselves, as detailed in the skinning section.

Every element can be given manually to the soft-body builder, but the constructors of the next section build the lattices of the most common shapes directly. Note that the elements a body is made of decide which of the cohesion models can hold it together.

Creation and insertion​

A soft-body is described by a SoftBodyBuilder (wrapped by the SoftBody component), which constructors build the lattice of the most common shapes:

ConstructorDimensionLattice
rope2D, 3DStructural and bending edges between the particles of a line.
cloth, cloth_anisotropic, cloth_tube3DStructural, shear and bending edges, with a triangle surface.
grid2DTriangle cells filling a rectangle.
cuboid3DTetrahedral cells filling a box.
polygon, disk2DA closed boundary preserving its area.
sphere3DA closed surface preserving its volume, with dihedral bending constraints.
trimesh, polyline2D, 3D (trimesh), 2D (polyline)The vertices and edges of a mesh, held by shape matching.
volumetric2D, 3DCells filling a closed mesh.

The SoftBody component provides shortcuts for most of these constructors (SoftBody::rope, SoftBody::cloth, SoftBody::cuboid, SoftBody::grid, SoftBody::volumetric, etc.), which positions are expressed in the local frame of the entity: the cuboid, sphere, grid, and disk shortcuts are centered at its origin. The other constructors are used with SoftBody::new(SoftBodyBuilder::...), and the methods of the builder are chained with SoftBody::map, e.g., SoftBody::rope(a, b, 20).map(|b| b.particle_mass(0.1)).

The volumetric constructor is the one to use for an arbitrary solid: it fills a closed mesh (segments in 2D, triangles in 3D, oriented outward) with cells of about the requested size. The interior of the mesh is triangulated by Delaunay refinement in 2D, whereas in 3D every cell of a lattice the mesh reaches is kept whole: the result contains the mesh instead of following it exactly, and its boundary is as blocky as its cells. The meshing parameters are spelled out by volumetric_with: the size of the cells, how much the cover is smoothed and subdivided around the boundary in 3D, i.e., how closely it follows the mesh, and whether the surface alone is covered, leaving the interior empty.

// Fill a closed, counter-clockwise polyline with triangle cells of about 0.2 in size.
let vertices = vec![
    Vec2::new(-0.5, -0.25),
    Vec2::new(0.5, -0.25),
    Vec2::new(0.5, 0.25),
    Vec2::new(-0.5, 0.25),
];
let indices = vec![[0, 1], [1, 2], [2, 3], [3, 0]];
let block = SoftBody::volumetric(&vertices, &indices, 0.2)
    .expect("the polyline must be closed and enclose some area");
commands.spawn((Transform::from_xyz(-3.0, 1.0, 0.0), block));

The builder allows the definition of everything else that is specific to one soft-body: the particles held in place (the pinned particles, pinned_particles), the softness of its constraints (softness), the mass of its particles (one mass for every particle with particle_mass, a total mass for the whole body with mass, or one mass per particle with masses), their radius (particle_radius), the collider its surface is made of, and whether that surface is allowed to collide with itself (self_contacts). The particles can also be given a linear damping (linear_damping), a gravity scale (gravity_scale), a dominance group (SoftBodyParticleSettings::dominance_group), and be allowed to sleep or not (can_sleep), exactly like a rigid-body. Inserting the soft-body into the world (i.e., spawning an entity with the SoftBody component) will automatically create the rigid-body standing for it (its root body), as well as the colliders covering its surface:

// A ground.
commands.spawn((
    Transform::from_xyz(0.0, -0.1, 0.0),
    Collider::cuboid(10.0, 0.1),
));

// A rope of 20 particles between two points (in the local frame of the entity).
let _ = SoftBody::rope(Vec2::ZERO, Vec2::new(2.0, 0.0), 20);
// A grid of `nx` by `ny` particles filled with triangle cells, centered on the entity.
let _ = SoftBody::grid(Vec2::new(1.0, 1.0), 6, 6);
// A disk: a ring of particles holding its area (a pressurized blob), centered on the entity.
let _ = SoftBody::disk(0.8, 24);
// A closed polygon of particles holding its area.
let _ = SoftBody::polygon(vec![
    Vec2::new(0.0, 0.0),
    Vec2::new(2.0, 0.0),
    Vec2::new(2.0, 2.0),
    Vec2::new(0.0, 2.0),
]);
// Any constructor of the Rapier builder can be used too.
let _ = SoftBody::new(SoftBodyBuilder::grid(Vec2::ZERO, Vec2::new(1.0, 0.5), 6, 3));

let n = 20;
commands.spawn((
    Sheet,
    // The particles are placed by the transform of the entity when the soft-body is
    // created. Then, the entity follows the center of mass of the particles.
    Transform::from_xyz(-3.0, 3.0, 0.0),
    SoftBody::grid(Vec2::new(1.0, 1.0), n, n).map(|builder| {
        // Particles held in place.
        builder
            .pinned_particles([0, (n - 1) as u32])
            // A uniform softness (frequency in Hz, damping ratio) for every constraint.
            .softness(SpringCoefficients::new(30.0, 1.0))
            // The mass of each particle.
            // Default: 1.0
            .particle_mass(0.05)
            // The thickness of the particles, for collisions.
            // Default: 0.01
            .particle_radius(0.05)
            // Whether the body may fall asleep.
            // Default: true
            .can_sleep(true)
    }),
    // The collider components of the entity configure the colliders of its surface.
    Friction::coefficient(0.8),
    // Render the soft-body with a mesh kept in sync with its particles.
    SoftBodyMeshSync::default(),
    MeshMaterial2d(materials.add(Color::srgb(0.8, 0.2, 0.2))),
));
info

The collider given to SoftBodyBuilder::surface_collider is only a template: its shape is replaced by the deformable surface of the soft-body, and its density is ignored, whereas all its other properties are kept. Therefore this is where the friction, the collision groups, or the active events of the soft-body must be set. A body that should only collide through colliders of your own can be built without any default one (no_surface_collider). The collider components of the soft-body entity (Friction, Restitution, CollisionGroups, ActiveEvents, Sensor, etc.) override the properties of that template, exactly like for a Collider: their later modifications are applied to the colliders of the surface as well, and removing one of them restores the value of the template (the particle radius for the ContactSkin).

tip

Two builders can be merged into a single soft-body with append, and their pieces sewn together with additional edges (add_edges), which rest length is the distance their particles have when they are added. This is, e.g., how the sleeves of a shirt are attached to its body.

Soft-bodies and entities​

A soft-body is created by inserting a SoftBody component on an entity. This component only wraps the Rapier SoftBodyBuilder of the body, and it is read only once: the plugin creates the Rapier soft-body during the next physics update, then inserts its RapierSoftBodyHandle on the entity, as well as a SoftBodyState component updated after each step with the (mass-weighted) center of mass of the body, whether it is sleeping, its number of particles, etc. Therefore modifying the SoftBody component afterwards has no effect: the body is controlled at runtime by the other soft-body components (SoftBodyMaterial, SoftBodyPinnedParticles, etc.) described in the next sections. Adding the SoftBodyDisabled component disables the soft-body until it is removed, and despawning the entity (or removing its SoftBody component) removes the soft-body from the simulation.

The positions of the particles given to the builder are expressed in the local frame of the entity: they are transformed by its GlobalTransform when the soft-body is created. After that, the particles live in world-space, and the plugin drives the Transform of the entity: it follows the pose of the root body of the soft-body, i.e., its translation follows the centroid of the free particles, and its rotation is the one best fitting the particles onto their rest shape (the identity when the soft-body is created), whereas its scale is kept. The colliders of the children of the soft-body entity are attached to the root body, so these children follow the body as a whole. Whatever must follow a specific part of the body is better attached to a cluster entity.

The soft-body entity also stands for the rigid-body and the colliders the engine creates for it:

  • It is mapped to the root body of the soft-body, so it can be used like any rigid-body entity by the impulse joints.
  • The colliders of its surface carry the bits of the entity in their user-data, so the collision events, the contact pairs, and the scene queries report the soft-body entity itself as the collider entity.
  • Its collider components (Friction, Restitution, CollisionGroups, SolverGroups, ActiveEvents, ActiveHooks, ActiveCollisionTypes, ContactForceEventThreshold, ContactSkin, and Sensor) configure the colliders of its surface exactly like for a Collider: they are applied when the soft-body is created and whenever they change, and removing one of them restores the value of the collider template of the builder. These colliders are given by RapierRigidBodySet::soft_body_colliders.

Finally, the Rapier soft-bodies are stored in the soft_bodies set of the RapierRigidBodySet component of the physics context, next to the rigid-bodies. The Rapier soft-body type is re-exported as RapierSoftBody (and its material as RapierSoftBodyMaterial) to avoid any confusion with the components. They are accessed with the ReadRapierContext and WriteRapierContext system parameters, which provide shortcuts for the most common operations: soft_body gives the Rapier soft-body of an entity, soft_body_entity gives the entity of a soft-body handle, soft_body_particle_positions and soft_body_center_of_mass read its state, and soft_body_mut gives mutable access to the soft-body of an entity:

fn read_soft_bodies(context: ReadRapierContext, sheet: Single<Entity, With<Sheet>>) -> Result {
    let context = context.single()?;
    // The Rapier soft-bodies live in the `RapierRigidBodySet` of the context, together with the
    // map from their entity to their handle (also given by their `RapierSoftBodyHandle`).
    let Some(handle) = context.rigidbody_set.entity2soft_body().get(&*sheet) else {
        return Ok(()); // Not created yet.
    };
    let soft_body: &RapierSoftBody = &context.rigidbody_set.soft_bodies[*handle];
    // Shortcuts are provided for the most common operations.
    assert_eq!(context.soft_body_entity(*handle), Some(*sheet));
    assert_eq!(
        context.soft_body_particle_positions(*sheet).unwrap().len(),
        soft_body.num_particles()
    );
    let _center = context.soft_body_center_of_mass(*sheet);
    // The colliders of its surface, configured by its collider components.
    let surface_colliders = context
        .rigidbody_set
        .soft_body_colliders(&context.colliders.colliders, *sheet)
        .unwrap_or_default();
    for handle in surface_colliders {
        let _friction = context.colliders.colliders[handle].friction();
    }
    Ok(())
}
warning

The properties covered by a component should be modified through that component rather than through soft_body_mut. The components are applied again whenever they change, so, e.g., a material set with RapierSoftBody::set_material is replaced by the SoftBodyMaterial of the entity the next time this component is modified.

info

The SoftBodyMeshSync component (from the to-bevy-mesh feature, enabled by default) renders the soft-body with a mesh kept in sync with its particles. The plugin generates the mesh and inserts it as a Mesh3d (3D) or Mesh2d (2D) component, updates its vertices after each step, and rebuilds it whenever the topology of the body changes, e.g., after a tear. Its vertices are expressed in the frame of the Transform of the entity, and the material must be added by you, as shown in the creation example. In 3D, the mesh is the skin of the body if it has one, else its surface (or its boundary triangles), or a line list of its edges for a body without any surface, e.g., a rope. In 2D, it is made of its cells, or of its boundary segments (or of its edges). The meshes of the deformable colliders bound to the body are never part of it.

Keeping the body together​

Rapier supports three ways of holding the particles of a soft-body together: shape matching, constraints, and the Finite Elements Method (FEM). They can be combined, e.g., shape matching on top of edge constraints. Note that shape matching works on the particles alone, whereas the constraints need edges or cells, and the FEM solver needs cells.

Shape matching​

Shape matching doesn't need any element. At each timestep, the rest shape of the body is placed where it best fits its current shape, i.e., both shapes are given the same center of mass, and the rest shape is given the rotation bringing its particles the closest to the current ones. Each particle is then pulled toward its twin in that matched rest shape by a spring:

Shape-matching steps

This is cheap, and a body always recovers its original shape whatever the deformation it went through. On the other hand, the particles don't interact with their neighbors: pushing on one particle doesn't pull the ones around it, which makes the deformations feel very local. Shape matching is enabled by SoftBodyBuilder::shape_matching, and the strength of its springs is the shape matching softness (shape_matching_softness) of the material:

// A cloud of particles without any element: shape matching alone pulls them back toward
// their rest shape, placed where it best fits the current one.
let points: Vec<Vec2> = (0..9)
    .map(|i| Vec2::new((i % 3) as f32, (i / 3) as f32) * 0.3)
    .collect();
commands.spawn((
    Transform::from_xyz(0.0, 4.0, 0.0),
    SoftBody::new(
        SoftBodyBuilder::new(points)
            .shape_matching(true)
            .particle_radius(0.1),
    ),
    SoftBodyMaterial(RapierSoftBodyMaterial {
        // How fast the particles are pulled back toward their rest shape.
        shape_matching_softness: SpringCoefficients::new(5.0, 1.0),
        ..default()
    }),
));
tip

Use shape matching for low-detail deformations, or whenever computing a topology (edges, cells) isn't desired. It is enabled by default by the trimesh and polyline constructors. Note however that it performs very poorly for ropes, cloth, or any open shape. Also note that combining it with edges makes the deformations spread to the neighbors to look more realistic.

Constraints​

The constraints-based soft-body solver is the default solver (SoftBodySolver::Constraints), and the most versatile one: every edge and cell element of the deformation lattice becomes a constraint, solved together with the contacts and the joints of the scene.

Edge and cell constraints

An edge is a spring-damper pulling its two particles back toward its rest length. A cell is either a volume constraint keeping its area or its volume, the shape itself being held by the edges, or an elastic element resisting any deformation. This is selected by the cell model of the body (cell_model):

  • Volume: one constraint per cell keeping its area (2D) or its volume (3D) at its rest value. This is the cheapest model, and combined with the edges it is often enough to obtain a convincing jelly.
  • Corotational: linear elasticity expressed in the rotation-free frame of the cell. It is stable at any stiffness and recovers from inverted cells.
  • NeoHookean: stable Neo-Hookean hyperelasticity. It feels stiffer than linear elasticity on compression, but softer on tension.

The stiffness of every element is configured by the SoftBodyMaterial of the body, which can be given to the builder or set at any time with the component of the same name, which wraps the Rapier material (re-exported as RapierSoftBodyMaterial) and overrides the one of the builder. The edges and the volume constraints are given a softness, i.e., a natural frequency (in Hz) and a damping ratio instead of a stiffness, so it doesn't depend on the masses of the particles:

  • The edge softness (edge_softness) for the structural edges;
  • The bend softness (bend_softness) for the bending edges and the dihedral constraints;
  • The volume softness (volume_softness) for the volume constraints.

The elastic cells are given a Young modulus (young_modulus, in force per unit area in 3D, per unit length in 2D), a Poisson ratio (poisson_ratio), and a damping ratio (elastic_damping_ratio) instead. Their natural frequency is derived from these, therefore a body meshed more finely doesn't become stiffer, whereas it becomes more expensive to simulate.

Finally, a body with a closed surface can preserve the area (2D) or the volume (3D) it encloses (volume_preservation), which target can be scaled by a volume_factor (or a SoftBodyVolumeFactor component) greater than 1 in order to inflate the body, e.g., to simulate a pressurized blob:

// Elastic cells: a jelly square with corotational linear elasticity.
let jelly_body = SoftBody::grid(Vec2::splat(1.0), 6, 6).map(|builder| {
    // The constitutive model of the cells: `Volume` (per-cell area constraints,
    // the shape is held by the edges), `Corotational` or `NeoHookean`.
    builder
        .cell_model(SoftBodyCellModel::Corotational)
        .particle_mass(0.2)
});
let jelly = commands
    .spawn((
        Jelly,
        Transform::from_xyz(3.0, 1.2, 0.0),
        jelly_body.clone(),
        // The material of the soft-body: modifying this component updates the soft-body.
        SoftBodyMaterial(RapierSoftBodyMaterial {
            // Stiffness of the elastic cells.
            young_modulus: 3.0e3,
            poisson_ratio: 0.35,
            elastic_damping_ratio: 0.5,
            // Plasticity: the rest shape flows past 5% strain, at 20 per second.
            plastic_yield: 0.05,
            plastic_creep: 20.0,
            // Tearing: an element past 40% strain tears.
            tear_strain: Some(0.4),
            ..default()
        }),
    ))
    .id();

// A pressurized blob: a ring of particles inflated by area preservation.
let blob_body = SoftBody::disk(0.8, 24).map(|builder| builder.self_contacts(true));
let blob_transform = Transform::from_xyz(0.0, 3.0, 0.0);
let blob = commands
    .spawn((
        blob_transform,
        blob_body.clone(),
        SoftBodyMaterial::uniform(20.0, 1.0),
        // Target area multiplier (`> 1` inflates the body).
        SoftBodyVolumeFactor(1.1),
    ))
    .id();
info

The stiffness effectively simulated by the constraints solver depends on its convergence: with too few iterations, a stiff body looks softer than its material says. This is why soft-bodies are configured with 3 additional internal PGS solver iterations by default, which can be modified with additional_pgs_iterations. The whole island a body belongs to can also be given additional substeps with additional_solver_iterations, just like rigid-bodies.

The same chain solved with 1, 4, and 32 iterations

The following table gathers the settings to look at for the most common problems:

ProblemWhat to change
The body is too soft, or stretches too much.Raise the natural frequency of the material's edge_softness, or its young_modulus for the elastic cells. Give it more additional_pgs_iterations, or switch it to the FEM solver with solver.
A cloth stretches, but should still fold easily.Keep a stiff edge_softness, and give it a soft bend_softness.
A rope compresses like a spring.Make its edges resist stretching only with tension_only.
The body keeps wobbling after an impact.Raise the damping_ratio of the material's softnesses and its elastic_damping_ratio, or its deformation_damping (which damps the deformations but not the motion of the body as a whole).
A closed body collapses, or must be inflated.Enable volume_preservation, and give it a volume_factor greater than 1.
The deformations are too local.Combine shape_matching with edges, or rely on edges and cells alone.

FEM solver​

The FEM solver (SoftBodySolver::Fem, behind the fem feature of bevy_rapier, given to the builder or with the SoftBodyElasticitySolver component) resolves the elasticity of the whole body at once and semi-implicitly: the forces and the stiffness of every cell are assembled into a single linear system, solved at each substep. Therefore the stiffness of the body no longer depends on the number of solver iterations, which makes it capable of simulating very stiff materials, as well as more realistic plastic deformations and failures:

Assembly of the FEM system

This comes at a price: the system is factorized at each timestep, and every constraint touching the body (contacts, joints) needs a solve against it. Note that the FEM solver requires cells, so it only applies to the bodies built with cells, e.g., with the grid, cuboid, or volumetric constructors. The configuration of its linear solves is shared by every body using it, and lives in the integration parameters:

fn configure_fem(
    mut commands: Commands,
    mut simulation: Single<&mut RapierContextSimulation, With<DefaultRapierContext>>,
) {
    // A stiff beam simulated by the FEM solver (requires the `fem` feature): its stiffness
    // doesn't depend on the number of solver iterations.
    commands.spawn((
        Transform::from_xyz(0.0, 2.0, 0.0),
        SoftBody::grid(Vec2::new(1.0, 0.1), 21, 3).map(|builder| {
            builder
                .cell_model(SoftBodyCellModel::NeoHookean)
                // The particles of the side at `x = -1` are the first 3 ones.
                .pinned_particles(0..3)
        }),
        SoftBodyElasticitySolver(SoftBodySolver::Fem),
        SoftBodyMaterial(RapierSoftBodyMaterial {
            young_modulus: 1.0e5,
            poisson_ratio: 0.3,
            ..default()
        }),
    ));

    // The tuning of the linear solves of the FEM solver, shared by every body using it.
    let fem = &mut simulation.integration_parameters.soft_bodies.fem;
    fem.linear_tolerance = 1.0e-5;
    fem.max_linear_iterations = 20;
}

The linear solves stop at the relative residual linear_tolerance, or after max_linear_iterations conjugate-gradient iterations, whatever the residual. The bodies with at most max_dense_dofs degrees of freedom (600 by default) are factorized directly, whereas the larger ones rely on the iterative conjugate gradient.

tip

Use the FEM solver for stiff materials which simulated stiffness must not depend on the iteration count, e.g., the chassis of a car or a metal beam. This also results in more realistic plasticity and tearing.

Contacts and self-intersections​

A soft-body collides through the collider covering its surface, which is a deformable triangle-mesh (a polyline in 2D) built from the template given to the builder.

Thickness​

The radius of the particles (particle_radius) is the thickness of the soft-body wrt. collision-detection: it is the contact skin of its surface collider, i.e., the distance kept between the surface and the objects touching it, as well as the distance the solver bounds the motion of one particle by at each substep. A radius that is too small relative to the distance between two neighboring particles may let thin objects pass through the surface, whereas a radius larger than that distance will make the body collide with itself even when it is at rest. Therefore it is recommended to keep it well below the distance between two neighboring particles. Note that every constructor picks a sensible default, i.e., about half the length of its edges or of its cells.

Oriented surfaces and shells​

A closed surface (a balloon, a jelly cube, a filled polygon) is oriented: its contacts are generated on its outward side only, like for an oriented triangle-mesh, so nothing is held inside it. An open surface (a rope, a cloth) is two-sided, because a body arriving from either side must be stopped. This is what the builder does by default, and it is what a solid body wants. A shell, i.e., a closed surface which inner side must hold the bodies contained in it, is obtained by asking for a surface that is not oriented (oriented):

// A shell: a closed surface that is not oriented, so its inner side holds the bodies put
// inside it (a bowl, a box, a container). A closed surface is oriented by default.
commands.spawn((
    Transform::from_xyz(-3.0, 2.0, 0.0),
    SoftBody::disk(0.8, 24).map(|builder| {
        builder
            .oriented(false)
            .softness(SpringCoefficients::new(60.0, 1.0))
    }),
));
note

After the insertion, the shape of the Rapier collider of the surface is the authority: the flag is changed there, like for any other collider.

Self-contacts​

A soft-body doesn't collide with itself by default. Self-contacts are enabled by SoftBodyBuilder::self_contacts, which makes the vertices and the edges of the surface collide with the surface of their own body: this is what keeps a cloth folding onto itself, or a jelly squashed against itself, from passing through itself. Note that they are more expensive, since the whole surface must be tested against itself.

Penetrations and tangles​

The contacts between two meshes are computed triangle by triangle (segment by segment in 2D), without any notion of their interiors. As long as the two surfaces don't penetrate, this works well. But as soon as they do, some of these local contacts start pointing the wrong way, and actively keep the two surfaces in their penetrating state instead of separating them. Deformations make it worse, since a single surface can also cross itself and end up tangled:

Local contacts between penetrating meshes

Rapier handles these configurations by measuring the volume of the overlap between the two surfaces. The gradient of that volume gives a good approximation of the direction separating the two bodies, aka. the volume normal, which is used both to push the overlapping regions apart, and to correct the direction of the local contacts inside them:

Contact directions corrected with the volume normal

This is enabled by default for the closed surfaces, against other soft-bodies as well as against rigid colliders.

It is configured, along with the detection and the recovery of the tangled configurations, by the recovery settings of the global settings (integration_parameters.soft_bodies.recovery of the RapierContextSimulation component). Every mechanism can be switched off individually, and the table below lists the ones to look at for the most common problems:

ProblemWhat to change
Thin or fast objects pass through a surface.Raise the particle radius (particle_radius). Let the body request more substeps while it is hit fast (max_extra_substeps).
Two bodies crossing corner-first don't collide.Enable edge_speculation (note that it can leave pressed 3D piles crossed).
A body stays tangled with itself.Keep self_stand_down enabled (the default), which lets the elasticity untangle it, or push the crossed features apart with crossing_repulsion.
The recovery from a penetration is too slow, or too violent.Change the recovery_pace, i.e., the corrective speed allowed to the recovery (in length units per second).
Soft contacts feel too spongy.Raise the contact_stiffening of the soft-body contacts relative to the rigid ones.
The overlap of two bodies isn't resolved at all.Make sure both surfaces are closed: the intersection-volume constraints (overlap_constraints) only apply to them.

Soft frames: joints and rigid colliders​

Joints and rigid colliders both need a frame to be attached to, i.e., a translation and a rotation, which a soft-body doesn't have. This is what soft frames are for: a soft frame is a rigid-body of type RigidBodyType::SoftFrame which pose is computed at each timestep from a set of particles, by shape-matching. Since it is an ordinary rigid-body, every API working with rigid-bodies works with it too: impulse joints of any kind (fixed, revolute, prismatic, generic, etc.) can be attached to it, as well as rigid colliders (sensors included), and its position can be read at any time. Therefore a soft-body is linked to another soft-body, to a rigid-body, or to a multibody exactly the same way two rigid-bodies are.

The root body​

Every soft-body is created with one soft frame covering all of its particles: its root body. It is the rigid-body given by RapierSoftBody::root_body. A joint attached to it acts on the soft-body as a whole, and so does a force or an impulse applied to it. It also stands for the soft-body in the islands, and it is the parent of the colliders the engine built for the body's surface (a deformable collider bound to another cluster has the proxy of that cluster as its parent instead). The soft-body a collider belongs to is given by the deformable_mesh_ref of the Rapier collider, which is how a collider reported by a scene query or by a collision event is traced back to the body it covers. Note that this is rarely needed here, since the colliders of the surface report the soft-body entity itself as their entity.

The soft-body entity stands for its root body: an ImpulseJoint inserted on the soft-body entity, or which parent is the soft-body entity, is attached to the root body, and so is a Collider inserted on a child entity of the soft-body entity (such a child follows the pose of the root body, as explained in the soft-bodies and entities section). The handle of the root body is given by soft_body_whole_proxy:

// The soft-body entity stands for its root body. A joint attached to it acts on the soft-body
// as a whole: this one hangs the jelly under a fixed anchor by a spring.
let anchor = commands
    .spawn((Transform::from_xyz(3.0, 5.0, 0.0), RigidBody::Fixed))
    .id();
commands.entity(jelly).insert(ImpulseJoint::new(
    anchor,
    SpringJointBuilder::new(2.0, 60.0, 2.0),
));

// A rigid collider on a child of the soft-body entity is attached to its root body: here a
// sensor detecting what comes close to the jelly.
commands
    .entity(jelly)
    .with_child((Transform::default(), Collider::ball(1.6), Sensor));
warning

The pose of the root body is recomputed from the particles at each timestep, therefore moving it has no effect. Removing it is not a no-op though: like any cluster proxy, it takes its cluster with it, i.e., the whole soft-body, unless another cluster covers some of its particles (see removal).

Clusters​

A single frame for the whole body is often not expressive enough: several joints attached to the root body all act on the body as a whole, and their effect isn't concentrated where they are attached. This is why a soft-body can also be given clusters (entities with a SoftBodyCluster component), i.e., soft frames over any subset of its particles, each with its own pose computed by shape-matching over that subset only. Joints attached to different clusters then act on different parts of the body, each with its own orientation:

One soft frame per cluster

Similarly, rigid colliders attached to the proxies of different clusters move and rotate independently, which is what allows the definition of rigid parts on a deformable body: the handle of a deformable hammer, the bones of a soft character, or the plate a jelly is carried on.

Rigid colliders attached to different soft frames

A cluster is created by inserting a SoftBodyCluster component (containing the soft-body entity it related to and the indices of the particles of the cluster) on another entity than the soft-body entity. The plugin then inserts the RapierRigidBodyHandle of the proxy of the cluster on that entity, which can therefore be used like any rigid-body entity by the ImpulseJoints, as well as by the Colliders inserted on its children. The pose of the proxy is written back to the Transform of the cluster entity after each step, so its children follow every motion of the cluster. Note that the cluster entity must not be given a RigidBody component, that modifying its Transform has no effect, and that its SoftBodyCluster component is only read when the cluster is created:

// A cluster over the top particles of the jelly (their indices are read from its builder,
// in the local frame of the jelly entity).
let top: Vec<u32> = (0..)
    .zip(jelly_body.builder.particle_positions())
    .filter(|(_, p)| p.y > 0.8)
    .map(|(i, _)| i)
    .collect();
// A rigid plate welded onto the cluster.
let plate = commands
    .spawn((
        Transform::from_xyz(3.0, 2.4, 0.0),
        RigidBody::Dynamic,
        Collider::cuboid(1.2, 0.05),
        ColliderMassProperties::Density(0.4),
    ))
    .id();
// The cluster entity gets the proxy rigid-body of the cluster, which joints and colliders
// can be attached to like to any rigid-body.
commands.spawn((
    PlateCluster,
    SoftBodyCluster::new(jelly, top),
    ImpulseJoint::new(
        plate,
        FixedJointBuilder::new().local_anchor1(Vec2::new(0.0, -0.1)),
    ),
    // A cluster can be tuned as a whole.
    SoftBodyClusterMaterial {
        stiffness_scale: 2.0,
        ..default()
    },
    SoftBodyClusterShapeMatching::default(),
));

A cluster also defines a few settings for the elements it covers, which gives regional materials without needing separate bodies:

  • The stiffness scale (SoftBodyClusterMaterial::stiffness_scale) multiplies the Young modulus of every cell entirely contained in the cluster (the cells straddling its boundary are left unchanged).
  • The edge softness (SoftBodyClusterMaterial::edge_softness) overrides the softness of every edge entirely contained in the cluster, e.g., a stiffer collar on a shirt.
  • The tear resistance (SoftBodyClusterMaterial::tear_resistance) multiplies the tear thresholds of every element entirely contained in the cluster, e.g., a tough region, or a perforation line.
  • Shape-matching (the SoftBodyClusterShapeMatching component) pulls the particles of the cluster toward the frame of its proxy (or toward the world-space target of that component), so that part of the body tends to keep the shape it was created with.

These cluster components, as well as the ones controlling a cluster kinematically, are applied again whenever they change, and can also be inserted on the soft-body entity itself in order to act on its whole-body cluster.

warning

The rotation of a cluster is deduced from its particles, which isn't possible for a cluster made of a single particle (or, in 3D, of collinear particles). Such a cluster has no angular response, therefore the angular parts of the joints attached to its proxy are disabled.

Attaching a rigid-body to a particle​

A particle can also be attached directly to a rigid-body (the SoftBodyAttachments component), which is the simplest way of combining the two kinds of bodies: a rope tied to a swinging ball, a flag attached to its pole, etc. Unlike pinning, an attachment is a two-way point-to-point constraint: the rigid-body holds the particle, and the particle pulls the rigid-body back. The anchor is the position the particle has when the attachment is created, expressed in the local frame of the rigid-body. Note that a particle attached twice keeps both of its attachments, and that an attachment is undone with its removal from the SoftBodyAttachments component (removing the component detaches every particle):

Each entry of the SoftBodyAttachments component attaches one particle to the entity of a rigid-body (or of a cluster). Each time the component changes, the attachments of the soft-body are updated to match it: the attachments that didn't change keep their anchor, and the ones targeting an entity which rigid-body isn't created yet are retried on the next frames:

// Attach the last particle of a rope to a rigid box, at the particle's position.
let weight = commands
    .spawn((
        Transform::from_xyz(12.0, 8.6, 0.0),
        RigidBody::Dynamic,
        Collider::cuboid(0.3, 0.3),
        ColliderMassProperties::Density(2.0),
    ))
    .id();
commands.spawn((
    Rope,
    Transform::from_xyz(8.0, 9.0, 0.0),
    SoftBody::rope(Vec2::ZERO, Vec2::new(4.0, 0.0), 25).map(|builder| {
        builder
            .pinned_particles([0])
            .softness(SpringCoefficients::new(40.0, 1.0))
    }),
    SoftBodyAttachments(vec![SoftBodyAttachment {
        particle: 24,
        body: weight,
    }]),
));

Particles and kinematic control​

The state of a soft-body is the state of its particles, which are identified by their index in the body. Their positions and their velocities can be read (particle_position, particle_positions, particle_velocity, particle_velocities) and modified (set_particle_position, set_particle_velocity) at any time, one by one or all at once. The elements built from them (edges, cells, and boundary) can be read as well, e.g., in order to render the body with your own mesh. These are methods of the Rapier soft-body of the entity, given by the soft_body and soft_body_mut methods of the physics context (see soft-bodies and entities). Note that the positions are expressed in world-space, and not in the frame of the entity.

A particle can also be pinned (the SoftBodyPinnedParticles component). A pinned particle is kinematic: it is no longer affected by the forces nor by the contacts, and it will simply hold its position, or follow the kinematic target (the SoftBodyKinematicTargets component) or the velocity it is given. This is, e.g., how a piece of cloth is hung on a wall, or how a rope is dragged by the player. Releasing the particle gives it back its nominal mass and lets it keep its current velocity:

The SoftBodyPinnedParticles component lists exactly the particles that are pinned: it replaces the particles pinned by the builder, which are restored when the component is removed. The SoftBodyKinematicTargets component gives world-space targets to some of the pinned particles: each time it changes, the listed particles are moved to their target over the next step, then held there:

fn control_particles(
    mut commands: Commands,
    mut context: WriteRapierContext,
    sheet: Single<Entity, With<Sheet>>,
) -> Result {
    let mut context = context.single_mut()?;
    let Some(soft_body) = context.soft_body_mut(*sheet) else {
        return Ok(());
    };
    // Read the particles (in world-space).
    let position = soft_body.particle_position(0);
    let velocity = soft_body.particle_velocity(0);
    let positions: Vec<Vec2> = soft_body.particle_positions().collect();
    assert_eq!(positions.len(), soft_body.num_particles());
    // Move a particle.
    soft_body.set_particle_position(1, position + Vec2::new(0.0, 0.1));
    soft_body.set_particle_velocity(1, velocity);
    // The elements: edges, cells and the boundary segments.
    let num_edges = soft_body.edges().len();
    let num_cells = soft_body.cells().len();
    let boundary: &[[u32; 2]] = soft_body.boundary();
    assert!(num_edges > 0 && num_cells > 0 && !boundary.is_empty());

    // Pin particles (exactly the listed ones), and drive the particle 2 kinematically.
    commands.entity(*sheet).insert((
        SoftBodyPinnedParticles(vec![0, 19, 2]),
        SoftBodyKinematicTargets(vec![(2, Vec2::new(-3.5, 3.5))]),
    ));
    Ok(())
}
warning

Setting the position of a particle explicitly teleports it: no contact is taken into account along the way, so a particle can be moved inside of another object this way. Whenever the motion must be seen by the contacts and by the friction (to drag a piece of cloth, for example), it is recommended to pin the particle and to give it a kinematic target instead.

Controlling a region kinematically​

A whole region of the body is controlled at once through a cluster covering it. Pinning the cluster (the SoftBodyClusterPinned component) pins all of its particles, and its kinematic target (the SoftBodyClusterKinematicTarget component, a world-space Transform which also pins the cluster when it is inserted) moves them rigidly: each pinned particle is sent where the rest shape of the cluster places it at the target pose, with the matching velocity. The rest of the body is then simulated as usual, and drags behind the controlled region, e.g., the hand of a soft character carrying something:

fn drive_cluster(mut commands: Commands, cluster: Single<Entity, With<PlateCluster>>) {
    // Pin every particle of the cluster (the target inserts `SoftBodyClusterPinned`), and move
    // it to a world-space pose: the cluster behaves like a kinematic rigid part dragging the
    // rest of the body.
    commands
        .entity(*cluster)
        .insert(SoftBodyClusterKinematicTarget(Transform::from_xyz(
            3.0, 2.5, 0.0,
        )));
}

fn release_cluster(mut commands: Commands, cluster: Single<Entity, With<PlateCluster>>) {
    // Release it: the cluster is simulated again.
    commands
        .entity(*cluster)
        .remove::<(SoftBodyClusterKinematicTarget, SoftBodyClusterPinned)>();
}

Deformable colliders and skinning​

Games don't need the simulated shape of a body to be as detailed as its visual shape: a coarse and well-shaped lattice is faster and more stable to simulate than one cell per visual triangle. This is why Rapier supports cage simulation and skinning. The detailed mesh is embedded in a coarse volumetric lattice, aka. its cage, which is the only part being simulated. The vertices of the mesh are then interpolated from the deformed cells holding them, aka. skinning:

A detailed mesh, its coarse cage, and the mesh following the deformed cage

Skinned soft-bodies​

The SoftBody::volumetric_skinned constructor computes the cage of a closed mesh automatically, and keeps the mesh as the skin of the body. That automatic cage is built for performance rather than geometric fidelity: in 3D, it encloses the whole mesh with the tetrahedra of a lattice, without snapping them to the mesh:

A screwdriver mesh and its automatically generated cage (blue)

By default, the body still collides through the boundary of its cage, which is as coarse as its cells. Its skin can become its actual collision mesh instead with skin_collision.

The SoftBodyMeshSync component renders the skin of a 3D body, as in this example (the meshes of the deformable colliders bound to a body are never rendered by this component). In 2D, it renders the cells of the cage instead, and the vertices of the skin are read from the collision mesh of the Rapier soft-body (RapierSoftBody::collision_mesh):

// A detailed outline held by a coarse cage of cells: only the cells are simulated, and the
// outline (the skin) follows their deformation.
let num = 48;
let vertices: Vec<Vec2> = (0..num)
    .map(|i| {
        let angle = i as f32 / num as f32 * std::f32::consts::TAU;
        Vec2::new(angle.cos(), angle.sin()) * 0.5
    })
    .collect();
let indices: Vec<[u32; 2]> = (0..num as u32).map(|i| [i, (i + 1) % num as u32]).collect();
let skinned = SoftBody::volumetric_skinned(&vertices, &indices, 0.25)
    .expect("the polyline must be closed and enclose some area")
    // Collide through the skin instead of the boundary of the cage.
    .map(|builder| builder.skin_collision(true));
commands.spawn((
    Transform::from_xyz(0.0, 4.0, 0.0),
    skinned,
    // The synchronized mesh renders the cells of the cage.
    SoftBodyMeshSync::default(),
    MeshMaterial2d(materials.add(Color::srgb(0.2, 0.6, 0.3))),
));
info

A skin doesn't need a computed cage: any mesh can be given as the skin of a body built with cells, with SoftBodyBuilder::skin. Each of its vertices is bound to the cell closest to it, in the pose the cells are built in.

Deformable colliders​

The colliders built from the surface or the skin of a soft-body are generated by the engine itself, but it is also possible to give a body a collider of your own which vertices follow its particles: a deformable collider (a DeformableCollider component next to the Collider of an entity). This is a polyline in 2D, or a triangle mesh in 3D, flagged as deformable, and attached to the proxy of one of the clusters of the body (the root body, a cluster itself, can be used too). Its vertices are given in world-space, i.e., they are placed by the GlobalTransform of the collider entity when the collider is created, and they can be read back at any time in order to render the mesh where the simulation moved it. A deformable collider can be a sensor as well, e.g., to detect what enters a deformable volume.

How the vertices follow the particles is given by the binding (SoftMeshBinding):

  • skinned: each vertex is embedded in the cell of the cluster holding it, i.e., the collider is a skin of the cage.
  • direct: the vertex i follows the particle given for it, which must belong to the cluster. Its alternative that binds every vertex to the closest particle within a given distance (direct_by_position) is useful when the mesh is the one the particles were built from.

The DeformableCollider component targets the soft-body entity (for its root body) or a cluster entity. The Collider of its entity must be a polyline (2D) or a triangle mesh (3D) flagged with PolylineFlags::DEFORMABLE or TriMeshFlags::DEFORMABLE. Once created, the collider follows the particles: the Transform and the shape of its entity are ignored, whereas its other collider components (friction, collision groups, events, etc.) apply as usual. If the binding fails, an error is logged and a DeformableColliderError component is inserted on the entity:

// A deformable polyline bound to the blob: each vertex follows one particle (`direct`),
// or is embedded in the cell holding it (`skinned`). The vertices are placed by the
// transform of the collider entity when the collider is created.
let vertices = blob_body.builder.particle_positions().to_vec();
let num = vertices.len() as u32;
let indices: Vec<[u32; 2]> = (0..num).map(|i| [i, (i + 1) % num]).collect();
commands.spawn((
    blob_transform,
    Collider::polyline_with_flags(vertices, Some(indices), PolylineFlags::DEFORMABLE),
    Sensor,
    DeformableCollider::new(blob, SoftMeshBinding::direct((0..num).collect())),
));

The current vertices of a deformable collider are read from the Rapier soft-body it follows, which is also given by the deformable_mesh_ref of its Rapier collider:

fn read_deformable_colliders(
    context: ReadRapierContext,
    colliders: Query<&RapierColliderHandle, With<DeformableCollider>>,
) -> Result {
    let context = context.single()?;
    for handle in &colliders {
        // The soft-body a collider follows.
        let collider = &context.colliders.colliders[handle.0];
        let Some(mesh_ref) = collider.deformable_mesh_ref() else {
            continue;
        };
        let soft_body = &context.rigidbody_set.soft_bodies[mesh_ref.body];
        // The mesh follows the particles: read its current vertices back (in world-space).
        let mesh = soft_body.mesh_of(handle.0).unwrap();
        let vertices: Vec<Vec2> = mesh.vertex_positions(soft_body).collect();
        assert!(!vertices.is_empty());
    }
    Ok(())
}
info

A deformable collider has no mass: its density is ignored, and it is the particles which hold the mass of the soft-body. Note that a collider given no contact skin explicitly gets the particle radius of the soft-body as its skin, so its thickness matches the thickness of the surface of the body.

Plasticity and 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.

Tear events​

The tears applied during a step, whether they were generated by the simulation itself or requested with RapierSoftBody::tear_edge (as well as the ones applied by RapierContextMut::tear_soft_body and cut_soft_body), are reported the same way as the collision events, i.e., as messages. Each event (a SoftBodyTearEvent, read with a MessageReader) identifies the soft-body that tore and gives the pieces it was split into, so the rendering of the scene can be updated accordingly:

The SoftBodyTearEvent message gives the entities of the torn soft-body and of its pieces (the first piece being the torn entity itself, the other ones being the entities already returned by tear_soft_body and cut_soft_body for the tears they applied), the pieces of the clusters the tear split (cluster_splits), and the joints it moved from a cluster proxy to another (moved_joints). Its raw field is the event of Rapier, with every detail of the topology change in terms of handles and particle indices:

fn read_tear_events(context: ReadRapierContext, mut tears: MessageReader<SoftBodyTearEvent>) {
    let Ok(context) = context.single() else {
        return;
    };
    for tear in tears.read() {
        // The first piece is the torn entity itself, the others are the entities spawned for
        // the soft-bodies split off it.
        for piece in &tear.pieces {
            println!(
                "Soft body {} tore: piece {} has {} particles",
                tear.soft_body,
                piece.soft_body,
                piece.particles.len()
            );
        }
        // Where a particle of the torn body went.
        if let Some((handle, index)) = tear.raw.particle_destination(399) {
            let entity = context.soft_body_entity(handle);
            println!("particle 399 is now particle {index} of {entity:?}");
        }
    }
}

Forces and impulses​

Forces and impulses can be applied to a soft-body as a whole (SoftBodyExternalForce::force, SoftBodyExternalImpulse::velocity_change), or to one particular particle (SoftBodyExternalForce::particle_forces, SoftBodyExternalImpulse::particle_impulses). A force added to the whole body is added to each of its free particles and is persistent, i.e., it keeps being applied at each step until the forces are reset (i.e., until the SoftBodyExternalForce component changes or is removed), exactly like the forces of a rigid-body. An impulse applied to the whole body is a velocity change applied to each of its free particles, so the body is kicked as a whole without being deformed. Note that the pinned particles ignore both.

Two additional methods are provided for the effects which magnitude depends on the distance to a point: an impulse applied within a radius (apply_impulse_at_point), and a radial blast pushing the particles away from its center (apply_radial_impulse). In both cases the impulse is scaled linearly down to zero at the given radius. Like for the rigid-bodies, the last boolean argument of all these methods ensures the soft-body is awake before the force or the impulse is applied:

The SoftBodyExternalForce and SoftBodyExternalImpulse components wake the soft-body up automatically, and the impulses of the SoftBodyExternalImpulse component are reset to zero once they are applied. The impulses depending on the distance to a point are applied to the Rapier soft-body of the entity directly:

fn apply_forces(
    mut commands: Commands,
    mut context: WriteRapierContext,
    sheet: Single<Entity, With<Sheet>>,
) -> Result {
    commands.entity(*sheet).insert((
        // Persistent forces: applied at each step until the component changes or is removed.
        SoftBodyExternalForce {
            force: Vec2::new(0.0, 1.0),
            particle_forces: vec![(3, Vec2::new(0.0, 1.0))],
        },
        // One-time impulses: applied (and reset to zero) at the next step.
        SoftBodyExternalImpulse {
            velocity_change: Vec2::new(0.0, 0.1),
            particle_impulses: vec![(3, Vec2::new(0.0, 0.1))],
        },
    ));

    // The other impulses are applied to the Rapier soft-body directly. The `true` argument
    // makes sure the soft-body is awake.
    let mut context = context.single_mut()?;
    if let Some(soft_body) = context.soft_body_mut(*sheet) {
        // An impulse on the particles within 0.5 of a point, scaled down with the distance.
        soft_body.apply_impulse_at_point(Vec2::new(0.0, 0.1), Vec2::new(-3.0, 3.0), 0.5, true);
        // A blast pushing the particles away from a center.
        soft_body.apply_radial_impulse(Vec2::new(-3.0, 3.0), 0.1, 1.0, true);
    }
    Ok(())
}

Global 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), so they can be changed between two steps:

  • The re-sweep strain (resweep_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_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_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 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 SoftFemParameters):

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;
}

Removal​

Removing a soft-body (i.e., despawning its entity, or removing its SoftBody component) removes everything the engine created for it: its root body, the proxies of its clusters, the colliders of its surface and of its deformable meshes, as well as the joints attached to any of them. One cluster can also be removed on its own (by despawning its entity, or removing its SoftBodyCluster component):

fn remove_soft_bodies(
    mut commands: Commands,
    rope: Single<Entity, With<Rope>>,
    cluster: Single<Entity, With<PlateCluster>>,
) {
    // Despawning a soft-body entity (or removing its `SoftBody` component) removes its root
    // body, its proxies, its colliders and the joints attached to them.
    commands.entity(*rope).despawn();
    // Despawning a cluster entity (or removing its `SoftBodyCluster` component) removes the
    // cluster.
    commands.entity(*cluster).despawn();
}
warning

Removing a cluster also removes the particles that only this cluster covered, with their elements and their attachments. Therefore removing the last cluster of a soft-body removes the soft-body itself. Note that removing the proxy of a cluster from the rigid-body set is equivalent to removing the cluster.