Box3D Open Source 3D Physics Engine Release

Box3D Open Source 3D Physics Engine Release

Box3D is an open-source 3D physics engine designed for high-performance game simulation

Box3D is a 3D extension of the widely used Box2D engine, providing a C17-based library that supports complex collision types, multi-threading, and large-world coordinates. It was developed primarily to meet the specific technical requirements of the game The Legend of California, specifically addressing shortcomings in existing middleware regarding gyroscopic torques and large-scale entity management.

Core Technical Specifications

Box3D maintains an architecture nearly identical to Box2D v3.0, ensuring consistency for developers familiar with the 2D version. Key technical features include:

  • Language and API: Written in C17 with a C API.
  • Collision Support: Includes triangle mesh collision, height-field collision, and baked compound collision.
  • Solver and Performance: Features a sub-stepping solver, continuous collision detection (CCD), and a wide SIMD contact solver.
  • Scalability: Implements graph coloring for large islands, multi-threading hooks, and an optional internal scheduler.
  • World Scale: Supports large worlds by using doubles for position data.
  • Utility: Includes built-in recording and replay functionality.

Development Origin: From Rubikon-Lite to Box3D

Box3D originated as a fork of "Rubikon-Lite," a hobbyist version of the Rubikon engine developed by Dirk Gregorius (the engine used in Half-Life: Alyx). The transition occurred in stages to align the 3D engine with the optimizations present in Box2D v3.0.

Erin Catto replaced the majority of Rubikon-Lite's APIs, data structures, and algorithms with Box2D code to maintain sanity and efficiency across his 2D and 3D projects. While Box3D still retains some Rubikon-Lite code for collision algorithms and convex hull generation, the bulk of the engine is now based on Box2D's architecture.

Solving Real-World Game Physics Challenges

The development of Box3D was driven by specific failures encountered while using Unreal Engine's native physics engine, Chaos, for The Legend of California:

Gyroscopic Torques and Stability

Until late 2024, the Chaos solver lacked support for gyroscopic torques, causing slender objects (like rifles) to spin indefinitely without conserving angular velocity. Box3D implements these torques to ensure physically plausible rotation.

Large-Scale Entity Management

For a survival game with hundreds of thousands of server-side entities, a highly optimized broad-phase is critical. Box3D allows for custom tailoring of these data structures to avoid the risks of relying on middleware for core game loop performance.

Voxel Terrain and Compound Collision

To handle the interaction between fast-falling redwood trees and voxel terrain, Box3D utilizes optimized mesh collision and CCD. To manage memory and loading efficiency for large structures (some containing 50,000 separate collision meshes), Box3D uses a "baked compound collision" system. This cooks separate shapes into a single optimized data structure, removing the overhead of managing thousands of individual bodies.

Current Status and Ecosystem

Box3D is currently considered alpha software, with a v0.1 tag planned for the near future. It is already being utilized in several projects:

  • The Legend of California: The primary driver for the engine's development.
  • s&box: A game platform by Facepunch Studios.
  • Esoterica: An open-source game engine.
  • A 1000-player space game: A multiplayer project by Glenn Fiedler.

Community Insights

Developers in the community have noted the engine's potential for web-based gaming due to its small footprint. One user observed that a release build on macOS was approximately 916K, suggesting it would be a viable candidate for WASM compilation via Emscripten.

Other developers have compared Box3D to other modern open-source options like Jolt and Rapier, noting a growing landscape of alternatives to the previously dominant Bullet physics engine.

Getting Started

Box3D is available on GitHub and requires git and CMake for installation. Documentation is hosted at box2d.org/documentation3d/, and minimal implementation examples can be found in the test_world.c file within the repository.

Sources