Module soft_body 

Components describing soft bodies: deformable bodies made of particles linked by elastic constraints, simulated together with the rigid-bodies.

Entities and conventions

A soft body is created by inserting a SoftBody component on an entity. The positions of the soft body’s particles given by its SoftBodyBuilder are expressed in the local frame of that entity: they are transformed by the entity’s GlobalTransform when the soft body is created. After its creation, the particles live in world space and the plugin drives the entity’s Transform: it follows the pose of the soft body’s whole-body proxy (the frame of its whole-body cluster: its origin is the centroid of the free particles, and its rotation the best fit of the particles onto their rest shape, identity at creation), its scale is kept. The colliders of children entities are attached to that proxy, so their entities stay where their colliders are. A mesh synchronized with [SoftBodyMeshSync] is expressed in that frame. The mass-weighted center of the particles is written to SoftBodyState::center_of_mass.

The soft body entity also stands for the Rapier objects created with the soft body:

• its surface colliders (their user_data holds the entity bits), so collision events, contact pairs and scene queries report the soft body entity as the collider entity;
• its hidden proxy rigid-bodies, so contact pairs report it as the rigid-body entity;
• its whole-body proxy rigid-body in particular (the proxy of its whole-body cluster, see RapierRigidBodySet::soft_body_whole_proxy): the entity is mapped to it, so impulse joints can attach the whole soft body like a rigid-body, with the soft body entity as their parent or by adding them to the soft body entity.

SoftBodyCluster entities stand for their own cluster proxy rigid-body, which impulse joints and colliders can be attached to like to any rigid-body. A cluster (or the whole-body cluster of a soft body entity) can be driven with the SoftBodyClusterPinned, SoftBodyClusterKinematicTarget, SoftBodyClusterShapeMatching and SoftBodyClusterMaterial components.

When a soft body tears, the particle indices of its SoftBodyPinnedParticles, SoftBodyKinematicTargets, SoftBodyAttachments, SoftBodyExternalForce and SoftBodyExternalImpulse components (and the pinned particles of its SoftBody builder, restored when SoftBodyPinnedParticles is removed) are remapped to the renumbered particles, the entries of the particles moved to a new piece being moved to the entity of that piece. When a tear splits a cluster, the entity spawned for the new cluster inherits the SoftBodyClusterPinned, SoftBodyClusterKinematicTarget (shifted so that the particles keep their targets), SoftBodyClusterShapeMatching and SoftBodyClusterMaterial components of the split cluster’s entity.

Modifying the SoftBody component after the soft body was created has no effect. Use the other components of this module, or the helpers of RapierRigidBodySet and RapierContextMut, to control it at runtime. Removing the SoftBody component or despawning its entity removes the soft body from the simulation.

Structs

DeformableCollider

Turns the Collider of this entity into a deformable collider bound to the particles of a soft body.

DeformableColliderError

Inserted on an entity whose DeformableCollider could not be created.

RapierSoftBody

A deformable body: SoftBodyParticles linked by elastic elements (SoftBodyEdges, bending, SoftBodyCells, volume preservation, shape matching). Its hidden root rigid body (tagged by crate::dynamics::RigidBody::soft_body) must never be moved, removed or attached to joints.

RapierSoftBodyCluster

A cluster of a soft body: a set of its particles backed by a proxy rigid body (crate::dynamics::RigidBodyType::SoftFrame) carrying its frame, gathered velocity and reduced mass. A rank-deficient one (one particle, or collinear in 3D) has no angular response.

RapierSoftBodyHandle

The Rapier handle of a SoftBody that was inserted to the physics scene.

RapierSoftBodyMaterial

The stiffness and damping of every soft-body constraint family: a natural_frequency (Hz) and damping_ratio per family, normalized by the constraint’s effective mass (independent of mass, substeps and timestep); a frequency far above the substep rate saturates instead of exploding.

RapierSoftBodyTearEvent

What a tear or a cut did to a soft body (see EventHandler::handle_soft_body_tear_event, crate::dynamics::SoftBodySet::tear and crate::dynamics::SoftBodySet::cut); the indices of torn_edges/torn_cells predate the tear, the others follow it, before the split.

SoftBodiesSettings

Simulation settings shared by every soft body of a world.

SoftBody

Describes a soft body to create.

SoftBodyAttachment

A particle of a soft body attached to a rigid-body entity (see SoftBodyAttachments).

SoftBodyAttachments

Particles of a soft body attached to rigid-bodies by two-way point-to-point constraints.

SoftBodyBuilder

A builder for crate::dynamics::SoftBodys: particles are given in world space and elements reference particles by index. The generators (Self::rope, plus cloth/cuboid/sphere in 3D and polygon/disk/grid in 2D) make complete bodies; the setters build any body.

SoftBodyCell

A simplex cell of a soft body: a triangle in 2D, a tetrahedron in 3D.

SoftBodyCluster

A cluster of particles of a soft body, backed by a proxy rigid-body.

