How bearlikelion/godot-box3d works
godot-box3d is a Godot GDExtension implementing a drop-in PhysicsServer3D backend over Box3D. Stock Godot physics nodes submit resource and simulation requests to the server; it manages spaces, bodies, areas, shapes, and joints, while direct-space state provides queries and body state supports contact reporting and motion testing. The README also documents multithreaded solving and several shape types whose implementation details are not sampled here; those capabilities are represented at the subsystem level. Arrows reflect sampled calls or documented integration, not a complete trace of unsampled stepping code.
Main entry points: box3d_physics_server_3d.cpp Physics Server · box3d_space_3d.cpp Physics Space · box3d_body_impl_3d.cpp Body Implementation · box3d_physics_direct_space_state_3d.cpp Direct Space State
Components 18
Godot Integration
- Extension Registration
src/register_types.cpp - Physics Server
src/servers/box3d_physics_server_3d.cpp - RID Registry
src/containers/rid_owner.hpp
World Simulation
- Physics Space
src/spaces/box3d_space_3d.cpp - CPU Topology
src/misc/box3d_cpu_topology.cpp
Physics Resources
- Body Implementation
src/objects/box3d_body_impl_3d.cpp - Area Implementation
src/objects/box3d_area_impl_3d.cpp - Shaped Objects
src/objects/box3d_shaped_object_impl_3d.cpp - Shape Implementations
src/shapes/box3d_shape_impl_3d.cpp - Heightmap Shape
src/shapes/box3d_heightmap_shape_impl_3d.cpp - Joint Implementations
src/joints/box3d_hinge_joint_impl_3d.cpp
Queries and State
- Direct Space State
src/spaces/box3d_physics_direct_space_state_3d.cpp - Query Filter
src/spaces/box3d_query_filter_3d.hpp - Query Shape Proxy
src/misc/box3d_shape_proxy.cpp - Direct Body State
src/objects/box3d_physics_direct_body_state_3d.cpp
Other components
- Godot Project
- Godot Physics API
- Box3D Engine
Connections 25
- Godot Project → Godot Physics API: selects backend
- Godot Physics API → Extension Registration: loads extension
- Extension Registration → Physics Server: registers backend
- Godot Physics API → Physics Server: calls physics API
- Physics Server → RID Registry: resolves RIDs
- Physics Server → Physics Space: creates and configures
- Physics Server → Body Implementation: dispatches body calls
- Physics Server → Area Implementation: dispatches area calls
- Physics Server → Shaped Objects: dispatches shape calls
- Physics Server → Joint Implementations: dispatches joint calls
- Body Implementation → Physics Space: joins space
- Area Implementation → Physics Space: joins space
- Shaped Objects → Shape Implementations: creates shape instances
- Heightmap Shape → Box3D Engine: builds heightfield
- Body Implementation → Box3D Engine: creates and updates bodies
- Joint Implementations → Box3D Engine: creates constraints
- Physics Space → Box3D Engine: owns world
- Physics Space → CPU Topology: queries CPU topology
- Physics Server → Direct Space State: returns query state
- Direct Space State → Physics Space: queries world
- Direct Space State → Query Filter: applies filtering
- Direct Space State → Query Shape Proxy: builds query proxy
- Query Shape Proxy → Shape Implementations: reads shape data
- Physics Server → Direct Body State: provides body state
- Body Implementation → Box3D Engine: refreshes contacts