Several shapes on one body
Open the live demo · Read the source · View on GitHub
A table is not a box. Shaped as one, it stands on a slab where its legs should be, and a ball rolled under it hits nothing that is drawn. The physics core can build one body out of several shapes instead: a compound of up to sixty-four parts, each a sphere, box, capsule, cylinder, cone or hull, placed and turned in the compound's own frame. The body moves as one piece and touches the world with every part.
This page drops three of them onto a floor: a table of five boxes, a dumbbell of two balls and a capsule, and a hammer whose head is a hull. Each is dropped a little tilted, lands on one part first, and settles onto the rest. Compounds 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: Describe the parts #
A NativeCompoundPart is a shape and where it goes: at for its centre and
turn for how it is turned. A capsule and a cylinder stand along y, so the
dumbbell's bar and the hammer's handle are given a quarter turn about z to lie
along x. Each part here comes with the mesh that draws it, made to the same
sizes.
A hull is different, because the world keeps it. createHull takes the head's
eight corners and moves them so that the hull's centre of mass is at its
origin. hullOffset says by how much, and the part is placed with that
offset added, so the head ends up where its corners say. The head is
narrower at its face than at its back, which makes its centre sit off the
middle and shows why the offset is there.
/// A top and four legs, all boxes. The compound's origin is on the floor
/// under the middle of the table, where the legs end.
static List<_Piece> _table() => <_Piece>[
(
part: NativeCompoundPart(
NativeShape.box(Vector3(0.6, 0.025, 0.4)),
at: Vector3(0.0, 0.725, 0.0),
),
mesh: CuboidShape(size: Vector3(1.2, 0.05, 0.8)).build(),
),
for (final (double x, double z) in const <(double, double)>[
(-0.55, -0.35),
(0.55, -0.35),
(-0.55, 0.35),
(0.55, 0.35),
])
(
part: NativeCompoundPart(
NativeShape.box(Vector3(0.03, 0.35, 0.03)),
at: Vector3(x, 0.35, z),
),
mesh: CuboidShape(size: Vector3(0.06, 0.7, 0.06)).build(),
),
];
/// Two balls and the bar between them. A capsule stands along y, so the
/// bar is turned a quarter round z to lie along x.
static List<_Piece> _dumbbell() => <_Piece>[
for (final double x in const <double>[-0.35, 0.35])
(
part: NativeCompoundPart(
const NativeShape.sphere(0.16),
at: Vector3(x, 0.0, 0.0),
),
mesh: const SphereShape(radius: 0.16).build(),
),
(
part: NativeCompoundPart(
const NativeShape.capsule(0.035, 0.3),
orientation: _alongX,
),
mesh: const CapsuleShape(radius: 0.035, height: 0.6).build(),
),
];
/// A handle, a cylinder laid along x, and a head that is a hull: a block
/// that narrows towards its striking face. The world keeps the hull, and
/// moved its points so that its centre of mass is at its origin;
/// `hullOffset` says by how much, and the part is placed with it so the
/// head sits where its points say.
static List<_Piece> _hammer(NativeWorld world) {
final NativeHull head = world.createHull(_headPoints);
final Vector3 shift = world.hullOffset(head);
return <_Piece>[
(
part: NativeCompoundPart(
const NativeShape.cylinder(0.03, 0.3),
orientation: _alongX,
),
mesh: const CylinderShape(
radiusTop: 0.03,
radiusBottom: 0.03,
height: 0.6,
).build(),
),
(
part: NativeCompoundPart.hull(
head,
at: Vector3(0.36, 0.0, 0.0) + shift,
),
mesh: _headMesh(shift),
),
];
}
Step 2: One body, shaped as all of them #
createCompound makes the compound from the parts and setCompound shapes a
body as it. The parts are treated as one solid of even density. The core
moves all of them together so that their centre of mass is at the body's
origin, the point the body turns about and the one positionOf reports.
compoundOffset is that move. To put the compound's own origin somewhere,
the table's under the middle of its legs for instance, the body goes that much
further along, turned with the body.
/// One body shaped as [pieces], [mass] kilograms, with the compound's own
/// origin put at [at] and turned by [turn]. The core moved the parts by
/// `compoundOffset` to put their centre of mass on the body's origin, so
/// the body goes that much further along.
static _Thing _add(
NativeWorld world,
String name,
List<_Piece> pieces, {
required Vector3 at,
required Quaternion turn,
required double mass,
}) {
final NativeCompound compound = world.createCompound(<NativeCompoundPart>[
for (final _Piece p in pieces) p.part,
]);
final Vector3 offset = world.compoundOffset(compound);
final NativeBody body = world.addBody(
position: at + turn.asRotationMatrix().transformed(offset),
mass: mass,
);
world
..setCompound(body, compound)
..setOrientation(body, turn);
return _Thing(name, body, offset, pieces);
}
Step 3: Draw each part #
Every body gets a scene node, and every part a mesh under that node. A part's mesh sits where the core put the part: its place in the compound less the offset, with its own turn.
// A node follows each body; under it, a mesh for every part, where the
// part sits once the core has moved it by the offset.
for (final (int i, _Thing thing) in _things.indexed) {
final material = RenderMaterial(
name: thing.name,
baseColor: LinearColor.fromSrgb(
0.55 + 0.35 * math.sin(i * 1.3 + 0.4),
0.45 + 0.3 * math.sin(i * 2.1 + 1.5),
0.35 + 0.3 * math.sin(i * 0.7 + 2.6),
1.0,
),
roughness: 0.6,
);
final node = SceneNode(name: thing.name);
for (final (int j, _Piece piece) in thing.pieces.indexed) {
node.add(
MeshNode(
DeviceMesh.upload(context.device, piece.mesh),
material,
name: '${thing.name} part $j',
)
..setPositionFrom(piece.part.at - thing.offset)
..setRotation(piece.part.orientation),
);
}
_nodes.add(node);
scene.add(node);
}
Step 4: Follow the bodies #
Each frame the world steps a sixtieth of a second and every node takes its body's position and orientation. The parts come along as children. Every six seconds the three are dropped again.
/// Each node takes its body's place and turn from the core.
void _follow() {
final NativeWorld? world = _world;
if (world == null) return;
for (final (int i, _Thing thing) in _things.indexed) {
_nodes[i]
..setPositionFrom(world.localPositionOf(thing.body))
..setRotation(world.orientationOf(thing.body));
}
}
Step 5: What has to be true once they settle #
After four seconds all three are asleep. The table stands on its legs: the compound's origin, where the legs end, is on the floor to within a centimetre, and the top is level at 75 cm. Both of the dumbbell's balls touch the floor, so the bar lies level at their radius. The hammer lies on its head and on the far end of its handle, which is on the floor at the handle's radius. If the parts were not moved by the offset, or a part were missing from the contacts, one of these would be off by several centimetres.
for (var i = 0; i < 240; i++) {
world.step(_step);
}
for (final _Thing t in _things) {
if (!world.isAsleep(t.body)) {
throw StateError('the ${t.name} never came to rest');
}
}
// The table: its legs end at the compound's origin, so standing on them
// that origin is on the floor, a centimetre at most either way, and the
// top is level.
final Vector3 feet = pointOf('table', Vector3.zero());
final Vector3 top = pointOf('table', Vector3(0.0, 0.75, 0.0));
if (feet.y.abs() > 0.01 || (top.y - 0.75).abs() > 0.01) {
throw StateError('the table is not on its legs: feet $feet, top $top');
}
// The dumbbell: both balls on the floor, so the bar lies level at their
// radius.
for (final double x in const <double>[-0.35, 0.35]) {
final Vector3 ball = pointOf('dumbbell', Vector3(x, 0.0, 0.0));
if ((ball.y - 0.16).abs() > 0.01) {
throw StateError('a dumbbell ball rests at $ball, not on the floor');
}
}
// The hammer: the far end of its handle on the floor at the handle's
// radius, and its head low beside it, not propped up on the head alone.
final Vector3 end = pointOf('hammer', Vector3(-0.3, 0.0, 0.0));
final Vector3 head = pointOf('hammer', Vector3(0.36, 0.0, 0.0));
if ((end.y - 0.03).abs() > 0.01 || head.y > 0.07) {
throw StateError('the hammer rests at handle $end, head $head');
}
Note. A body touching something has one contact manifold with it, and a compound's parts all feed that one. Their contacts are joined along the normal of whichever part goes deepest, and a part whose own normal turns more than about eighteen degrees away from it is left out for that step. Against a flat floor every part pushes the same way and nothing is lost, but a compound wedged into a corner can be held by one side of it at a time. The mass is spread as if the parts were one solid, and where two parts overlap, as the dumbbell's bar does inside its balls, the overlap is counted twice.