flutter3d
Showcase Changelog 62 packages API reference

Joints that break

since 1.0.0-rc.1 Physics and particles

A joint in the physics core holds whatever it is asked to. A shelf on two brackets would carry a piano. setJointBreak gives a joint a force, and if it likes a torque, that it lets go past. At the end of a step in which the joint held its second body harder than that, the core takes the joint out, wakes both bodies, and raises a jointBroken event naming them.

On this page a shelf hangs on a wall from two brackets, and a crate is set on it every fifty steps until the brackets give way. The slider sets the force they break past. Breaking joints are the core's alone, so in the browser the page waits for the core to load and says so beside the viewport until it has.

Step 1: Hang the shelf #

The wall is a fixed body and the shelf a dynamic one of four kilograms. Each bracket is a fixed joint between them, which holds the shelf where it was against the wall, both place and turn. Joined bodies do not collide, so the shelf can sit against the wall without the two pushing apart. Each bracket then gets its limit. A limit of nought means never, and it is what a joint starts with.

/// A floor, a wall, and a four-kilogram shelf held to the wall by two
/// fixed joints. Each joint gives way once it holds the shelf with more
/// than [breakForce] newtons.
void _hang(NativeWorld world) {
  final NativeBody floor = world.addBody(
    position: Vector3(0.0, -0.5, 0.0),
    type: NativeBodyType.fixed,
    mass: 0.0,
  );
  world.setShape(floor, NativeShape.box(Vector3(3.0, 0.5, 2.0)));
  _wall = world.addBody(
    position: Vector3(0.0, 1.2, -0.35),
    type: NativeBodyType.fixed,
    mass: 0.0,
  );
  world.setShape(_wall, NativeShape.box(Vector3(1.2, 1.2, 0.1)));
  _shelf = world.addBody(position: Vector3(0.0, 1.4, 0.0), mass: 4.0);
  world.setShape(_shelf, NativeShape.box(Vector3(0.7, 0.03, 0.22)));
  _brackets = <NativeJoint>[
    for (final double x in _bracketsAt)
      world.createJoint(
        NativeJointType.fixed,
        _wall,
        _shelf,
        anchor: Vector3(x, 1.4, -0.22),
      ),
  ];
  for (final NativeJoint bracket in _brackets) {
    world.setJointBreak(bracket, force: breakForce);
  }
}

Step 2: Load it, step it, and listen #

Every fifty steps a three-kilogram crate is set down five centimetres above the shelf, each in its own place along it. The world steps, and the page keeps the jointBroken events. The other events the step raised, bodies falling asleep and contacts beginning, are read and dropped, so the world's queue never fills.

The two brackets share the load evenly. Each holds 19.6 N of empty shelf and 14.7 N more for every crate at rest. A crate landing, even from five centimetres, pulls far harder than that for a step. With the limit at 150 N the shelf carries four crates and goes when the fifth lands. At 80 N the first landing is enough.

/// One step: a three-kilogram crate set down five centimetres over the
/// shelf every fifty steps, the world stepped, and the breaks it raised
/// kept. The other events are read and let go, so none pile up.
void _tick(NativeWorld world) {
  if (_steps % 50 == 20 && _crates.length < _slots.length) {
    final NativeBody crate = world.addBody(
      position: Vector3(_slots[_crates.length], 1.6, 0.02),
      mass: 3.0,
    );
    world
      ..setShape(crate, NativeShape.box(Vector3.all(0.12)))
      ..setFriction(crate, 0.8);
    _crates.add(crate);
  }
  world.step(_step);
  _steps++;
  broken.addAll(
    world.readEvents().where((e) => e.kind == NativeEventKind.jointBroken),
  );
}

Step 3: Show what is left #

The shelf and the crates are drawn where the core has them. A bracket is drawn only while containsJoint still finds its joint, so it disappears in the step it breaks.

/// The shelf and the crates where the core has them; a bracket drawn for
/// as long as its joint is still in the world.
void _place() {
  final NativeWorld? world = _world;
  for (final (int i, MeshNode node) in _crateNodes.indexed) {
    node.isVisible = world != null && i < _crates.length;
    if (node.isVisible) {
      node
        ..setPositionFrom(world!.localPositionOf(_crates[i]))
        ..setRotation(world.orientationOf(_crates[i]));
    }
  }
  if (world == null) {
    _shelfNode.setPosition(0.0, 1.4, 0.0);
    return;
  }
  _shelfNode
    ..setPositionFrom(world.localPositionOf(_shelf))
    ..setRotation(world.orientationOf(_shelf));
  for (final (int i, NativeJoint bracket) in _brackets.indexed) {
    _bracketNodes[i].isVisible = world.containsJoint(bracket);
  }
}

Step 4: What has to happen #

Before the fifth crate, with four crates on the shelf, both brackets are still there and each holds 78.5 N, half of sixteen kilograms. By step three hundred both are gone, there were exactly two breaks, each naming the wall and the shelf, and the shelf is on the floor. If the limit were never read, the brackets would still be there. If the event lost a body, the names would not match.

// Four crates on: 16 kg, held half by each bracket, 78.5 N apiece, and
// under the 150 they break past.
runTo(210);
for (final NativeJoint bracket in _brackets) {
  if (!world.containsJoint(bracket)) {
    throw StateError('a bracket let go under four crates');
  }
  final double held = world.jointForce(bracket).y;
  if ((held - 78.5).abs() > 1.5) {
    throw StateError('a bracket holds ${held.toStringAsFixed(1)} N');
  }
}
// The fifth crate's landing takes both past it. Each break is an event
// that names the wall and the shelf, and the shelf ends on the floor.
runTo(300);
if (_brackets.any(world.containsJoint)) {
  throw StateError('a bracket held under five crates');
}
if (broken.length != 2 ||
    broken.any((e) => e.body != _wall || e.other != _shelf)) {
  throw StateError('the breaks were told as $broken');
}
final double shelfAt = world.localPositionOf(_shelf).y;
if (shelfAt > 0.1) {
  throw StateError('the shelf hangs at $shelfAt m with no brackets');
}

Note. A joint breaks on what it held over the last substep, so a short hard knock breaks it as surely as a steady load. That is how a real bracket behaves under an impact, but it also means the limit to set is higher than the weight the joint should carry at rest. How high depends on how things arrive, so it is worth trying with the drops a game actually has. When two joints share a load, as these brackets do, they often break within a few steps of each other.