Physics engines
Cairn has two physics libraries built in, Jolt and Box3D. A project picks one in its settings. Jolt is the default.
Unlike a project's script language, the choice is not fixed: change it whenever you like, and change it back. Scripts and scenes do not change. The engine and your scripts talk to one physics interface, and the library behind it is swapped underneath.
Changing the engine
In the editor, open Project Settings, go to Physics and pick Engine: Jolt or Box3D. The change takes effect the next time the game starts. A game that is playing keeps the library it started with, since bodies in motion cannot move from one library to the other.
In the project file it is one line under Physics, left out for Jolt:
An agent sends:
An exported game uses the engine its project names. Both libraries are in every build of the runtime.
What is the same on both
Everything on the Physics and Rigid bodies pages works on both, the character controller and joints included. The engine's tests run every physics test once on each library, and both pass them all.
Gravity, layer names and which layers collide are project settings and go along when the engine changes.
What differs
The two are separate simulations, so the same scene settles differently in detail: a pile of crates thrown by an explosion lands in a different pattern. Gameplay that depends on exactly where a body ends up can differ between them. Anything that depends on rules (a door opens when a trigger is entered, a ball rests on a floor) behaves the same.
Performance
Measured with the Ball Pit sample, which pours balls into a box from three spouts, 400 a second, so the number of moving bodies keeps climbing. Release builds on an Apple M2 Pro, with 8 physics threads for each library.
Frames per second with that many bodies:
120 is where this machine's display stops the frame rate. A pile falls differently each run, so numbers vary by 10 to 20% from one run to the next.
The Jolt column past 10,000 bodies is too kind. It was measured while a Jolt world was set up for 16,384 contacts whatever the game needed, and a bigger pile went over that: Jolt skipped the contacts it had no room for, which is cheaper, and let balls fall through the box. With room for every contact, Jolt runs Ball Pit at about 8 frames a second at 20,000 bodies. These tables will be measured again.
Up to about 12,000 bodies the two give about the same frame rate, because drawing the balls takes longer than simulating them. The difference is in how much of each frame the physics uses, which is time a game has for everything else:
Box3D's solver is about two to three times faster in a big pile. Past 12,000 bodies Jolt no longer finishes a physics step in time for every frame and falls behind, which is the drop to 20 frames a second at 14,000.
In a typical game the choice does not show. Zombie Survival, with about 200 entities, runs at about 120 frames a second on both, and physics takes about 0.1 ms of each frame.
To measure your own game, run it with --stats-log (see Performance) once on each engine and compare the Physics and Physics solver rows. Physics solver is the time inside the library. The rest of Physics is the engine keeping bodies and entities in step, which is the same on both.
How many bodies a Jolt world holds
A Jolt world makes room, when the game starts, for a set number of bodies and for twice as many touching pairs. Past the bodies, new ones get no body and the console says so once. Past the pairs, Jolt skips contacts and bodies fall through each other, and the console says that once too. The room costs memory in every game, so the default is 16,384 bodies, which keeps a world near 35 MB.
A game with more raises Max bodies under Physics in Project Settings, or sends project.set_physics with max_bodies (see Commands). Ball Pit sets 65,536 for its 20,000 balls. A change takes effect the next time the game starts. Box3D grows as it needs to and ignores the setting.
Which to pick
Keep Jolt unless you have a reason to change. It is mature, and for most games it is just as fast.
Try Box3D when a game has thousands of bodies moving at once, such as piles of debris or props, and physics shows up in the stats.
Since the choice can be undone at any time, the quickest way to decide is to try both on your game and look at the numbers.