# stink-o/box3d-godot architecture

> Architecture diagram of the GitHub repository stink-o/box3d-godot, 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/stink-o/box3d-godot
- Repository: https://github.com/stink-o/box3d-godot

## Overview

Box3D for Godot embeds the Box3D rigid-body engine as a Godot 4 GDExtension. A project author configures world, body, collider and joint nodes; the binding creates and steps an engine world, then exposes simulation state and events back to Godot. The documented product also includes spatial queries, character control, recording/replay, editor gizmos and a browser demo. The tree and excerpts support the core engine/binding links; demo details beyond the listed generators are based on README capabilities.

Main entry points: [`include/box3d/box3d.h`](https://github.com/stink-o/box3d-godot/blob/main/include/box3d/box3d.h) (Engine public API), [`godot/src/box3d_world.cpp`](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_world.cpp) (World node), [`src/physics_world.c`](https://github.com/stink-o/box3d-godot/blob/main/src/physics_world.c) (World simulation), [`godot/src/box3d_body.cpp`](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_body.cpp) (Body node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_godot["Godot binding"]
  node_registration["Extension registration<br/>[register_types.cpp]"]
  node_world["World node<br/>[box3d_world.cpp]"]
  node_body["Body node<br/>[box3d_body.cpp]"]
  node_collider["Collision shapes"]
  node_joint["Joint nodes<br/>[box3d_joint.cpp]"]
  node_character["Character controller"]
  node_contact["Contact rules"]
end

subgraph group_engine["Physics engine"]
  node_api["Engine public API<br/>[box3d.h]"]
  node_simulation["World simulation<br/>[physics_world.c]"]
  node_collision["Collision detection<br/>[broad_phase.c]"]
  node_solver["Constraint solver<br/>[solver.c]"]
  node_queries["Spatial queries<br/>[physics_world.c]"]
end

subgraph group_replay["Replay and editor"]
  node_recording["Recording<br/>[recording.c]"]
  node_replay_player["Replay player<br/>[recording_replay.c]"]
  node_binding_replay["Godot replay<br/>[box3d_replay.cpp]"]
  node_gizmos["Editor gizmos"]
end

subgraph group_demo["Demo samples"]
  node_demo_generators["Demo samples"]
  node_demo_entry["Demo scene setup<br/>[gen_main.py]"]
end

node_author(("Godot project author"))

node_author -->|"loads extension"| node_registration
node_author -->|"configures scene"| node_world
node_world -->|"creates and steps"| node_api
node_body -->|"creates bodies"| node_api
node_collider -->|"creates shapes"| node_api
node_joint -->|"creates joints"| node_api
node_character -->|"controls movement"| node_api
node_contact -->|"sets contact rules"| node_api
node_api -->|"dispatches calls"| node_simulation
node_simulation -->|"finds contacts"| node_collision
node_simulation -->|"solves constraints"| node_solver
node_world -->|"runs queries"| node_queries
node_simulation -->|"provides events"| node_world
node_world -->|"syncs state"| node_body
node_simulation -->|"records state"| node_recording
node_recording -->|"replays recording"| node_replay_player
node_binding_replay -->|"controls playback"| node_replay_player
node_author -->|"views editor guides"| node_gizmos
node_demo_entry -->|"configures demo world"| node_world
node_demo_generators -->|"generates samples"| node_demo_entry

click node_registration "https://github.com/stink-o/box3d-godot/blob/main/godot/src/register_types.cpp"
click node_world "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_world.cpp"
click node_body "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_body.cpp"
click node_collider "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_collision_shape.cpp"
click node_joint "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_joint.cpp"
click node_character "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_character.cpp"
click node_contact "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_contact_rules.cpp"
click node_api "https://github.com/stink-o/box3d-godot/blob/main/include/box3d/box3d.h"
click node_simulation "https://github.com/stink-o/box3d-godot/blob/main/src/physics_world.c"
click node_collision "https://github.com/stink-o/box3d-godot/blob/main/src/broad_phase.c"
click node_solver "https://github.com/stink-o/box3d-godot/blob/main/src/solver.c"
click node_queries "https://github.com/stink-o/box3d-godot/blob/main/src/physics_world.c"
click node_recording "https://github.com/stink-o/box3d-godot/blob/main/src/recording.c"
click node_replay_player "https://github.com/stink-o/box3d-godot/blob/main/src/recording_replay.c"
click node_binding_replay "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_replay.cpp"
click node_gizmos "https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_editor_gizmos.cpp"
click node_demo_generators "https://github.com/stink-o/box3d-godot/tree/main/godot/demo/tools"
click node_demo_entry "https://github.com/stink-o/box3d-godot/blob/main/godot/demo/tools/gen_main.py"

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_world,node_body,node_collider,node_joint,node_character,node_contact toneBlue
class node_api,node_simulation,node_collision,node_solver,node_queries toneAmber
class node_recording,node_replay_player,node_binding_replay,node_gizmos toneMint
class node_demo_generators,node_demo_entry toneRose
class node_author toneIndigo
```

## Components

### Godot binding

- [Extension registration](https://github.com/stink-o/box3d-godot/blob/main/godot/src/register_types.cpp): `godot/src/register_types.cpp`
- [World node](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_world.cpp): `godot/src/box3d_world.cpp`
- [Body node](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_body.cpp): `godot/src/box3d_body.cpp`
- [Collision shapes](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_collision_shape.cpp): `godot/src/box3d_collision_shape.cpp`
- [Joint nodes](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_joint.cpp): `godot/src/box3d_joint.cpp`
- [Character controller](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_character.cpp): `godot/src/box3d_character.cpp`
- [Contact rules](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_contact_rules.cpp): `godot/src/box3d_contact_rules.cpp`

### Physics engine

- [Engine public API](https://github.com/stink-o/box3d-godot/blob/main/include/box3d/box3d.h): `include/box3d/box3d.h`
- [World simulation](https://github.com/stink-o/box3d-godot/blob/main/src/physics_world.c): `src/physics_world.c`
- [Collision detection](https://github.com/stink-o/box3d-godot/blob/main/src/broad_phase.c): `src/broad_phase.c`
- [Constraint solver](https://github.com/stink-o/box3d-godot/blob/main/src/solver.c): `src/solver.c`
- [Spatial queries](https://github.com/stink-o/box3d-godot/blob/main/src/physics_world.c): `src/physics_world.c`

### Replay and editor

- [Recording](https://github.com/stink-o/box3d-godot/blob/main/src/recording.c): `src/recording.c`
- [Replay player](https://github.com/stink-o/box3d-godot/blob/main/src/recording_replay.c): `src/recording_replay.c`
- [Godot replay](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_replay.cpp): `godot/src/box3d_replay.cpp`
- [Editor gizmos](https://github.com/stink-o/box3d-godot/blob/main/godot/src/box3d_editor_gizmos.cpp): `godot/src/box3d_editor_gizmos.cpp`

### Demo samples

- [Demo samples](https://github.com/stink-o/box3d-godot/tree/main/godot/demo/tools): `godot/demo/tools`
- [Demo scene setup](https://github.com/stink-o/box3d-godot/blob/main/godot/demo/tools/gen_main.py): `godot/demo/tools/gen_main.py`

### Other components

- **Godot project author**

## Connections

- Godot project author → Extension registration: loads extension
- Godot project author → World node: configures scene
- World node → Engine public API: creates and steps
- Body node → Engine public API: creates bodies
- Collision shapes → Engine public API: creates shapes
- Joint nodes → Engine public API: creates joints
- Character controller → Engine public API: controls movement
- Contact rules → Engine public API: sets contact rules
- Engine public API → World simulation: dispatches calls
- World simulation → Collision detection: finds contacts
- World simulation → Constraint solver: solves constraints
- World node → Spatial queries: runs queries
- World simulation → World node: provides events
- World node → Body node: syncs state
- World simulation → Recording: records state
- Recording → Replay player: replays recording
- Godot replay → Replay player: controls playback
- Godot project author → Editor gizmos: views editor guides
- Demo scene setup → World node: configures demo world
- Demo samples → Demo scene setup: generates samples