Skip to main content

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::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 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.
let root: RigidBodyHandle = world.soft_bodies[jelly_handle].root_body();
assert!(world.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.
let _sensor = world.insert_collider(ColliderBuilder::ball(1.6).sensor(true), Some(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.
let anchor = world.insert_body(RigidBodyBuilder::fixed().translation(Vector::new(3.0, 5.0)));
world.insert_impulse_joint(anchor, root, SpringJointBuilder::new(2.0, 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:

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 over the top particles of the jelly: a rigid proxy that joints and
// colliders can attach to.
let top: Vec<u32> = {
    let jelly = &world.soft_bodies[jelly_handle];
    (0..jelly.num_particles() as u32)
        .filter(|&i| jelly.particle_position(i as usize).y > 2.0)
        .collect()
};
let cluster = world
    .add_soft_body_cluster(jelly_handle, &top)
    .expect("at least one valid particle");
let proxy: RigidBodyHandle = world.soft_bodies[jelly_handle]
    .cluster_proxy(cluster)
    .unwrap();
// A rigid plate welded onto the cluster.
let (plate, _) = world.insert(
    RigidBodyBuilder::dynamic().translation(Vector::new(3.0, 2.4)),
    ColliderBuilder::cuboid(1.2, 0.05).density(0.4),
);
world.insert_impulse_joint(
    plate,
    proxy,
    FixedJointBuilder::new().local_anchor1(Vector::new(0.0, -0.1)),
);
// A cluster can be pinned, driven or tuned as a whole.
let jelly = &mut 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 SoftBodyCluster::set_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.