soft_body_creation_and_insertion

A soft-body is described by a SoftBodyBuilder, which constructors build the lattice of the most common shapes:

Constructor	Dimension	Lattice
`rope`	2D, 3D	Structural and bending edges between the particles of a line.
`cloth`, `cloth_anisotropic`, `cloth_tube`	3D	Structural, shear and bending edges, with a triangle surface.
`grid`	2D	Triangle cells filling a rectangle.
`cuboid`	3D	Tetrahedral cells filling a box.
`polygon`, `disk`	2D	A closed boundary preserving its area.
`sphere`	3D	A closed surface preserving its volume, with dihedral bending constraints.
`trimesh`, `polyline`	2D, 3D (`trimesh`), 2D (`polyline`)	The vertices and edges of a mesh, held by shape matching.
`volumetric`	2D, 3D	Cells filling a closed mesh.

The volumetric constructor is the one to use for an arbitrary solid: it fills a closed mesh (segments in 2D, triangles in 3D, oriented outward) with cells of about the requested size. The interior of the mesh is triangulated by Delaunay refinement in 2D, whereas in 3D every cell of a lattice the mesh reaches is kept whole: the result contains the mesh instead of following it exactly, and its boundary is as blocky as its cells. The meshing parameters are spelled out by volumetric_with: the size of the cells, how much the cover is smoothed and subdivided around the boundary in 3D, i.e., how closely it follows the mesh, and whether the surface alone is covered, leaving the interior empty.

Example 2D
Example 3D

// Fill a closed, counter-clockwise polyline with triangle cells of about 0.2 in size.
let vertices = vec![
    Vector::new(-0.5, -0.25),
    Vector::new(0.5, -0.25),
    Vector::new(0.5, 0.25),
    Vector::new(-0.5, 0.25),
];
let indices = vec![[0, 1], [1, 2], [2, 3], [3, 0]];
let block = SoftBodyBuilder::volumetric(&vertices, &indices, 0.2)
    .expect("the polyline must be closed and enclose some area")
    .translated(Vector::new(-3.0, 1.0));
let _block_handle = world.insert_soft_body(block);

// Fill a closed, outward-oriented triangle mesh with tetrahedral cells of about 0.2 in size.
let (vertices, indices) = Cuboid::new(Vector::new(0.5, 0.25, 0.25)).to_trimesh();
let block = SoftBodyBuilder::volumetric(&vertices, &indices, 0.2)
    .expect("the mesh must be closed and enclose some volume")
    .translated(Vector::new(-3.0, 1.0, 0.0));
let _block_handle = world.insert_soft_body(block);

The builder allows the definition of everything else that is specific to one soft-body: the particles held in place (the pinned particles, pinned_particles), the softness of its constraints (softness), the mass of its particles (one mass for every particle with particle_mass, a total mass for the whole body with mass, or one mass per particle with masses), their radius (particle_radius), the collider its surface is made of, and whether that surface is allowed to collide with itself (self_contacts). The particles can also be given a linear damping (linear_damping), a gravity scale (gravity_scale), a dominance group (SoftBodyParticleSettings::dominance_group), and be allowed to sleep or not (can_sleep), exactly like a rigid-body. Inserting the soft-body into the world (PhysicsWorld::insert_soft_body) will automatically create the rigid-body standing for it (its root body), as well as the colliders covering its surface:

Example 2D
Example 3D

// A world with a ground.
let mut world = PhysicsWorld::new();
world.insert_collider(ColliderBuilder::cuboid(10.0, 0.1), None);

