# dimforge/rapier architecture

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

- Interactive diagram: https://gitdiagram.com/dimforge/rapier
- Repository: https://github.com/dimforge/rapier

## Overview

Rapier is a Rust 2D/3D physics engine for games, animation, and robotics, with C/C++, Python, TypeScript/JavaScript, and Bevy integrations. The main workflow is to configure bodies and colliders, run simulation/collision processing, then use spatial queries, events, or rendering/debug output. The graph retains those domain stages and the documented binding branches. Relationships are limited to README statements and shown source references/calls; unsampled implementation details are not asserted.

Main entry points: [`src/lib.rs`](https://github.com/dimforge/rapier/blob/master/src/lib.rs) (Rapier engine), [`src/pipeline/query_pipeline.rs`](https://github.com/dimforge/rapier/blob/master/src/pipeline/query_pipeline.rs) (Spatial queries), [`src/geometry/collider.rs`](https://github.com/dimforge/rapier/blob/master/src/geometry/collider.rs) (Colliders and shapes), [`src/pipeline/collision_pipeline.rs`](https://github.com/dimforge/rapier/blob/master/src/pipeline/collision_pipeline.rs) (Collision processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Physics Engine"]
  node_engine["Rapier engine<br/>[lib.rs]"]
  node_bodies["Rigid and soft bodies<br/>[rigid_body.rs]"]
  node_body_components["Body components"]
  node_islands["Island management<br/>[manager.rs]"]
  node_colliders["Colliders and shapes<br/>[collider.rs]"]
  node_contacts["Contact pairs<br/>[contact_pair.rs]"]
  node_collision["Collision processing"]
  node_world["Physics world<br/>[physics_world.rs]"]
  node_changes["User changes<br/>[user_changes.rs]"]
end

subgraph group_controls["Controllers and Queries"]
  node_queries["Spatial queries<br/>[query_pipeline.rs]"]
  node_character["Character controller"]
  node_vehicle["Vehicle controller"]
end

subgraph group_bevy["Bevy Integration"]
  node_bevy_plugin["Bevy physics plugin<br/>[plugin.rs]"]
  node_bevy_systems["Bevy character system"]
  node_bevy_pid["Bevy PID controller<br/>[pid_controller.rs]"]
end

subgraph group_bindings["Language Bindings"]
  node_c_api["C and C++ API<br/>[rapier.h]"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_python_pipeline["Python pipeline<br/>[pipeline.rs]"]
  node_typescript_queries["TypeScript queries<br/>[query_pipeline.ts]"]
end

subgraph group_visual["Visualization"]
  node_debug_render["Debug rendering"]
end

node_user(("Application developer"))

node_user -->|"uses for physics"| node_engine
node_engine -->|"exposes dynamics"| node_bodies
node_engine -->|"exposes geometry"| node_colliders
node_engine -->|"exposes pipeline"| node_world
node_collision -->|"processes pairs"| node_colliders
node_collision -->|"computes contacts"| node_contacts
node_collision -->|"updates islands"| node_islands
node_world -.->|"applies changes"| node_changes
node_queries -->|"queries shapes"| node_colliders
node_queries -->|"filters by body"| node_bodies
node_character -->|"uses queries"| node_queries
node_vehicle -->|"uses queries"| node_queries
node_user -->|"integrates with Bevy"| node_bevy_plugin
node_bevy_systems -->|"uses plugin context"| node_bevy_plugin
node_bevy_systems -.->|"runs controller"| node_character
node_bevy_pid -.->|"controls bodies"| node_bodies
node_user -->|"uses C binding"| node_c_api
node_user -->|"uses Python binding"| node_python_api
node_python_api -.->|"exposes pipeline"| node_python_pipeline
node_user -->|"uses JavaScript binding"| node_typescript_queries
node_user -.->|"uses debug rendering"| node_debug_render
node_debug_render -->|"draws contacts"| node_contacts
node_debug_render -->|"draws colliders"| node_colliders

click node_engine "https://github.com/dimforge/rapier/blob/master/src/lib.rs"
click node_bodies "https://github.com/dimforge/rapier/blob/master/src/dynamics/rigid_body.rs"
click node_body_components "https://github.com/dimforge/rapier/blob/master/src/dynamics/rigid_body_components.rs"
click node_islands "https://github.com/dimforge/rapier/blob/master/src/dynamics/island_manager/manager.rs"
click node_colliders "https://github.com/dimforge/rapier/blob/master/src/geometry/collider.rs"
click node_contacts "https://github.com/dimforge/rapier/blob/master/src/geometry/contact_pair.rs"
click node_collision "https://github.com/dimforge/rapier/blob/master/src/pipeline/collision_pipeline.rs"
click node_world "https://github.com/dimforge/rapier/blob/master/src/pipeline/physics_world.rs"
click node_changes "https://github.com/dimforge/rapier/blob/master/src/pipeline/user_changes.rs"
click node_queries "https://github.com/dimforge/rapier/blob/master/src/pipeline/query_pipeline.rs"
click node_character "https://github.com/dimforge/rapier/blob/master/src/control/character_controller.rs"
click node_vehicle "https://github.com/dimforge/rapier/blob/master/src/control/ray_cast_vehicle_controller.rs"
click node_bevy_plugin "https://github.com/dimforge/rapier/blob/master/bindings/bevy_rapier/src/plugin/plugin.rs"
click node_bevy_systems "https://github.com/dimforge/rapier/blob/master/bindings/bevy_rapier/src/plugin/systems/character_controller.rs"
click node_bevy_pid "https://github.com/dimforge/rapier/blob/master/bindings/bevy_rapier/src/control/pid_controller.rs"
click node_c_api "https://github.com/dimforge/rapier/blob/master/bindings/c/include/rapier.h"
click node_python_api "https://github.com/dimforge/rapier/blob/master/bindings/python/rapier-py-3d/python/rapier3d/__init__.py"
click node_python_pipeline "https://github.com/dimforge/rapier/blob/master/bindings/python/rapier-py-3d/src/pipeline.rs"
click node_typescript_queries "https://github.com/dimforge/rapier/blob/master/bindings/typescript/src.ts/pipeline/query_pipeline.ts"
click node_debug_render "https://github.com/dimforge/rapier/blob/master/src/pipeline/debug_render_pipeline/debug_render_pipeline.rs"

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_engine,node_bodies,node_body_components,node_islands,node_colliders,node_contacts,node_collision,node_world,node_changes toneBlue
class node_queries,node_character,node_vehicle toneAmber
class node_bevy_plugin,node_bevy_systems,node_bevy_pid toneMint
class node_c_api,node_python_api,node_python_pipeline,node_typescript_queries toneRose
class node_debug_render,node_user toneIndigo
```

## Components

### Physics Engine

- [Rapier engine](https://github.com/dimforge/rapier/blob/master/src/lib.rs): `src/lib.rs`
- [Rigid and soft bodies](https://github.com/dimforge/rapier/blob/master/src/dynamics/rigid_body.rs): `src/dynamics/rigid_body.rs`
- [Body components](https://github.com/dimforge/rapier/blob/master/src/dynamics/rigid_body_components.rs): `src/dynamics/rigid_body_components.rs`
- [Island management](https://github.com/dimforge/rapier/blob/master/src/dynamics/island_manager/manager.rs): `src/dynamics/island_manager/manager.rs`
- [Colliders and shapes](https://github.com/dimforge/rapier/blob/master/src/geometry/collider.rs): `src/geometry/collider.rs`
- [Contact pairs](https://github.com/dimforge/rapier/blob/master/src/geometry/contact_pair.rs): `src/geometry/contact_pair.rs`
- [Collision processing](https://github.com/dimforge/rapier/blob/master/src/pipeline/collision_pipeline.rs): `src/pipeline/collision_pipeline.rs`
- [Physics world](https://github.com/dimforge/rapier/blob/master/src/pipeline/physics_world.rs): `src/pipeline/physics_world.rs`
- [User changes](https://github.com/dimforge/rapier/blob/master/src/pipeline/user_changes.rs): `src/pipeline/user_changes.rs`

### Controllers and Queries

- [Spatial queries](https://github.com/dimforge/rapier/blob/master/src/pipeline/query_pipeline.rs): `src/pipeline/query_pipeline.rs`
- [Character controller](https://github.com/dimforge/rapier/blob/master/src/control/character_controller.rs): `src/control/character_controller.rs`
- [Vehicle controller](https://github.com/dimforge/rapier/blob/master/src/control/ray_cast_vehicle_controller.rs): `src/control/ray_cast_vehicle_controller.rs`

### Bevy Integration

- [Bevy physics plugin](https://github.com/dimforge/rapier/blob/master/bindings/bevy_rapier/src/plugin/plugin.rs): `bindings/bevy_rapier/src/plugin/plugin.rs`
- [Bevy character system](https://github.com/dimforge/rapier/blob/master/bindings/bevy_rapier/src/plugin/systems/character_controller.rs): `bindings/bevy_rapier/src/plugin/systems/character_controller.rs`
- [Bevy PID controller](https://github.com/dimforge/rapier/blob/master/bindings/bevy_rapier/src/control/pid_controller.rs): `bindings/bevy_rapier/src/control/pid_controller.rs`

### Language Bindings

- [C and C++ API](https://github.com/dimforge/rapier/blob/master/bindings/c/include/rapier.h): `bindings/c/include/rapier.h`
- [Python API](https://github.com/dimforge/rapier/blob/master/bindings/python/rapier-py-3d/python/rapier3d/__init__.py): `bindings/python/rapier-py-3d/python/rapier3d/__init__.py`
- [Python pipeline](https://github.com/dimforge/rapier/blob/master/bindings/python/rapier-py-3d/src/pipeline.rs): `bindings/python/rapier-py-3d/src/pipeline.rs`
- [TypeScript queries](https://github.com/dimforge/rapier/blob/master/bindings/typescript/src.ts/pipeline/query_pipeline.ts): `bindings/typescript/src.ts/pipeline/query_pipeline.ts`

### Visualization

- [Debug rendering](https://github.com/dimforge/rapier/blob/master/src/pipeline/debug_render_pipeline/debug_render_pipeline.rs): `src/pipeline/debug_render_pipeline/debug_render_pipeline.rs`

### Other components

- **Application developer**

## Connections

- Application developer → Rapier engine: uses for physics (evidence: `README.md`)
- Rapier engine → Rigid and soft bodies: exposes dynamics (evidence: `src/lib.rs`)
- Rapier engine → Colliders and shapes: exposes geometry (evidence: `src/lib.rs`)
- Rapier engine → Physics world: exposes pipeline (evidence: `src/lib.rs`)
- Collision processing → Colliders and shapes: processes pairs (evidence: `src/pipeline/collision_pipeline.rs`)
- Collision processing → Contact pairs: computes contacts (evidence: `src/pipeline/collision_pipeline.rs`)
- Collision processing → Island management: updates islands (evidence: `src/pipeline/collision_pipeline.rs`)
- Physics world → User changes: applies changes
- Spatial queries → Colliders and shapes: queries shapes (evidence: `src/pipeline/query_pipeline.rs`)
- Spatial queries → Rigid and soft bodies: filters by body (evidence: `src/pipeline/query_pipeline.rs`)
- Character controller → Spatial queries: uses queries (evidence: `src/control/character_controller.rs`)
- Vehicle controller → Spatial queries: uses queries (evidence: `src/control/ray_cast_vehicle_controller.rs`)
- Application developer → Bevy physics plugin: integrates with Bevy (evidence: `README.md`)
- Bevy character system → Bevy physics plugin: uses plugin context (evidence: `bindings/bevy_rapier/src/plugin/systems/character_controller.rs`)
- Bevy character system → Character controller: runs controller
- Bevy PID controller → Rigid and soft bodies: controls bodies
- Application developer → C and C++ API: uses C binding (evidence: `README.md`)
- Application developer → Python API: uses Python binding (evidence: `README.md`)
- Python API → Python pipeline: exposes pipeline
- Application developer → TypeScript queries: uses JavaScript binding (evidence: `README.md`)
- Application developer → Debug rendering: uses debug rendering
- Debug rendering → Contact pairs: draws contacts (evidence: `src/pipeline/debug_render_pipeline/debug_render_pipeline.rs`)
- Debug rendering → Colliders and shapes: draws colliders (evidence: `src/pipeline/debug_render_pipeline/debug_render_pipeline.rs`)
