# yjplapian/joltphysics architecture

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

- Interactive diagram: https://gitdiagram.com/yjplapian/joltphysics
- Repository: https://github.com/yjplapian/joltphysics

## Overview

##### Project Type and Purpose
- Jolt Physics is a high-performance, multi-threaded C++ physics and collision detection library targeted at games and VR applications.
- It provides rigid body simulation, collision detection (broadphase & narrowphase), constraints, soft bodies, vehicles, character controllers, water buoyancy, determinism, and a double-precision mode.

##### File Structure Overview
Top-level directories reveal a layered, modular architecture:
- Jolt/           → Core engine modules (Core, Math, Geometry, Collision, Physics, Constraints, SoftBody, Vehicle, Renderer, ObjectStream, Skeleton, etc.)
- Samples/        → Sample application showing engine features, using TestFramework and Jolt library.
- JoltViewer/     → A standalone viewer application for recording/playback of physics simulations.
- PerformanceTest/→ A console app that benchmarks engine performance.
- HelloWorld/     → Minimal example integrating Jolt via CMake FetchContent.
- UnitTests/      → Doctest-based unit tests validating each module.
- Assets/         → Runtime assets (fonts, shaders, terrains, models) consumed by TestFramework, Samples, and JoltViewer.
- Build/          → CMake scripts, platform wrappers, Gradle wrappers, and other build orchestration files.
- Docs/, README, CI configs, bindings, and integrations.

##### Key Architecture Insights from README
- The engine is built as a standalone library with no external dependencies beyond STL.
- Supports multiple platforms and CPU instruction sets via CMake build profiles.
- Emphasizes data-oriented, concurrent access to physics data (lock-free or minimal locking).
- A clear separation exists between simulation core and visualization/test harness.

##### Components
a. Core Library Module:
- Core (memory, job system, profiling)
- Math (vectors, matrices, curves)
- Geometry (hulls, GJK/EPA)
- Physics (Bodies, Scenes, Systems, Updates)
- Constraints & Motors
- SoftBody & Vehicle modules
- ObjectStream (serialization)
- Renderer hooks (DebugRenderer)
b. TestFramework Module:
- Windowing & Input (Win/Linux/macOS)
- Renderer backends (DX12, Vulkan, MTL)
- Debug UI & 2D primitives
- Asset loading (TGA/BMP, fonts)
c. Applications:
- SamplesApp
- JoltViewer
- PerformanceTest
- HelloWorld example
d. Assets:
- Fonts, shaders (HLSL/GLSL/Metal), terrains, meshes
e. Build System:
- CMake entry points, platform scripts (VS, Xcode, Ninja)
- Android/Gradle integration
- CI pipelines (GitHub Actions, SonarCloud, Doxygen)
f. Unit Tests:
- Modules tested via TestFramework and doctest

