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