# bearlikelion/godot-box3d architecture

> Architecture diagram of the GitHub repository bearlikelion/godot-box3d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bearlikelion/godot-box3d
- Repository: https://github.com/bearlikelion/godot-box3d

## Overview

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: [`src/servers/box3d_physics_server_3d.cpp`](https://github.com/bearlikelion/godot-box3d/blob/main/src/servers/box3d_physics_server_3d.cpp) (Physics Server), [`src/spaces/box3d_space_3d.cpp`](https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_space_3d.cpp) (Physics Space), [`src/objects/box3d_body_impl_3d.cpp`](https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_body_impl_3d.cpp) (Body Implementation), [`src/spaces/box3d_physics_direct_space_state_3d.cpp`](https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_physics_direct_space_state_3d.cpp) (Direct Space State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Godot Integration"]
  node_registration["Extension Registration<br/>[register_types.cpp]"]
  node_server["Physics Server"]
  node_rid_owner["RID Registry<br/>[rid_owner.hpp]"]
end

subgraph group_world["World Simulation"]
  node_space["Physics Space<br/>[box3d_space_3d.cpp]"]
  node_topology["CPU Topology"]
end

subgraph group_resources["Physics Resources"]
  node_body["Body Implementation"]
  node_area["Area Implementation"]
  node_shaped_object["Shaped Objects"]
  node_shape_impl["Shape Implementations"]
  node_heightmap["Heightmap Shape"]
  node_joints["Joint Implementations"]
end

subgraph group_queries["Queries and State"]
  node_direct_state["Direct Space State"]
  node_query_filter["Query Filter"]
  node_shape_proxy["Query Shape Proxy"]
  node_direct_body_state["Direct Body State"]
end

node_godot_project(("Godot Project"))
node_godot_engine(("Godot Physics API"))
node_box3d_engine{{"Box3D Engine"}}

node_godot_project -->|"selects backend"| node_godot_engine
node_godot_engine -->|"loads extension"| node_registration
node_registration -->|"registers backend"| node_server
node_godot_engine -->|"calls physics API"| node_server
node_server -->|"resolves RIDs"| node_rid_owner
node_server -->|"creates and configures"| node_space
node_server -->|"dispatches body calls"| node_body
node_server -->|"dispatches area calls"| node_area
node_server -->|"dispatches shape calls"| node_shaped_object
node_server -->|"dispatches joint calls"| node_joints
node_body -->|"joins space"| node_space
node_area -->|"joins space"| node_space
node_shaped_object -->|"creates shape instances"| node_shape_impl
node_heightmap -->|"builds heightfield"| node_box3d_engine
node_body -->|"creates and updates bodies"| node_box3d_engine
node_joints -->|"creates constraints"| node_box3d_engine
node_space -->|"owns world"| node_box3d_engine
node_space -.->|"queries CPU topology"| node_topology
node_server -->|"returns query state"| node_direct_state
node_direct_state -->|"queries world"| node_space
node_direct_state -->|"applies filtering"| node_query_filter
node_direct_state -->|"builds query proxy"| node_shape_proxy
node_shape_proxy -->|"reads shape data"| node_shape_impl
node_server -->|"provides body state"| node_direct_body_state
node_body -->|"refreshes contacts"| node_box3d_engine

click node_registration "https://github.com/bearlikelion/godot-box3d/blob/main/src/register_types.cpp"
click node_server "https://github.com/bearlikelion/godot-box3d/blob/main/src/servers/box3d_physics_server_3d.cpp"
click node_rid_owner "https://github.com/bearlikelion/godot-box3d/blob/main/src/containers/rid_owner.hpp"
click node_space "https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_space_3d.cpp"
click node_topology "https://github.com/bearlikelion/godot-box3d/blob/main/src/misc/box3d_cpu_topology.cpp"
click node_body "https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_body_impl_3d.cpp"
click node_area "https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_area_impl_3d.cpp"
click node_shaped_object "https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_shaped_object_impl_3d.cpp"
click node_shape_impl "https://github.com/bearlikelion/godot-box3d/blob/main/src/shapes/box3d_shape_impl_3d.cpp"
click node_heightmap "https://github.com/bearlikelion/godot-box3d/blob/main/src/shapes/box3d_heightmap_shape_impl_3d.cpp"
click node_joints "https://github.com/bearlikelion/godot-box3d/blob/main/src/joints/box3d_hinge_joint_impl_3d.cpp"
click node_direct_state "https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_physics_direct_space_state_3d.cpp"
click node_query_filter "https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_query_filter_3d.hpp"
click node_shape_proxy "https://github.com/bearlikelion/godot-box3d/blob/main/src/misc/box3d_shape_proxy.cpp"
click node_direct_body_state "https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_physics_direct_body_state_3d.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registration,node_server,node_rid_owner toneBlue
class node_space,node_topology toneAmber
class node_body,node_area,node_shaped_object,node_shape_impl,node_heightmap,node_joints,node_godot_engine toneMint
class node_direct_state,node_query_filter,node_shape_proxy,node_direct_body_state toneRose
class node_godot_project,node_box3d_engine toneIndigo
```

## Components

### Godot Integration

- [Extension Registration](https://github.com/bearlikelion/godot-box3d/blob/main/src/register_types.cpp): `src/register_types.cpp`
- [Physics Server](https://github.com/bearlikelion/godot-box3d/blob/main/src/servers/box3d_physics_server_3d.cpp): `src/servers/box3d_physics_server_3d.cpp`
- [RID Registry](https://github.com/bearlikelion/godot-box3d/blob/main/src/containers/rid_owner.hpp): `src/containers/rid_owner.hpp`

### World Simulation

- [Physics Space](https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_space_3d.cpp): `src/spaces/box3d_space_3d.cpp`
- [CPU Topology](https://github.com/bearlikelion/godot-box3d/blob/main/src/misc/box3d_cpu_topology.cpp): `src/misc/box3d_cpu_topology.cpp`

### Physics Resources

- [Body Implementation](https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_body_impl_3d.cpp): `src/objects/box3d_body_impl_3d.cpp`
- [Area Implementation](https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_area_impl_3d.cpp): `src/objects/box3d_area_impl_3d.cpp`
- [Shaped Objects](https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_shaped_object_impl_3d.cpp): `src/objects/box3d_shaped_object_impl_3d.cpp`
- [Shape Implementations](https://github.com/bearlikelion/godot-box3d/blob/main/src/shapes/box3d_shape_impl_3d.cpp): `src/shapes/box3d_shape_impl_3d.cpp`
- [Heightmap Shape](https://github.com/bearlikelion/godot-box3d/blob/main/src/shapes/box3d_heightmap_shape_impl_3d.cpp): `src/shapes/box3d_heightmap_shape_impl_3d.cpp`
- [Joint Implementations](https://github.com/bearlikelion/godot-box3d/blob/main/src/joints/box3d_hinge_joint_impl_3d.cpp): `src/joints/box3d_hinge_joint_impl_3d.cpp`

### Queries and State

- [Direct Space State](https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_physics_direct_space_state_3d.cpp): `src/spaces/box3d_physics_direct_space_state_3d.cpp`
- [Query Filter](https://github.com/bearlikelion/godot-box3d/blob/main/src/spaces/box3d_query_filter_3d.hpp): `src/spaces/box3d_query_filter_3d.hpp`
- [Query Shape Proxy](https://github.com/bearlikelion/godot-box3d/blob/main/src/misc/box3d_shape_proxy.cpp): `src/misc/box3d_shape_proxy.cpp`
- [Direct Body State](https://github.com/bearlikelion/godot-box3d/blob/main/src/objects/box3d_physics_direct_body_state_3d.cpp): `src/objects/box3d_physics_direct_body_state_3d.cpp`

### Other components

- **Godot Project**
- **Godot Physics API**
- **Box3D Engine**

## Connections

- 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