SoftBodyClusterKinematicTarget

The world-space pose a pinned cluster is moved to.

SoftBodyClusterMaterial

Regional material overrides of the elements (cells and edges) fully contained in a cluster.

SoftBodyClusterPinned

Pins every particle of a cluster: the cluster becomes a fixed region dragging the rest of its soft body, and can be moved with a SoftBodyClusterKinematicTarget.

SoftBodyClusterShapeMatching

Enables the shape matching of the particles of a cluster toward the cluster’s frame, or toward a target pose.

SoftBodyDisabled

Add this component to disable a soft body: it is left where it is, without colliders or constraints, until this component is removed.

SoftBodyEdge

A distance constraint between two particles of a soft body.

SoftBodyExternalForce

Persistent forces applied to the particles of a soft body.

SoftBodyExternalImpulse

One-time impulses applied to the particles of a soft body.

SoftBodyHandle

The unique handle of a soft body added to a super::SoftBodySet.

SoftBodyKinematicTargets

World-space kinematic targets of pinned particles, as (particle index, target) pairs.

SoftBodyMaterial

The material (stiffness, damping, plasticity and tearing) of a soft body.

SoftBodyParticle

One particle (point mass) of a soft body: plain state owned by its crate::dynamics::SoftBody, given its own solver body for the step when the body is awake. A pinned particle (inv_mass == 0) is kinematic: it moves at its velocity or toward its target.

SoftBodyParticleSettings

The dynamics settings shared by every particle of a soft body.

SoftBodyPiece

A soft body a tear left: the torn body itself, or a body split off it (see SoftBodyTearEvent::pieces).

SoftBodyPinnedParticles

The particles of a soft body that are pinned (kinematic).

SoftBodyState

The state of a soft body, written back after each simulation step.

SoftBodyVolumeFactor

The multiplier applied to the rest area (2D) or volume (3D) of a soft body to obtain the target of its volume preservation (> 1 inflates the soft body).

SoftClusterRemoval

What crate::dynamics::SoftBodySet::remove_cluster (or removing a proxy rigid body) deleted: the particles only the removed cluster covered, and everything attached to them.

SoftClusterSplit

A cluster piece a tear left: where a cluster the crack ran through ended up (see SoftBodyTearEvent::clusters).

SoftCollisionMesh

A mesh a soft body collides through: a polyline (2D) or triangle mesh (3D) whose vertices follow the body’s particles, and the collider holding it. A skinned mesh carries thin features the coarse cells cannot: its vertices are barycentric combinations of the particles.

SoftContactImpulse

The impulse a contact slot reported (see SoftPairContacts::impulses).

SoftJointMove

An impulse joint a tear re-attached: its proxy was split, and the piece closest to the joint’s anchor in the rest shape is not the one that kept the proxy (see SoftBodyTearEvent::moved_joints).

SoftMeshBinding

How a deformable collider follows its soft body, and the collision settings that are not the collider’s own.

SoftMeshId

Where a collision mesh lives in its soft body: the cluster owning it, and its slot in that cluster. Stable for the mesh’s whole life (removed meshes leave a dead slot).

SoftMeshRef

A collision mesh of a given soft body: what a deformable collider points back to.

SoftPairContacts

The contacts of a pair of two soft surfaces: the candidates the narrow phase detected between them, which the soft-body solver turns into constraints, rebuilt by every update of the pair. Each slot (vertex-pass, edge, then volume-bin candidates) reports the solver’s impulse.

SoftParticleAttachment

A particle of a soft body attached to a rigid body (see SoftBody::attach_particle): a point-to-point constraint between the particle and a point of the body.

SoftRecoverySettings

Runtime configuration of the soft-body tangle detection and recovery stack. It lives on crate::dynamics::SoftBodiesSettings::recovery (itself on IntegrationParameters::soft_bodies), so it can be changed between steps.

SoftVolumePiece

A piece of a soft body’s material enclosed by closed boundary elements (see SoftBody::volume_pieces): its volume constraint holds the area/volume it encloses at its rest one times the body’s volume factor.

Enums

PairContacts

The contacts of a ContactPair, with a fixed layout: the solver addresses a pair’s manifolds through raw pointers (see ManifoldStore), so the offset of the rigid contacts must not depend on the value.

SoftBindingError

Why a mesh could not be bound to a cluster (crate::geometry::ColliderSet::insert_deformable).

SoftBodyCellModel

The constitutive model of a soft body’s cells (triangles in 2D, tetrahedra in 3D).

SoftBodyEdgeKind

The role of a soft-body edge (distance constraint).

SoftEdgePlasticFlow

Which strains make a soft-body edge flow plastically (see SoftBodyMaterial::edge_plastic_yield).

SoftMeshBindingMode

How a collision mesh should be bound to its cluster, requested at insertion (crate::geometry::ColliderSet::insert_deformable).

SoftPatchConstraints

What the per-point constraints of the features a volume constraint acts on do (see SoftRecoverySettings::overlap_patch_constraints).