# jondolf/avian architecture

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

- Interactive diagram: https://gitdiagram.com/jondolf/avian
- Repository: https://github.com/jondolf/avian

## Overview

##### Main Components Overview

a) Core Physics Components:
- Collision System
- Dynamics System
- Spatial Query System
- Debug Rendering System
- Solver System

b) Integration Layer:
- Bevy ECS Integration
- Plugin Architecture
- Transform Synchronization

##### Detailed Component Breakdown

TOP LAYER - Integration
**[Bevy Game Engine] <---> [Avian Physics Plugin System]**

MIDDLE LAYER - Core Systems
**[Collision Detection]     [Dynamics]          [Spatial Queries]**

**[Broad Phase]        [Rigid Bodies]         [Ray Casting]**
**[Contact Detection]  [Force Systems]        [Query Filters]**

BOTTOM LAYER - Implementation
**[Parry Integration]    [XPBD Solver]    [Debug Rendering]**

##### Key Relationships to Highlight

- Data flow between systems (→)
- Dependencies (⇢)
- Plugin integration points (⇄)

**[avian2d] ─── [Common Core] ─── [avian3d]**

**[Core Physics] ←── [Pluggable Components]**
- Custom Constraints
- Custom Collision Backend
- Custom Broad Phase

##### Technical Details

- Components that support f32/f64 precision
- Parallel processing capabilities
- Integration points with Bevy's ECS
- XPBD solver architecture

##### Implementation Notes

- ECS-driven architecture
- No separate physics world (direct ECS integration)
- Modular plugin system
- Clear separation between 2D and 3D implementations while showing shared core components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style Definitions
    classDef core fill:#2196F3,color:white
    classDef integration fill:#4CAF50,color:white
    classDef pluggable fill:#FF9800,color:white
    classDef debug fill:#9C27B0,color:white
    classDef external fill:#757575,color:white

    %% Main Integration Layer
    BevyEngine["Bevy Game Engine"]:::integration
    AvianPlugin["Avian Physics Plugin"]:::integration
    click AvianPlugin "https://github.com/Jondolf/avian/blob/main/src/lib.rs"

    %% Core Systems
    subgraph CoreSystems["Core Physics Systems"]
        %% Collision System
        CollisionSystem["Collision System"]:::core
        click CollisionSystem "https://github.com/Jondolf/avian/tree/main/src/collision/"
        BroadPhase["Broad Phase"]:::core
        click BroadPhase "https://github.com/Jondolf/avian/blob/main/src/collision/broad_phase.rs"
        NarrowPhase["Narrow Phase"]:::core
        click NarrowPhase "https://github.com/Jondolf/avian/blob/main/src/collision/narrow_phase.rs"
        ContactDetection["Contact Detection"]:::core
        click ContactDetection "https://github.com/Jondolf/avian/blob/main/src/collision/contact_query.rs"

        %% Dynamics System
        DynamicsSystem["Dynamics System"]:::core
        click DynamicsSystem "https://github.com/Jondolf/avian/tree/main/src/dynamics/"
        RigidBodies["Rigid Bodies"]:::core
        click RigidBodies "https://github.com/Jondolf/avian/tree/main/src/dynamics/rigid_body/"
        Forces["Force Systems"]:::core
        click Forces "https://github.com/Jondolf/avian/blob/main/src/dynamics/rigid_body/forces.rs"
        MassProps["Mass Properties"]:::core
        click MassProps "https://github.com/Jondolf/avian/tree/main/src/dynamics/rigid_body/mass_properties/"

        %% Solver System
        SolverSystem["Solver System"]:::core
        click SolverSystem "https://github.com/Jondolf/avian/tree/main/src/dynamics/solver/"
        XPBDSolver["XPBD Solver"]:::core
        click XPBDSolver "https://github.com/Jondolf/avian/tree/main/src/dynamics/solver/xpbd/"
        Constraints["Constraints"]:::core
        click Constraints "https://github.com/Jondolf/avian/tree/main/src/dynamics/solver/joints/"
        ContactSolver["Contact Solver"]:::core
        click ContactSolver "https://github.com/Jondolf/avian/tree/main/src/dynamics/solver/contact/"

        %% Spatial Query System
        SpatialSystem["Spatial Query System"]:::core
        click SpatialSystem "https://github.com/Jondolf/avian/tree/main/src/spatial_query/"
        RayCasting["Ray Casting"]:::core
        click RayCasting "https://github.com/Jondolf/avian/blob/main/src/spatial_query/ray_caster.rs"
        ShapeCasting["Shape Casting"]:::core
        click ShapeCasting "https://github.com/Jondolf/avian/blob/main/src/spatial_query/shape_caster.rs"
        QueryFilters["Query Filters"]:::core
        click QueryFilters "https://github.com/Jondolf/avian/blob/main/src/spatial_query/query_filter.rs"
    end

    %% Debug System
    DebugSystem["Debug Rendering System"]:::debug
    click DebugSystem "https://github.com/Jondolf/avian/tree/main/src/debug_render/"
    Gizmos["Gizmos"]:::debug
    click Gizmos "https://github.com/Jondolf/avian/blob/main/src/debug_render/gizmos.rs"
    DebugConfig["Debug Configuration"]:::debug
    click DebugConfig "https://github.com/Jondolf/avian/blob/main/src/debug_render/configuration.rs"

    %% Integration Components
    TransformSync["Transform Sync"]:::integration
    click TransformSync "https://github.com/Jondolf/avian/tree/main/src/sync/"
    Schedule["Schedule Management"]:::integration
    click Schedule "https://github.com/Jondolf/avian/tree/main/src/schedule/"

    %% Dimension Implementations
    Avian2D["2D Physics"]:::core
    click Avian2D "https://github.com/Jondolf/avian/tree/main/crates/avian2d/"
    Avian3D["3D Physics"]:::core
    click Avian3D "https://github.com/Jondolf/avian/tree/main/crates/avian3d/"

    %% External Dependencies
    ParryIntegration["Parry Integration"]:::external

    %% Relationships
    BevyEngine <--> AvianPlugin
    AvianPlugin --> TransformSync
    AvianPlugin --> Schedule

    CollisionSystem --> BroadPhase
    CollisionSystem --> NarrowPhase
    CollisionSystem --> ContactDetection

    DynamicsSystem --> RigidBodies
    DynamicsSystem --> Forces
    DynamicsSystem --> MassProps

    SolverSystem --> XPBDSolver
    SolverSystem --> Constraints
    SolverSystem --> ContactSolver

    SpatialSystem --> RayCasting
    SpatialSystem --> ShapeCasting
    SpatialSystem --> QueryFilters

    DebugSystem --> Gizmos
    DebugSystem --> DebugConfig

    Avian2D --> CollisionSystem
    Avian3D --> CollisionSystem

    CollisionSystem --> ParryIntegration

    %% Legend
    subgraph Legend
        L1["Core Systems"]:::core
        L2["Integration Components"]:::integration
        L3["Debug Tools"]:::debug
        L4["External Dependencies"]:::external
    end
```
