godot-box3d

A GDExtension that integrates Box3D, Erin Catto's 3D physics engine, into Godot 4 as a drop-in replacement for the built-in PhysicsServer3D.

The structure of this extension is based on godot-jolt, which pioneered swapping out Godot's 3D physics backend via GDExtension.

Status: early and experimental. Box3D itself is a young engine, and this extension is a work in progress. Expect missing features and rough edges.

What works

• Rigid, static, and kinematic bodies
• Shapes: box, sphere, capsule, convex polygon, concave polygon (trimesh), heightmap, and world boundary
• Areas, including overlap events and gravity/damping overrides
• Direct space state queries: ray casts, point and shape intersection, shape casts (cast_motion), collide_shape, and rest_info
• body_test_motion, so CharacterBody3D and move_and_slide() work
• Joints: pin, hinge, and slider
• A small test project (test_project/) with demo and stress scenes

What's left to do

• Cylinder and separation ray shapes (not supported by Box3D)
• ConeTwist and Generic6DOF joints
• SoftBody3D
• Per-pair collision exceptions (use collision layers/masks for now)
• Changing a PinJoint3D anchor after creation (recreate the joint instead)
• More platforms and architectures (currently Linux, Windows, and macOS builds)
• Performance benchmarking and tuning
• Documentation

Behavior differences

• Area3D does not detect trimesh or heightmap bodies. In Box3D a concave shape (ConcavePolygonShape3D) or HeightMapShape3D can never act as a sensor visitor — by design, since testing an arbitrary mesh against a sensor is too expensive. So an Area3D silently ignores a body whose shape is a trimesh or heightmap: no body_entered / body_exited fires for it. This diverges from Godot's built-in physics (and Jolt), which report such a body on the first physics frame. If you need a body to be detected by an area, give it a convex shape. (A trimesh may still be used as an Area3D's own shape to detect convex bodies passing through it.)

Requirements

• Godot 4.3 or newer

Building

The project builds with CMake:

cmake -B build
cmake --build build

The resulting library is placed in bin/ and loaded via godot-box3d.gdextension. Copy bin/ and the .gdextension file into your project, then select the Box3D physics server in your project settings.

Contributing

Help wanted! This is a big surface area for one person, and contributions of any size are very welcome: missing features from the list above, bug reports with reproduction scenes, benchmarks, documentation, or just trying it in your project and reporting what breaks. Open an issue or a pull request.

License

MIT. See LICENSE for details.

Box3D is licensed under the MIT license. This project takes structural inspiration from godot-jolt, also MIT licensed.