Skip to main content

soft_body_deformable_colliders

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 SoftBodyBuilder::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.

// 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<Vector> = (0..num)
    .map(|i| {
        let angle = i as f32 / num as f32 * std::f32::consts::TAU;
        Vector::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 = SoftBodyBuilder::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.
    .skin_collision(true)
    .translated(Vector::new(0.0, 4.0));
let skinned_handle = world.insert_soft_body(skinned);
// The skin is the body's collision mesh: read its vertices back to render it.
let body = &world.soft_bodies[skinned_handle];
let skin = body.collision_mesh().expect("the skin collides");
let skin_vertices: Vec<Vector> = skin.vertex_positions(body).collect();
assert_eq!(skin_vertices.len(), vertices.len());
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 (ColliderSet::insert_deformable). 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 the frame of that proxy, 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.
// A deformable polyline bound to the blob: each vertex follows one particle (`direct`),
// or is embedded in the cell holding it (`skinned`). The polyline is given in the frame
// of the proxy it is attached to.
let root = world.soft_bodies[blob_handle].root_body();
let root_pose = *world.bodies[root].position();
let blob = &world.soft_bodies[blob_handle];
let num = blob.num_particles();
let vertices: Vec<Vector> = blob
    .particle_positions()
    .map(|p| root_pose.inverse() * p)
    .collect();
let indices: Vec<[u32; 2]> = (0..num as u32).map(|i| [i, (i + 1) % num as u32]).collect();
let particles: Vec<u32> = (0..num as u32).collect();
let outline =
    ColliderBuilder::polyline_with_flags(vertices, Some(indices), PolylineFlags::DEFORMABLE)
        .sensor(true);
let outline_handle = world
    .insert_deformable(outline, SoftMeshBinding::direct(particles), root)
    .expect("a deformable polyline bound to a cluster proxy");
// The polyline follows the particles: read its current vertices back.
let blob = &world.soft_bodies[blob_handle];
let mesh = blob.mesh_of(outline_handle).unwrap();
let outline_vertices: Vec<Vector> = mesh.vertex_positions(blob).collect();
assert_eq!(outline_vertices.len(), num);
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.