> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Physics engines Cairn has two physics libraries built in, [Jolt](https://github.com/jrouwe/JoltPhysics) and [Box3D](https://github.com/erincatto/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: ```yaml Physics: Engine: Box3D ``` An agent sends: ```json {"command": "project.set_physics", "engine": "box3d"} ``` 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](/guide/features/physics.md) and [Rigid bodies](/guide/features/rigid-bodies.md) 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 | | Jolt | Box3D | | ------------------------------------- | ------------------------------------- | -------------------------------------------------------------- | | Maturity | Has shipped in large commercial games | Alpha, with no release yet | | Character controller | Jolt's own `CharacterVirtual` | Cairn's, built on Box3D's mover the way Box3D's own samples do | | Speed with thousands of moving bodies | Good | Better, see below | 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: | Bodies | Jolt | Box3D | | ------ | ---- | ----- | | 2,000 | 120 | 120 | | 4,000 | 117 | 120 | | 6,000 | 95 | 97 | | 8,000 | 79 | 76 | | 10,000 | 68 | 61 | | 12,000 | 50 | 39 | | 14,000 | 20 | 44 | | 16,000 | 19 | 39 | | 20,000 | 12 | 18 | 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: | Bodies | Jolt, physics time per frame | Box3D, physics time per frame | | ------ | ---------------------------- | ----------------------------- | | 4,000 | 2.9 ms | 1.4 ms | | 8,000 | 8.1 ms | 3.9 ms | | 10,000 | 10.7 ms | 6.4 ms | 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](/guide/editor/performance.md)) 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](/agents/commands.md)). 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.