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:

Skinned soft-bodies

The SoftBody.volumetric constructor computes the cage of a closed mesh automatically when its skinned argument is True, 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:

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

SoftBody.volumetric raises a MeshConversionError if the mesh can't be filled with cells, e.g., because it isn't closed. The vertices of the skin, as well as the ones of any other mesh of the body, are read back from a SoftCollisionMesh: a snapshot of the mesh taken when it is requested, which vertices (in world-space) and indices are NumPy arrays. SoftBody.collision_mesh gives the collision mesh of the body (its skin here), and SoftBody.mesh_of gives the mesh of a collider. A skin that doesn't collide has no collider: SoftBody.meshes lists every mesh of the body (its is_skinned and collision_enabled properties telling which mesh is which), and SoftBody.mesh gives the mesh with the given identifier (a SoftMeshId):

# A detailed mesh held by a coarse cage of cells: only the cells are simulated, and the mesh
# (the skin) follows their deformation.
vertices, indices = rp.Ball(0.5).to_trimesh(24, 24)
# Raises `MeshConversionError` if the mesh isn't closed or doesn't enclose any volume.
skinned = (
    rp.SoftBody.volumetric(vertices, indices, 0.25, skinned=True)
    # Collide through the skin instead of the boundary of the cage.
    .skin_collision(True)
    .translated((0.0, 4.0, 3.0))
)
skinned_handle = world.add_soft_body(skinned)
# The skin is the body's collision mesh: read its vertices back to render it.
skin = world.soft_bodies[skinned_handle].collision_mesh()
assert skin is not None and skin.is_skinned
assert skin.vertices.shape == vertices.shape

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 (PhysicsWorld.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.

The collider is built by Collider.trimesh with the TriMeshFlags.DEFORMABLE flag, and its binding by one of the static methods of SoftMeshBinding: skinned(), direct(particles), or direct_by_position(eps), the self_contacts method of the binding making the mesh collide with itself. The collider is created by PhysicsWorld.insert_deformable (or by ColliderSet.insert_deformable when the sets are used directly), given the rigid-body handle of the root body (SoftBody.root_body) or of a cluster proxy (SoftBody.cluster_proxy) it is attached to. Its other properties (friction, collision groups, events, sensor, etc.) apply as usual. If the binding fails, a SoftBindingError is raised. Then the current vertices of the collider are read from its SoftCollisionMesh (SoftBody.mesh_of), and the collider tells which soft-body mesh it is with its deformable_mesh_ref property:

# A deformable triangle mesh bound to the jelly: each vertex is embedded in the cell
# holding it (`skinned`), or follows one particle (`direct`). The mesh is given in the
# frame of the proxy it is attached to.
jelly = world.soft_bodies[jelly_handle]
root = jelly.root_body
to_root = world.rigid_bodies[root].position.inverse()
center = jelly.center_of_mass
r = 1.0
offsets = [(r, 0.0, 0.0), (-r, 0.0, 0.0), (0.0, r, 0.0), (0.0, -r, 0.0), (0.0, 0.0, r), (0.0, 0.0, -r)]
vertices = np.array([tuple(to_root.transform_point(center + v)) for v in offsets], dtype=np.float32)
indices = np.array(
    [[0, 2, 4], [2, 1, 4], [1, 3, 4], [3, 0, 4], [2, 0, 5], [1, 2, 5], [3, 1, 5], [0, 3, 5]],
    dtype=np.uint32,
)
skin = rp.Collider.trimesh(vertices, indices, rp.TriMeshFlags.DEFORMABLE).sensor(True)
# Raises `SoftBindingError` if the mesh can't be bound to the cluster of `root`.
skin_handle = world.insert_deformable(skin, rp.SoftMeshBinding.skinned(), root)
# The mesh follows the particles: read its current vertices back (a NumPy array).
mesh = world.soft_bodies[jelly_handle].mesh_of(skin_handle)
skin_vertices = mesh.vertices
assert skin_vertices.shape == (6, 3)

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.