soft_body_clusters

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.SOFT_FRAME (see RigidBody.is_soft_frame) 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 SoftBody.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 Collider.deformable_mesh_ref, which is how a collider reported by a scene query or by a collision event is traced back to the body it covers.

# The rigid body the engine created for the whole soft body, read back after its insertion.
root = world.soft_bodies[jelly_handle].root_body
assert world.rigid_bodies[root].is_soft_frame

# A rigid collider attached to it follows the frame of the whole body: here a sensor
# detecting what comes close to the jelly.
sensor = world.add_collider(rp.Collider.ball(1.0).sensor(True), parent=root)

# 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.
anchor = world.add_body(rp.RigidBody.fixed(translation=(3.0, 4.0, 0.0)))
world.impulse_joints.insert(anchor, root, rp.SpringJointBuilder(2.5, 60.0, 2.0))

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 (PhysicsWorld.add_soft_body_cluster), 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:

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.

A cluster is identified by its index in the soft-body, returned by add_soft_body_cluster (which returns None if none of the given particles is valid), and its proxy is given by SoftBody.cluster_proxy. Snapshots of the live clusters of a body (their index, particles, and proxy) are given by the clusters property of SoftBody, and the cluster a proxy stands for by the soft_body and soft_cluster properties of its RigidBody:

# A cluster over the top particles of the jelly: a rigid proxy that joints and
# colliders can attach to.
positions = world.soft_bodies[jelly_handle].particle_positions
top = np.flatnonzero(positions[:, 1] > 1.3)
cluster = world.add_soft_body_cluster(jelly_handle, top)
assert cluster is not None, "at least one valid particle"
proxy = world.soft_bodies[jelly_handle].cluster_proxy(cluster)
# A rigid plate welded onto the cluster.
plate = world.add_body(
    rp.RigidBody.dynamic(translation=(3.0, 1.9, 0.0)),
    colliders=[rp.Collider.cuboid(0.7, 0.05, 0.7).density(0.4)],
)
world.impulse_joints.insert(
    plate, proxy, rp.FixedJointBuilder().local_anchor1((0.0, -0.1, 0.0))
)
# A cluster can be pinned, driven or tuned as a whole.
jelly = world.soft_bodies[jelly_handle]
jelly.set_cluster_stiffness_scale(cluster, 2.0)
jelly.enable_cluster_shape_matching(cluster, True)

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

• The stiffness scale (set_cluster_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 (set_cluster_edge_softness) overrides the softness of every edge entirely contained in the cluster, e.g., a stiffer collar on a shirt.
• The tear resistance (set_cluster_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 (enable_cluster_shape_matching) pulls the particles of the cluster toward the frame of its proxy (or toward the target pose given by set_cluster_shape_matching_target), so that part of the body tends to keep the shape it was created with.

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.