# jrouwe/joltphysics architecture

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

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

## Overview

##### Main Components
- Physics Engine Core:
– Jolt/Core: Contains low-level utilities, memory management, job systems (single-threaded and thread pools), and profiler support.
– Jolt/Math: Provides vector, matrix, quaternion operations, and other mathematical utilities.
– Jolt/Geometry: Implements spatial partitioning (AABB trees, Morton codes) and geometric calculations.
– Jolt/Physics: This is the heart of the simulation. Break it down into submodules such as:
○ Body, Character, and Collision (rigid body simulation, collision detection with broadphase and narrow phase).
○ Constraints (hinge, slider, distance, fixed constraints, etc.) and Job systems to support multi-core processing.
○ Vehicles, SoftBody, Ragdoll for simulating more specialized dynamics.
– ObjectStream: Handles serialization and deserialization of physics data.
- External/Support Components:
– TestFramework: The rendering and input framework used by both the Sample applications and the JoltViewer; includes support for multiple graphics APIs (DX, Metal, Vulkan).
– JoltViewer: Provides a standalone debugging/visualization application for recorded simulation output (using the debug renderer classes).
– Samples & PerformanceTest: These are demonstration applications that show usage of the engine and measure its performance.
– Assets & Shaders: These include the fonts, shader sources (for different rendering APIs), and other resources that the test framework or viewer will load.
– Build Scripts, CMake files, and platform-specific configurations that allow building on Windows, Linux, macOS, Android, etc.

##### Relationships and Data Flow
- That the Physics module has direct subcomponents for Collision Detection (broad phase and narrow phase), Constraint Solvers, and Simulation update.
- Sample applications using the TestFramework for rendering and user input, while also interfacing with the core physics simulation.

##### Architectural Patterns & Principles
- Modularity: Emphasize that the engine is split into logically separated yet interdependent modules (Physics, Geometry, Math, etc.).
- Multi-threading and Determinism: Mark the use of job systems from the Core module which allow simulations to run concurrently with collision queries and background scene updates.
- Separation of Concerns: Illustrate how simulation, visualization, and testing are kept in independent modules (Jolt, TestFramework, Samples).
- Platform Abstraction: The existence of separate rendering directories (DX, MTL, VK) in both Assets/Shaders and TestFramework/Renderer indicates that rendering is abstracted to support multiple platforms.

##### Relevant Technologies, Frameworks, and Libraries
- C++ 17 is used with heavy reliance on the STL (with custom memory management, without RTTI or exceptions).
- Multi-threading, SIMD instructions (SSE2, SSE4.1 through AVX variants on x86/x64; NEON on ARM), and a custom job system.
- Rendering support for DirectX 12, Metal (MTL), Vulkan (VK), and integration with sample apps and viewer based on these APIs.
- CMake is used for build configuration across multiple platforms.

##### Specific Elements
- Clear boundaries for each module (e.g., “Core & Math”, “Geometry”, “Physics”, “Collision”, “Constraints”).
– Simulation update cycle from the physics engine into the debug renderer.
– Resource loading (from Assets/Shaders) into the TestFramework for rendering.
– Build system connections with different platform-specific configurations.
- Labels to indicate that modules support multi-threading (job system) and deterministic simulation.
- Notation that the physics engine supports a variety of body types and constraints with examples (rigid bodies, vehicles, soft bodies, ragdolls).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Engine Subgraph
    subgraph "Core Engine"
        node1["Core Engine Core"]:::core
        node2["Physics Math"]:::core
        node3["Physics Geometry"]:::core
        node4["Physics Simulation"]:::core
        node5["Object Serialization"]:::core
    end

    %% External/Support Subgraph
    subgraph "External/Support"
        node6["Test Framework"]:::support
        node7["Debug/Visualization"]:::support
        node8["Sample Applications & PerformanceTest"]:::support
        node9["Assets"]:::support
        node10["Shaders"]:::support
        node11["Build & Platform Configurations"]:::build
    end

    %% Internal Core Relationships
    node1 -->|"jobSystem"| node4
    node2 -->|"mathSupport"| node4
    node3 -->|"geometryCalc"| node4

    %% Data flow from Physics Simulation to external systems
    node4 -->|"simResults"| node6
    node4 -->|"debugData"| node7

    %% External Modules Dependencies
    node8 -->|"uses"| node6
    node9 -->|"resources"| node6
    node10 -->|"resources"| node6

    %% Build System orchestrates core modules
    node11 -->|"buildCnf"| node1
    node11 -->|"buildCnf"| node2
    node11 -->|"buildCnf"| node3
    node11 -->|"buildCnf"| node4
    node11 -->|"buildCnf"| node5

    %% Styles
    classDef core fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef support fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef build fill:#D5F5E3,stroke:#239B56,stroke-width:2px;

    %% Click Events
    click node1 "https://github.com/jrouwe/joltphysics/tree/master/Jolt/Core"
    click node2 "https://github.com/jrouwe/joltphysics/tree/master/Jolt/Math"
    click node3 "https://github.com/jrouwe/joltphysics/tree/master/Jolt/Geometry"
    click node4 "https://github.com/jrouwe/joltphysics/tree/master/Jolt/Physics"
    click node5 "https://github.com/jrouwe/joltphysics/tree/master/Jolt/ObjectStream"
    click node6 "https://github.com/jrouwe/joltphysics/tree/master/TestFramework"
    click node7 "https://github.com/jrouwe/joltphysics/tree/master/JoltViewer"
    click node8 "https://github.com/jrouwe/joltphysics/tree/master/Samples"
    click node9 "https://github.com/jrouwe/joltphysics/tree/master/Assets"
    click node10 "https://github.com/jrouwe/joltphysics/tree/master/Assets/Shaders"
    click node11 "https://github.com/jrouwe/joltphysics/tree/master/Build"
```
