flutter3d
Showcase Changelog 62 packages API reference

A chain that does not stretch

since 1.0.0-rc.1 Physics and particles

An ordinary joint is a constraint between two free bodies. Each step the solver pulls the two sides back together, but only so far, and a light link between a heavy weight and the rest of the chain cannot pull hard enough. The chain stretches. A multibody on the physics core holds the same joints in reduced coordinates. Each link is placed from its parent by its joint's angle or travel and nothing else, so there is no gap for a joint to open.

This page lays the same chain out twice and lets it go. Twelve links of 0.1 kg each, 0.3 m long, with a weight of 10 kg on the end. The left chain is held by ordinary hinge joints and the right one is a multibody. Each link turns red as the joint above it opens.

Step 1: One chain, laid out level #

Both chains are made by one function: a fixed post, then the links in a level row from it, then a ball for the weight. How each body is held to the one before it is the only argument, so that is all that differs between the two.

/// A post at [x] and a chain laid out level from it to +x: twelve links
/// 0.3 m long and 0.1 kg each, then a ball of [weight] kg. [join] holds
/// each body to the one before it, link [parent] of [bodies], at
/// [anchor].
List<NativeBody> _lay(
  NativeWorld world,
  double x,
  void Function(List<NativeBody> bodies, int parent, Vector3 anchor) join,
) {
  final NativeBody post = world.addBody(
    position: Vector3(x, _height, 0.0),
    type: NativeBodyType.fixed,
    mass: 0.0,
  );
  world.setShape(post, NativeShape.box(Vector3.all(0.05)));
  final bodies = <NativeBody>[post];
  for (var k = 0; k <= _count; k++) {
    final bool last = k == _count;
    final double near = x + k * 2 * _half;
    final NativeBody body = world.addBody(
      position: Vector3(near + (last ? _radius : _half), _height, 0.0),
      mass: last ? weight : 0.1,
    );
    world.setShape(
      body,
      last
          ? const NativeShape.sphere(_radius)
          : NativeShape.box(Vector3(_half, 0.03, 0.03)),
    );
    bodies.add(body);
    join(bodies, k, Vector3(near, _height, 0.0));
  }
  return bodies;
}

Step 2: Joints on the left, a multibody on the right #

On the left, createJoint puts a revolute joint about z between each body and the one before it, at the point they share. On the right, createMultibody roots a tree at the post, and addLink hangs each body under its parent on a revolute joint at the same point, about the same axis. A fixed root is a fixed base; a dynamic one would float. The link indices count from the root at nought, so link k's parent is k − 1. The angle where a link is added is its joint's nought.

A link also takes limits (setLinkLimits) and a motor (setLinkMotor), and linkJoint reads its angle or travel and speed back. This page uses none of them.

/// The left chain on ordinary hinges about z, each a constraint the
/// solver pulls closed; the right one a multibody, rooted at its post,
/// each link placed from its parent by one angle about z.
void _restart() {
  _world?.dispose();
  final NativeWorld? world = _world = _open();
  _age = 0.0;
  if (world == null) return;
  final Vector3 z = Vector3(0.0, 0.0, 1.0);
  _joints = _lay(world, _left, (bodies, parent, at) {
    world.createJoint(
      NativeJointType.revolute,
      bodies[parent],
      bodies.last,
      anchor: at,
      axis: z,
    );
  });
  NativeMultibody? chain;
  _multibody = _lay(world, _right, (bodies, parent, at) {
    chain ??= world.createMultibody(bodies.first);
    world.addLink(
      chain!,
      bodies.last,
      parent: parent,
      type: NativeJointType.revolute,
      anchor: at,
      axis: z,
    );
  });
}

Step 3: How far a joint is open #

Two ends that should meet: the parent's far end and the link's near end, each where its own body is now. On the post the anchor is its centre, and on the weight it is the edge of the ball.

/// How far apart the two sides of the joint above link [k] of [bodies]
/// are, m: the parent's far end against the link's near end, each where
/// its own body has it now. Nought for a joint that holds.
double _gap(List<NativeBody> bodies, int k) {
  final NativeWorld world = _world!;
  Vector3 end(NativeBody body, double along) =>
      world.localPositionOf(body) +
      world
          .orientationOf(body)
          .asRotationMatrix()
          .transformed(Vector3(along, 0.0, 0.0));
  final NativeBody parent = bodies[k - 1];
  final NativeBody link = bodies[k];
  return (end(parent, k == 1 ? 0.0 : _half) -
          end(link, k == bodies.length - 1 ? -_radius : -_half))
      .length;
}

/// The widest joint of [bodies] now.
double _widest(List<NativeBody> bodies) => <double>[
  for (var k = 1; k < bodies.length; k++) _gap(bodies, k),
].reduce(math.max);

Step 4: Drawing it #

Every link is drawn where the core has it, reddening as the joint above it opens, fully red at three centimetres. The world steps once a frame and lets go of both chains again every ten seconds. Move Weight on the end to change the weight: at a kilogram the ordinary chain opens by about a centimetre at its worst joint, and at twenty by more than twenty. The multibody stays white throughout.

/// Every link where the core has it, reddening as the joint above it
/// opens: fully red at three centimetres.
void _place() {
  if (_world == null) return;
  for (final (List<NativeBody> bodies, List<MeshNode> meshes, paint)
      in <(List<NativeBody>, List<MeshNode>, List<RenderMaterial>)>[
        (_joints, _jointMeshes, _jointPaint),
        (_multibody, _multibodyMeshes, _multibodyPaint),
      ]) {
    for (var k = 1; k < bodies.length; k++) {
      meshes[k - 1]
        ..setPositionFrom(_world!.localPositionOf(bodies[k]))
        ..setRotation(_world!.orientationOf(bodies[k]));
      final double open = math.min(_gap(bodies, k) / 0.03, 1.0);
      paint[k - 1].baseColor = LinearColor.fromSrgb(
        0.8 + 0.15 * open,
        0.8 - 0.65 * open,
        0.78 - 0.65 * open,
        1.0,
      );
    }
  }
}

Step 5: What the two should show #

Two seconds from level, with ten kilograms on the end. Every joint of the multibody stays shut to within a millimetre (the core keeps them within a thousandth of one). Some joint of the ordinary chain opens by more than a centimetre, four on macOS. The multibody's weight has swung well below its post.

// Two seconds from level with ten kilograms on the end. The core holds
// every multibody joint to a thousandth of a millimetre, and lets an
// ordinary one open by four centimetres.
weight = 10.0;
final (:double joints, :double multibody) = widestOver(120);
if (multibody > 1e-3) {
  throw StateError('a multibody joint opened by $multibody m');
}
if (joints < 1e-2) {
  throw StateError('the ordinary chain held to $joints m');
}
// And the multibody has swung: its weight is well below its post.
final double low = _world!.localPositionOf(_multibody.last).y;
if (low > _height - 2.0) {
  throw StateError('the multibody weight is still at $low');
}

Note. The links of a multibody still move freely within a step, with their contacts, and are put back where their joints say after it. A contact the step resolved can be partly undone by that. A spherical link turns freely: there is no cone limit on it yet. A multibody has at most 32 links and 64 degrees of freedom.