Course outline

Topic 16.3Advanced ~19 min · step 3 of 6

Colliders and Joints

In one line

Pick the simplest collider that fits: balls, cuboids, cylinders and convex hulls are fast and solid; a triangle mesh is exact but hollow. Friction and restitution are set per collider and combined per contact (averaged by default). Joints hold bodies together: a revolute joint is a hinge, and its motor drives a wheel.

0/6 · 0%

Think of it like this

Building a toy car from a kit. The body is a block, the wheels are discs, and each wheel is held by an axle that lets it turn one way only. Physics joints are those axles; colliders are the simple blocks and discs, not the painted detail on top.

Words you'll meet

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

convex hull: The tightest dent-free shape around a set of points, like cling film stretched over them.
trimesh: A collider made of the exact triangles of a mesh: precise, slower, and hollow.
restitution: How bouncy a contact is: 0 stops dead, 1 bounces back to the same height.
combine rule: How two colliders' friction or restitution become one number for their contact: average, min, max or multiply.
revolute joint: A hinge: two bodies joined at a point, free to turn round one axis.
joint motor: A drive on a joint that pushes it towards a target speed or position.

Step by step

01Measure bounce and friction

Run the first example. The bounce heights are much lower than the restitution numbers suggest: that is the average rule at work. The friction distances match v² / (2 μ g).

02Build a bike from bodies and hinges

The second example: one frame body (about 11 kg) and two wheel bodies (cylinders turned to lie along z, about 1.5 kg each), each wheel joined to the frame by a revolute joint round z.

03Drive it

A motor on the rear joint at −8 rad/s (negative round z rolls towards +x). Friction between tyre and floor turns the wheel's spin into forward motion, and the speed settles at 2.80 m/s.

04Choose the shapes for the showroom

The test ride keeps it simpler still: one body with a box and two balls (Topic 16.5). No joints to tune, and balls roll smoothly over the ramp's edge.

Try it yourself

1
Use the Max rule
In the first example, add .setRestitutionCombineRule(RAPIER.CoefficientCombineRule.Max) to the ball's collider. The 0.9 ball now bounces to 0.73 m: 0.9² × 0.9.
2
Double the motor
In the second example, set the motor to -16. Measured: the bike rears up and flips right over (the frame ends turned 180°, upside down at y 0.05). The motor's reaction twists the frame the other way: a wheelie that goes too far. Real bikes have a rider leaning forward.

Code & diagrams

Bounce and slide, measured New tab

Rapier's default combine rule is the average; the floor here has restitution 0.

Console

(nothing was printed)

Expected console output

restitution 0 (floor 0, averaged): first bounce reaches 0.00 m (dropped from 0.90 m)
restitution 0.5 (floor 0, averaged): first bounce reaches 0.05 m (dropped from 0.90 m)
restitution 0.9 (floor 0, averaged): first bounce reaches 0.18 m (dropped from 0.90 m)
friction 0: slid 6.00 m in 2 s, speed now 3.00 m/s
friction 0.2: slid 2.29 m in 2 s, speed now 0.00 m/s
friction 0.8: slid 0.57 m in 2 s, speed now 0.00 m/s

Two wheels on hinges, and a motor New tab

Console

(nothing was printed)

Expected console output

settled: frame at x -0.00 y 0.80
after 2 s of motor: frame at x 5.53 | speed 2.80 m/s | ideal ω·r = 2.80 m/s

Break it on purpose

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

Break #1

Trust a trimesh to be solid

Make a 1 m box as ColliderDesc.trimesh(vertices, indices), and start a small ball inside it. Do the same with ColliderDesc.convexHull(vertices).

terminal

$ Step the world for 1 s

── what you'll see ──

trimesh box ball after 1 s: x 0.10 -> still inside

convex hull box ball after 1 s: x 0.60 -> pushed out

Measured in Rapier 0.21.0.

Myth vs fact

Myth

A collider's restitution of 0.5 means every bounce keeps half its speed.

Fact

Only if the other collider agrees: the contact uses a combined value, the average by default. On a floor of 0, a ball of 0.5 behaves like 0.25.

Pro corner

Extra depth for experienced readers. New to this? Skip it for now and come back later.

▸
Mass comes from collider density × volume (a 0.4 m box at density 1 is 0.064 kg). Set densities to real values (steel is about 7,850 kg/m³) or call setMass. Keep touching bodies within the same order of magnitude of mass where you can: a 1,000 kg crate resting on a 0.1 kg one makes the solver's job much harder.
▸
In Rapier 0.21, a trimesh on a dynamic body gets a mass from its closed volume and rests on a floor like a cuboid (measured: 0.064 kg, y 0.20). It still costs more to test than a hull and stays hollow: prefer hulls for moving parts.

Remember this

1
The problem this solves: the bike's mesh has thousands of triangles, but physics on thousands of triangles is slow and has surprises. Simple shapes are fast and predictable, and joints give real behaviour (a wheel that rolls, a door that swings) without you writing the maths.
2
Collider shapes. ball(r), cuboid(hx, hy, hz) (half-sizes), cylinder(halfHeight, r), capsule(halfHeight, r), convexHull(points) (the tightest shape with no dents around the points) and trimesh(vertices, indices) (the exact triangles). Use primitives and convex hulls on moving bodies, and triangle meshes for big static scenery like a track. A trimesh is only a skin: the third example starts a ball inside a trimesh box and it stays there, while a convex hull pushes it out.
3
Friction and restitution combine. Each collider has its own values, but a contact uses one number for the pair. Rapier's default rule is the average: a ball with restitution 0.5 on a floor with 0 bounces as if 0.25. The first example drops balls from 0.90 m and they reach 0.05 m and 0.18 m, which is (average)² × 0.9. Set setRestitutionCombineRule(Max) on the ball and 0.9 reaches 0.73 m. Friction averages too; the build sets its wheels to the Min rule so their 0 wins.
4
Friction you can check. A box slid at 3 m/s with friction μ stops after v² / (2 μ g): 9 / (2 × 0.2 × 9.81) = 2.29 m for 0.2, and 0.57 m for 0.8. The example measures exactly that. With friction 0 it slides on at 3 m/s.
5
Joints. JointData.revolute(anchor1, anchor2, axis) pins a point on one body to a point on another and allows rotation round one axis: a wheel on an axle. world.createImpulseJoint(data, frame, wheel, true) creates it. configureMotorVelocity(target, factor) makes the joint turn at a target speed (rad/s) with a given strength. The second example's rear motor turns at 8 rad/s and the bike reaches 2.80 m/s: exactly ω × r with r = 0.35 m.

Explain it without notes

Which collider shapes would you use for the bike, the track and a crate, and why?

Explain how friction and restitution are combined, with numbers.

Practice

Make the crates in Topic 16.1's scene less slippery and bouncier.

Add a front-wheel motor to the second example too, and compare the speed after 2 s.

Done when you can

You pick primitives or hulls for moving bodies
You know a trimesh is hollow
You can predict a combined friction or bounce
You can join a wheel with a revolute joint and drive it with a motor

Command Palette