flutter3d
Showcase Changelog 62 packages API reference

Cloth

since 0.7.0 Physics and particles

A ClothMesh is a grid of particles and the constraints between them: edges that resist stretching, and cross-edge pairs that resist folding. An XPBD solver advances it, which is what stays stable at a compliance of zero without a spring constant that has to be retuned every time the substep count changes. The solver is the run's physics, like a world's bodies: the C core where it starts, stepCloth in Dart where it does not.

Step 1: A sheet, and something in its way #

ClothMesh.grid pins the top row so the rest has something to hang from rather than falling forever. A ClothObstacle is a CollisionShape and a position, the same shapes the rest of this package's pages use, tested through expandedPlanes rather than through anything cloth-specific. The run's backend makes a ClothSimulation of the mesh, which steps the mesh's own arrays, so the page goes on reading ClothMesh.positions whichever backend moved them.

// Row zero is pinned, which is what stops the sheet falling forever:
// everything else hangs from it.
_cloth = ClothMesh.grid(
  cols: _cols,
  rows: _rows,
  spacing: _spacing,
  height: _hangs,
);
// Stepped on the run's physics: the core, or the Dart reference where
// the core cannot start. Either way it moves `_cloth` itself.
_simulation = usePhysics().cloth(_cloth);
_obstacle = ClothObstacle(
  CollisionSphere(_ballRadius),
  Vector3(0.68, 1.0, 0.6),
);

Step 2: Step it every frame #

Each call divides dt into ClothSettings.substeps XPBD substeps: gravity and damping predict a new position, the structural and bending constraints are solved against that prediction, and particles are pushed back outside every obstacle before the result is folded into velocity and position. Here it runs live, a step a frame: the sheet falls into place from lying flat, and then a ball swings through it and a gust of wind, which WindSettings applies per triangle as drag along its own normal, rises and falls. The gust is the world's wind: ClothSettings.inWorld gives the sheet its world's gravity, wind and air, so the same drag pushes less in thinner air. Wind sets how hard the gust blows; Swing the ball stops the ball where it is.

// A gust that rises and falls, blowing the sheet towards the viewer.
final double gust = wind * (0.5 + 0.5 * math.sin(_clock * 0.7));
_simulation!.step(
  ClothStep(
    // The sheet hangs in a world: its gravity, and its wind blowing in
    // its air. Drag 4, not 0.3: until 0.7.4 the wind was added as a
    // velocity, which made 0.3 several hundred times stronger than its
    // value.
    settings: ClothSettings.of(WorldProperties.standard)
        .copyWith(
          wind: WindSettings(
            drag: 4.0,
            airDensity: WorldProperties.standard.airDensity,
          ),
        )
        .inWorld(WorldProperties(wind: Vector3(0.0, 0.0, gust))),
    dt: _step,
    obstacles: <ClothObstacle>[_obstacle],
  ),
);

Step 3: What the sheet should do #

The pinned row never moves, because its inverse mass is zero and nothing an XPBD constraint does can reach a particle with no mass to correct. Left alone, the free edge should hang well below where it started, and a ball pushed into the sheet should never end up with a particle inside it.

// The pinned row never moves: its inverse mass is zero, so no force and
// no correction ever reaches it.
if (_cloth.positions[1] != _hangs) {
  throw StateError('the pinned row should not have moved');
}
// Left alone with the ball out of the way, the free edge has to sag
// well below the row it hangs from.
_obstacle.position.setValues(5.0, 5.0, 5.0);
for (var i = 0; i < 300; i++) {
  _simulation!.step(
    ClothStep(
      settings: ClothSettings.of(WorldProperties.standard),
      dt: _step,
    ),
  );
}
final int lastRow = (_rows - 1) * _cols;
for (var col = 0; col < _cols; col++) {
  final double y = _cloth.positions[3 * (lastRow + col) + 1];
  if (y > _hangs - 0.5 * (_rows - 1) * _spacing) {
    throw StateError('the free edge should have hung below its start');
  }
}
// And a ball pushed into the sheet must never end up inside it.
_obstacle.position.setValues(0.68, 1.0, 0.0);
for (var i = 0; i < 120; i++) {
  _simulation!.step(
    ClothStep(
      settings: ClothSettings.of(WorldProperties.standard),
      dt: _step,
      obstacles: <ClothObstacle>[_obstacle],
    ),
  );
}
for (var i = 0; i < _cloth.particleCount; i++) {
  final Vector3 at = Vector3(
    _cloth.positions[3 * i],
    _cloth.positions[3 * i + 1],
    _cloth.positions[3 * i + 2],
  );
  if (at.distanceTo(_obstacle.position) < _ballRadius - 0.03) {
    throw StateError('a particle passed through the ball');
  }
}

Note. This package has no scene graph of its own. The mesh on this page is rebuilt from ClothMesh.positions and ClothMesh.triangles every frame, with a normal at each particle worked out from the triangles that meet there, the same way the heightfield page draws its own terrain from a Float32List of samples.