##### Relationships and Data Flows
- Build System → compiles → Core Library + TestFramework + Applications + UnitTests
- Applications → link against → Core Library + TestFramework
- Applications → load → Assets
- UnitTests → link against → Core Library (isolated)
- CI/CD → orchestrates → Build System + runs tests + static analysis + docs generation
- External Bindings/Integrations (C#, Java, Rust, Godot plugin) → consume → Core Library API

##### Architectural Patterns & Principles
- Layered Architecture: Core engine → visualization/test framework → end-user applications.
- Modularization: Each domain in its own folder, clear module boundaries.
- Data-Oriented & Lock-Minimized: JobSystem, lock-free structures in Core.
- Platform Abstraction: Renderer, Input, Window separated by platform directories.
- Build-time Configuration: CPU feature switches, precision modes via CMake options.
- CI Integration: Automated builds across platforms, code quality gates.

##### Detail and Coverage
- Major modules (Core, Math, Geometry, Physics, Collision, Constraints, SoftBody, Vehicle, ObjectStream, Renderer).
- Platform-specific submodules under TestFramework (DX12, Vulkan, MTL).
- Don’t shy away from listing submodules if it aids clarity—this is a library designed for extensibility and multi-platform support.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & CI
    subgraph "Build & CI"
        direction TB
        BuildSystem["Build System"]:::buildci
        CI["CI/CD Pipelines"]:::buildci
    end
    BuildSystem -->|compiles| CoreLib
    BuildSystem -->|compiles| TestFW
    BuildSystem -->|compiles| Clients
    BuildSystem -->|compiles| UnitTests
    CI -->|orchestrates| BuildSystem
    CI -->|runs tests & docs| UnitTests

    %% Core Library
    subgraph "Jolt Core Library"
        direction TB
        Core["Core (memory, job system, profiling)"]:::coreLib
        Math["Math (vectors, matrices, curves)"]:::coreLib
        Geometry["Geometry (hulls, GJK/EPA)"]:::coreLib
        Collision["Collision (Broadphase & Narrowphase)"]:::coreLib
        Physics["Physics (Bodies, Scenes, Systems)"]:::coreLib
        Constraints["Constraints & Motors"]:::coreLib
        SoftBody["SoftBody"]:::coreLib
        Vehicle["Vehicle"]:::coreLib
        ObjectStream["ObjectStream (serialization)"]:::coreLib
        DebugRenderer["Renderer Hooks (DebugRenderer)"]:::coreLib
    end

    %% TestFramework
    subgraph "TestFramework"
        direction TB
        WindowInput["Windowing & Input"]:::testfw
        subgraph "Renderer Backends"
            DX12["DX12"]:::testfw
            Vulkan["Vulkan"]:::testfw
            Metal["Metal"]:::testfw
        end
        DebugUI["Debug UI & 2D Primitives"]:::testfw
        AssetLoading["Asset Loading"]:::testfw
    end

    BuildSystem -->|links| Clients
    BuildSystem -->|links| CoreLib
    BuildSystem -->|links| TestFW

    %% Clients / Applications
    subgraph "Clients"
        direction TB
        SamplesApp["SamplesApp"]:::app
        JoltViewer["JoltViewer"]:::app
        PerfTest["PerformanceTest"]:::app
        HelloWorld["HelloWorld"]:::app
    end

    %% Unit Tests
    UnitTests["UnitTests"]:::testfw

    %% Assets
    Assets["Assets (fonts, shaders, terrains, models)"]:::asset

    %% External Bindings
    subgraph "External Bindings & Integrations"
        CSharp["C#"]:::ext
        Java["Java"]:::ext
        Rust["Rust"]:::ext
        Godot["Godot Plugin"]:::ext
    end

    %% Relationships
    Clients -->|link against| CoreLib
    Clients -->|link against| TestFW
    Clients -->|load| Assets
    UnitTests -->|link against| CoreLib
    CoreLib -->|exposes API| CSharp
    CoreLib -->|exposes API| Java
    CoreLib -->|exposes API| Rust
    CoreLib -->|exposes API| Godot

    %% Click Events
    click Core "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Core"
    click Math "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Math"
    click Geometry "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Geometry"
    click Collision "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Physics/Collision"
    click Physics "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Physics"
    click Constraints "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Physics/Constraints"
    click SoftBody "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Physics/SoftBody"
    click Vehicle "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Physics/Vehicle"
    click ObjectStream "https://github.com/yjplapian/joltphysics/tree/master/Jolt/ObjectStream"
    click DebugRenderer "https://github.com/yjplapian/joltphysics/tree/master/Jolt/Renderer"
    click WindowInput "https://github.com/yjplapian/joltphysics/tree/master/TestFramework/Window"
    click DX12 "https://github.com/yjplapian/joltphysics/tree/master/TestFramework/Renderer/DX12"
    click Vulkan "https://github.com/yjplapian/joltphysics/tree/master/TestFramework/Renderer/VK"
    click Metal "https://github.com/yjplapian/joltphysics/tree/master/TestFramework/Renderer/MTL"
    click DebugUI "https://github.com/yjplapian/joltphysics/tree/master/TestFramework/Application/DebugUI"
    click AssetLoading "https://github.com/yjplapian/joltphysics/tree/master/TestFramework/Utils/AssetStream"
    click SamplesApp "https://github.com/yjplapian/joltphysics/blob/master/Samples/SamplesApp.cpp"
    click JoltViewer "https://github.com/yjplapian/joltphysics/blob/master/JoltViewer/JoltViewer.cpp"
    click PerfTest "https://github.com/yjplapian/joltphysics/blob/master/PerformanceTest/PerformanceTest.cpp"
    click HelloWorld "https://github.com/yjplapian/joltphysics/blob/master/HelloWorld/HelloWorld.cpp"
    click Assets "https://github.com/yjplapian/joltphysics/tree/master/Assets/"
    click BuildSystem "https://github.com/yjplapian/joltphysics/blob/master/Build/CMakeLists.txt"
    click CI "https://github.com/yjplapian/joltphysics/tree/master/.github/workflows/"
    click UnitTests "https://github.com/yjplapian/joltphysics/tree/master/UnitTests/"

    %% Styles
    classDef coreLib fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1
    classDef testfw fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
    classDef app fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef asset fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef buildci fill:#ECEFF1,stroke:#607D8B,color:#263238
    classDef ext fill:#FFEBEE,stroke:#E53935,color:#B71C1C
```
