I’m happy to announce the release of Box3D, an open source 3D physics engine. It is now available on GitHub.
You can think of Box3D as a fork of Box2D, extended with many features needed for 3D games. Some additions:
The core architecture of Box3D remains almost identical to Box2D.
If you want to see Box3D in action, watch this video:
There are two main reasons Box3D exists. But there is a lot to unpack. So stay awhile, and listen.
The first reason I developed Box3D is that the game I’ve been working on needs it. Let me explain.
I’ve been working on The Legend of California at Kintsugiyama since 2022. This game is built using the Unreal engine. We started with version 5.0. Our experiments with the native physics engine (called Chaos) had some problems. There was no support for simulating gyroscopic torques. This means slender shapes could spin for a long time, conserving angular velocity. For example, see this video of a spinning rifle.
In 2015 I developed a ~10 line drop-in algorithm for adding gyroscopic torques to any physics engine and presented it at the Game Developer Conference: presentation. So I could have easily added this feature to the Chaos solver. Epic added this feature in late 2024.
However, that was not my biggest problem. Being a survival game, one of the first things I worked on was chopping down trees. The falling trees moved erratically, teleporting around the screen. My best guess is that Chaos was using some sort of continuous collision fallback. This simulation was a large capsule falling on a smooth triangle mesh. This scenario should have been easy to simulate.
Another factor is that The Legend of California needs to manage a lot of entities. Hundreds of thousands of entities exist on the server. We need a fast broad-phase for this. This is so central to our game that it seemed risky to hand this off to middleware. I have a lot of experience working on broad-phase data structures. I even did a GDC presentation on the topic.
So we reached a pivot point with our physics tech. All these factors were adding up and I needed to make a decision: try to fix the native solution or replace it with an outside physics engine.
I was considering using an existing open source physics engine, such as Jolt. Being a physics programmer, I was pretty confident that I could at least fork Jolt and get the outcomes we need for our game. However, a good friend suggested another course of action.
My friend Dirk Gregorius is an accomplished physics programmer, having shipped a custom physics engine in Half-Life: Alyx called Rubikon. Dirk maintains a hobby/home version of Rubikon. Let’s call this “Rubikon-Lite”. He suggested that I could fork Rubikon-Lite and modify it to my needs.
So that’s what I did. I hooked Rubikon-Lite directly into Unreal. It worked great! We got gyroscopic torques and trees fell nicely. Everything just worked.
The topic of replacing the physics engine in Unreal is likely a whole blog post (or more) on its own. I was able to make a few shortcuts because:
Box2D v3.0 had many optimizations I wanted to bring into my Rubikon-Lite fork. At some point I realized I needed to keep my 2D and 3D efforts as similar as possible, for efficiency and sanity. So I replaced almost all the APIs, data structures, and algorithms in Rubikon-Lite with Box2D code. Fortunately, the data structures for 2D and 3D are largely indifferent to spatial dimensions.
Eventually my Rubikon-Lite fork transformed into Box3D. Today Box3D still has some Rubikon-Lite code in the convex hull generation and some collision algorithms. The rest is code from Box2D and new code I wrote for Box3D.
On the Valve side, Rubikon continues to evolve and Dirk has developed optimizations (similar to those in Box3D) in a new engine called Ragnarok. Look for that in future Valve games.
The Legend of California is an ambitious project with a large open world and server authority. Falling trees, ragdolls, voxels, saloon doors, and tumbleweeds are all simulated on the server. Having a custom physics engine means I can tailor the feature set and performance to the needs of our game.
For performance, I’ve done a lot of work to optimize for falling trees. We have huge redwood trees that fall fast onto a voxel terrain. Getting the mesh collision and CCD working well is a big effort.
I’ve also worked on building collision meshes fast for our voxel system, since they need to be built at runtime. They build well with median split because voxels are grid-like.
Streaming is another critical feature. Our strongholds are built using kitbashing. A large stronghold can easily have around 50,000 separate collision meshes. Loading these into the physics engine one-by-one is inefficient and uses a lot of memory. So I built a compound collision system where the separate collision shapes are cooked into an optimized data structure that can be loaded as a single uber shape. This removes the overhead of creating thousands of bodies and shapes.
On the personal side, I have been making physics engines for games since 2004. Every time I change jobs, I need to leave that work behind. This is partly the reason I developed Box2D. It is an open source project that captures my knowledge and efforts so I can use it as the basis for future work. However, on the 3D side I keep re-inventing the wheel in many ways. I’m not totally against that, but it is a big tax.
Somehow I convinced the fine folks at Kintsugiyama to allow me to not only make Box3D open source, but also work on it as part of my day job. This means it is something I can feasibly support. So everyone, please give a big thanks to Kintsugiyama for making Box3D possible.
This one is going to be brief. If you like Box2D and its design, then you’ll probably like Box3D. They are siblings after all.
Box3D is open source. I’m not trying to compete with other physics engines. Open source is not a business for me. I develop Box2D and Box3D because I love working on game physics. I’m delighted to see all the amazing games created with Box2D over the years.
Install vanilla git and CMake, then clone the Box3D repository. You can find the build instructions in the README. After you get a build, run the samples and see the features it has to offer. Look at the sample code to get started with coding.
The engine headers have full Doxygen comments and the written manual is in progress. Here’s the hosted documentation.
You can find minimal example code in the HelloWorld test.
Box3D is used in a few places already. Besides The Legend of California, it’s used in:
Despite usage in a few games now, I still consider Box3D to be alpha software. I will soon tag v0.1 and build from there to the v1.0 release. The engine needs more testing and more complete documentation. However, the feature set is in a good place already. Here are some tasks I’m considering:
I expect to support Box3D indefinitely, along with Box2D. However, once it becomes mature, I may take a break from feature work. Unlike Box2D, I expect to open up Box3D to pull requests, probably using a CLA.
I plan to continue blogging about Box3D and making videos. It should be fun!
I won’t be making a separate website or Discord server for Box3D. So look for updates on this site and join the Box2D Discord server to chat with me and the community.
If you want to see Box3D in our game, follow The Legend of California via the home page and Steam.
Thank you for your support!