Joints and motors
Open the live demo · Read the source · View on GitHub
A joint holds two bodies to each other, so that they can still move in some ways and not in others. The physics core has five kinds: fixed, spherical (a ball joint), revolute (a hinge), prismatic (a slider) and distance. This page puts four of them in a row. From the left: a hinge that swings into its limits, a slider driven by a motor, a ball joint held in a cone, and one distance joint made three ways, as a rod, as a spring and as a rope.
Joints belong to the core's NativeWorld. The Dart reference has none, so
when the core will not start this page shows the row standing still and says
why beside the viewport.
Every joint here joins a moving body to a fixed one. A fixed body is made
with NativeBodyType.fixed and a mass of nought. It does not need a shape,
because nothing has to touch it.
Step 1: A hinge with limits #
createJoint(NativeJointType.revolute, a, b, anchor:, axis:) pins the two
bodies together at the anchor and lets them turn about the axis only. Both
are given in world space, and the joint is taken from where the bodies stand
when it is made: that pose is angle nought. setJointLimits then keeps the
angle between a lower and an upper bound, in radians. The bar starts hanging
straight down and spinning fast enough to reach half a radian, so it keeps
running into both stops.
/// A bar hung from a pin, free to turn about z but only half a radian
/// either way, and started swinging hard enough to reach both stops.
static void _hinge(_Row row) {
final NativeWorld w = row.world;
final NativeBody pin = _fixed(w, _hingeAt);
row.arm = w.addBody(position: _hingeAt - Vector3(0.0, 0.6, 0.0), mass: 2.0);
w.setShape(row.arm, NativeShape.box(Vector3(0.06, 0.6, 0.06)));
row.hinge = w.createJoint(
NativeJointType.revolute,
pin,
row.arm,
anchor: _hingeAt,
axis: Vector3(0.0, 0.0, 1.0),
);
w
..setJointLimits(row.hinge, JointLimits(lower: -_limit, upper: _limit))
// Five radians a second about the pin; its centre, 0.6 m below,
// moves at three metres a second.
..setAngularVelocity(row.arm, Vector3(0.0, 0.0, 5.0))
..setVelocity(row.arm, Vector3(3.0, 0.0, 0.0));
}
Step 2: A slider and its motor #
A prismatic joint is the same call with NativeJointType.prismatic. The
carriage can only slide along the axis, and it cannot turn at all. Its
limits are now a travel in metres. setJointMotor drives the joint at a
speed, here 0.6 m/s, pushing with no more than the force it is given. A
motor of speed nought with a small force works as friction in the joint.
The motor does not turn round by itself at the end of the rail. The page
watches jointValue, which reads a slider's travel, and turns the motor
round near each end.
/// A carriage on a rail along x, its travel limited to 0.8 m each way
/// and a motor driving it at [speed] with at most forty newtons.
static void _slider(_Row row, double speed) {
final NativeWorld w = row.world;
final NativeBody rail = _fixed(w, _railAt);
row.cart = w.addBody(position: _railAt.clone(), mass: 1.0);
w.setShape(row.cart, NativeShape.box(Vector3(0.15, 0.1, 0.15)));
row.slider = w.createJoint(
NativeJointType.prismatic,
rail,
row.cart,
anchor: _railAt,
axis: Vector3(1.0, 0.0, 0.0),
);
w
..setJointLimits(row.slider, JointLimits(lower: -_travel, upper: _travel))
..setJointMotor(row.slider, JointMotor(speed: speed, maxForce: 40.0));
}
/// Turns the motor round at either end of the rail, so the carriage runs
/// back and forth.
void _drive(_Row row) {
final double at = row.world.jointValue(row.slider);
if (at > _travel - 0.05 && _speed > 0 ||
at < -_travel + 0.05 && _speed < 0) {
_speed = -_speed;
row.world.setJointMotor(
row.slider,
JointMotor(speed: _speed, maxForce: 40.0),
);
}
}
Step 3: A ball joint in a cone #
A spherical joint holds one point of each body together and lets them turn
any way about it. Its axis, here straight down along the limb, is what two
limits are measured from. setJointCone keeps the limb's swing within an
angle of that axis, like a shoulder. setJointLimits on a ball joint limits
its twist about the axis. setJointFriction resists turning with a set
torque, so the limb settles instead of swinging forever. A ragdoll's joints
are built from this.
/// A limb hung from a ball joint: it swings any way, but its axis stays
/// within 0.6 rad of straight down, its twist about itself within ±0.3,
/// and a little friction lets it settle.
static void _ball(_Row row) {
final NativeWorld w = row.world;
final NativeBody shoulder = _fixed(w, _shoulderAt);
row.limb = w.addBody(position: _shoulderAt - Vector3(0.0, 0.5, 0.0));
w.setShape(row.limb, NativeShape.box(Vector3(0.05, 0.5, 0.05)));
row.ball = w.createJoint(
NativeJointType.spherical,
shoulder,
row.limb,
anchor: _shoulderAt,
axis: Vector3(0.0, -1.0, 0.0),
);
w
..setJointCone(row.ball, _cone)
..setJointLimits(row.ball, JointLimits(lower: -_twist, upper: _twist))
..setJointFriction(row.ball, 0.2)
..setVelocity(row.limb, Vector3(4.0, 0.0, 2.0))
..setAngularVelocity(row.limb, Vector3(-4.0, 8.0, 8.0));
}
Step 4: One distance joint, three ways #
createDistanceJoint holds a point on one body at a distance from a point on
another. The distance is the one between the two points when the joint is
made. As it comes, the joint is a rod. setJointLength gives it a rest
length and a least and a most it may be stretched to. setJointSpring gives
it a frequency and damping, and with those it pulls back towards the rest
length like a spring. With a spring of nought hertz and a least of nought,
nothing pulls at all until the joint reaches its most, so it is a rope:
slack until it is taut. The rope's weight starts beside its hook, falls
freely and is caught.
/// One distance joint, made three ways. It is made at the length between
/// its two points now, which is a rod. A spring is the same joint with a
/// rest length, a least and a most, and a frequency. A rope is a spring
/// of nought hertz that may be anything from nought to its most: slack
/// until it is taut.
static void _distances(_Row row) {
final NativeWorld w = row.world;
NativeJoint hang(Vector3 hook, NativeBody weight) => w.createDistanceJoint(
_fixed(w, hook),
weight,
anchorA: hook,
anchorB: w.localPositionOf(weight),
);
NativeBody weight(Vector3 at) {
final NativeBody b = w.addBody(position: at);
w.setShape(b, const NativeShape.sphere(0.15));
return b;
}
// A rod 1.5 m long, the weight pushed sideways.
row.rodWeight = weight(_hooks[0] - Vector3(0.0, _rodLength, 0.0));
row.rod = hang(_hooks[0], row.rodWeight);
w.setVelocity(row.rodWeight, Vector3(3.0, 0.0, 0.0));
// A spring that rests at 1.2 m, let go stretched to 1.5.
row.springWeight = weight(_hooks[1] - Vector3(0.0, 1.5, 0.0));
row.spring = hang(_hooks[1], row.springWeight);
w
..setJointLength(
row.spring,
length: _springLength.length,
least: _springLength.least,
most: _springLength.most,
)
..setJointSpring(row.spring, JointSpring(hertz: 1.2, damping: 0.05));
// A rope 1.5 m long, its weight let go beside the hook: it falls
// slack until the rope catches it.
row.ropeWeight = weight(_hooks[2] + Vector3(0.3, -0.2, 0.0));
row.rope = hang(_hooks[2], row.ropeWeight);
w
..setJointLength(
row.rope,
length: _ropeLength,
least: 0.0,
most: _ropeLength,
)
..setJointSpring(row.rope, JointSpring(hertz: 0.0, damping: 0.0))
..setVelocity(row.ropeWeight, Vector3(1.0, 0.0, 0.0));
}
Step 5: Step it #
Each frame turns the motor round if the carriage is at an end, then steps the world by a sixtieth of a second. The cords are drawn from each hook to its weight. After twelve seconds the row starts again.
_drive(row);
row.world.step(_step);
Step 6: What each joint has to do #
The page's check starts the row again and steps it for six seconds, reading every joint after every step. The hinge has to reach its stops and go no more than two degrees past them. The carriage has to run at the motor's 0.6 m/s. The limb has to swing out to its cone and twist to its limit without going past either. The rod has to keep its length to within five millimetres. The rope has to start slack, go taut and never get longer than itself. The spring has to stay between its least and its most.
// Six seconds from the start, every joint read after every step.
_restart();
final _Row row = _row!;
final NativeWorld w = row.world;
var hinge = 0.0, swing = 0.0, twist = 0.0, rod = 0.0;
var ropeLeast = double.infinity, ropeMost = 0.0;
var springLeast = double.infinity, springMost = 0.0;
var cartSpeed = 0.0;
for (var i = 0; i < 360; i++) {
_drive(row);
w.step(_step);
hinge = math.max(hinge, w.jointValue(row.hinge).abs());
swing = math.max(swing, w.jointSwing(row.ball));
twist = math.max(twist, w.jointValue(row.ball).abs());
rod = math.max(rod, (w.jointValue(row.rod) - _rodLength).abs());
ropeLeast = math.min(ropeLeast, w.jointValue(row.rope));
ropeMost = math.max(ropeMost, w.jointValue(row.rope));
springLeast = math.min(springLeast, w.jointValue(row.spring));
springMost = math.max(springMost, w.jointValue(row.spring));
// Two thirds of a second in, the carriage is halfway along the rail.
if (i == 40) cartSpeed = w.velocityOf(row.cart).x;
}
void claim(bool holds, String what) {
if (!holds) throw StateError(what);
}
// The hinge reaches its stops and never goes more than 2° past them.
claim(hinge > _limit - 0.1, 'the hinge never reached its limits: $hinge');
claim(hinge < _limit + 0.035, 'the hinge went past its limits: $hinge');
// The slider runs at the motor's speed.
claim((cartSpeed - 0.6).abs() < 0.01, 'the slider ran at $cartSpeed m/s');
// The ball joint swings out to its cone and stays in it, and its twist
// in its limits.
claim(swing > _cone - 0.15 && swing < _cone + 0.05, 'swing $swing');
claim(twist > _twist - 0.1 && twist < _twist + 0.05, 'twist $twist');
// The rod holds its length to 5 mm; the rope is slack, then taut, and
// never longer than itself; the spring stays between its least and most.
claim(rod < 0.005, 'the rod changed length by $rod m');
claim(ropeLeast < 1.0, 'the rope was never slack: $ropeLeast');
claim(ropeMost > _ropeLength - 0.01, 'the rope never went taut');
claim(ropeMost < _ropeLength + 0.005, 'the rope stretched to $ropeMost');
claim(
springLeast >= _springLength.least && springMost <= _springLength.most,
'the spring went from $springLeast to $springMost m',
);
claim(springMost - springLeast > 0.1, 'the spring never moved');
Note. A limit is solved softly, in the same substeps as the contacts, so a fast body can pass it a little for a step before it is pushed back. On this page the hinge stays just inside its limits and the limb never passes its cone, but a heavier bar or a longer step would go further. The cords are drawn straight even when the rope is slack, because the joint has no shape of its own to draw. A chain of many light bodies with a heavy one at the end is where these joints stretch most; the core's multibodies are made for that case.