// Builder for a rope of 20 particles between two points.
let _ = SoftBodyBuilder::rope(Vector::new(0.0, 3.0), Vector::new(2.0, 3.0), 20);
// Builder for a grid of `nx` by `ny` particles filled with triangle cells.
let _ = SoftBodyBuilder::grid(Vector::new(3.0, 1.0), Vector::new(1.0, 1.0), 6, 6);
// Builder for a disk: a ring of particles holding its area (a pressurized blob).
let _ = SoftBodyBuilder::disk(Vector::new(0.0, 3.0), 0.8, 24);
// Builder for a closed polygon of particles holding its area.
let _ = SoftBodyBuilder::polygon(vec![
    Vector::new(5.0, 4.0),
    Vector::new(7.0, 4.0),
    Vector::new(7.0, 6.0),
    Vector::new(5.0, 6.0),
]);
let n = 20;
let sheet = SoftBodyBuilder::grid(Vector::new(-3.0, 3.0), Vector::new(1.0, 1.0), n, n)
    // Particles held in place.
    .pinned_particles([0, (n - 1) as u32])
    // A uniform softness (natural frequency in Hz, damping ratio) for every constraint.
    .softness(SpringCoefficients::new(30.0, 1.0))
    // The mass of each particle.
    // Default: 1.0
    .particle_mass(0.05)
    // The thickness of the particles, for collisions.
    // Default: 0.01
    .particle_radius(0.05)
    // The template of the body's colliders: its shape is replaced by the deformable surface.
    .surface_collider(ColliderBuilder::ball(0.05).friction(0.8))
    // Whether the body may fall asleep.
    // Default: true
    .can_sleep(true);
// Insert the soft body: this creates its hidden root rigid body and its colliders.
let sheet_handle = world.insert_soft_body(sheet);

// A world with a ground.
let mut world = PhysicsWorld::new();
world.insert_collider(ColliderBuilder::cuboid(10.0, 0.1, 10.0), None);

// Builder for a rope of 20 particles between two points.
let _ = SoftBodyBuilder::rope(Vector::new(0.0, 3.0, 0.0), Vector::new(2.0, 3.0, 0.0), 20);
// Builder for a cloth: `nu` by `nv` particles, particle `(i, j)` at `origin + i * du + j * dv`.
let _ = SoftBodyBuilder::cloth(
    Vector::new(-1.0, 2.0, -1.0),
    Vector::new(0.1, 0.0, 0.0),
    Vector::new(0.0, 0.0, 0.1),
    20,
    20,
);
// Builder for a box of `nx * ny * nz` particles filled with tetrahedral cells.
let _ = SoftBodyBuilder::cuboid(Vector::new(3.0, 1.0, 0.0), Vector::splat(0.5), 4, 4, 4);
// Builder for a hollow sphere holding its volume (a balloon).
let _ = SoftBodyBuilder::sphere(Vector::new(0.0, 3.0, 3.0), 0.8, 2);
// Builder over raw particle positions; the elements are added by the setters.
let n = 20;
let cloth = SoftBodyBuilder::cloth(
    Vector::new(-1.0, 2.0, -1.0),
    Vector::new(0.1, 0.0, 0.0),
    Vector::new(0.0, 0.0, 0.1),
    n,
    n,
)
// Particles held in place.
.pinned_particles([0, (n - 1) as u32, (n * (n - 1)) as u32, (n * n - 1) as u32])
// A uniform softness (natural frequency in Hz, damping ratio) for every constraint.
.softness(SpringCoefficients::new(30.0, 1.0))
// The mass of each particle.
// Default: 1.0
.particle_mass(0.05)
// The thickness of the particles, for collisions.
// Default: 0.01
.particle_radius(0.02)
// The template of the body's colliders: its shape is replaced by the deformable surface.
.surface_collider(ColliderBuilder::ball(0.05).friction(0.8))
// Whether the surface collides with itself.
// Default: false
.self_contacts(true)
// Whether the body may fall asleep.
// Default: true
.can_sleep(true);
// Insert the soft body: this creates its hidden root rigid body and its colliders.
let cloth_handle = world.insert_soft_body(cloth);

info

The collider given to SoftBodyBuilder::surface_collider is only a template: its shape is replaced by the deformable surface of the soft-body, and its density is ignored, whereas all its other properties are kept. Therefore this is where the friction, the collision groups, or the active events of the soft-body must be set. A body that should only collide through colliders of your own can be built without any default one (no_surface_collider).

tip

Two builders can be merged into a single soft-body with append, and their pieces sewn together with additional edges (add_edges), which rest length is the distance their particles have when they are added. This is, e.g., how the sleeves of a shirt are attached to its body.