# ihmcrobotics/simulation-construction-set-2 architecture

> Architecture diagram of the GitHub repository ihmcrobotics/simulation-construction-set-2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ihmcrobotics/simulation-construction-set-2
- Repository: https://github.com/ihmcrobotics/simulation-construction-set-2

## Overview

##### Project type and purpose
- This is a multi-module Java monorepo for a desktop simulation platform (“SCS2”) comprising:
- Core definition & IO libraries (robot, terrain, visuals)
- Simulation backends (built-in physics, Bullet bridge)
- Session management & buffering (in-memory & shared-memory)
- Logging & remote session support (MCAP, video scrubbers)
- Visualization layers (engine-agnostic + JavaFX GUI)
- Examples, symbolic equation support, packaging and CI

- scs2-definition
- scs2-shared-memory
- scs2-session
- scs2-simulation
- scs2-bullet-simulation
- scs2-session-logger
- scs2-session-visualizer (core)
- scs2-session-visualizer-jfx (JavaFX GUI)
- scs2-simulation-construction-set (bundled application entry point)
- scs2-symbolic, scs2-examples (auxiliary/library consumers)

##### Relationships and data flow
- Definitions → consumed by Simulation backends & GUI
- Simulation engines (SCS2 core + Bullet) → produce YoVariables & RobotState
- Shared-memory & session modules → buffer those variables over time
- Session-logger → reads from session buffer → writes log files (MCAP, video) or serves remote clients
- Visualizer modules → read live or logged session data → render 2D/3D graphics via JavaFX
- The “SimulationConstructionSet2” top-level app pulls all layers together

##### Architectural patterns & principles
- Layered + plugin-style physics engines via Factory interfaces
- Clear separation between:
- Definition (data models & IO)
- Simulation (computation)
- Session (buffering & control)
- Logging/Remote (persistence & streaming)
- Visualization (rendering & GUI)
- Multi-project Gradle build orchestrates module dependencies
- Use of JavaFX for GUI, MCAP for log format, URDF/SDF tools, Bullet native bridge

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Definition Layer
    subgraph "Definition Layer"
        direction TB
        DEF["scs2-definition"]:::core
        SHM["scs2-shared-memory"]:::core
    end

    %% Simulation Engines Layer
    subgraph "Simulation Engines"
        direction TB
        SIM["scs2-simulation"]:::engine
        BULLET["scs2-bullet-simulation"]:::engine
    end

    %% Session Layer
    subgraph "Session & Buffering"
        direction TB
        SESSION["scs2-session"]:::session
    end

    %% Logging Layer
    subgraph "Logging & Remote"
        direction TB
        LOGGER["scs2-session-logger"]:::logger
    end

    %% Visualization Layer
    subgraph "Visualization"
        direction TB
        VIS_CORE["scs2-session-visualizer"]:::viz
        VIS_JFX["scs2-session-visualizer-jfx"]:::viz
    end

    %% Application Entry
    APP["scs2-simulation-construction-set"]:::app

    %% Examples & Symbolic
    subgraph "Auxiliary Modules"
        direction TB
        SYM["scs2-symbolic"]:::example
        EXAM["scs2-examples"]:::example
    end

    %% Data Flows
    DEF -->|"definitions"| SIM
    DEF -->|"definitions"| BULLET
    SHM -->|"shared buffer"| SESSION
    SIM -->|"YoVariables & RobotState"| SESSION
    BULLET -->|"YoVariables & RobotState"| SESSION
    SESSION -->|"buffer stream"| LOGGER
    SESSION -->|"live data"| VIS_CORE
    SESSION -->|"live data"| VIS_JFX
    LOGGER -->|"MCAP log playback"| VIS_CORE
    LOGGER -->|"MCAP log playback"| VIS_JFX
    VIS_JFX -->|"GUI control"| SESSION

    %% App orchestration
    APP --> DEF
    APP --> SHM
    APP --> SIM
    APP --> BULLET
    APP --> SESSION
    APP --> LOGGER
    APP --> VIS_JFX

    %% Aux dependencies
    SYM -->|"uses definitions"| DEF
    EXAM -->|"uses definitions"| DEF

    %% Click Events
    click DEF "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-definition/"
    click SHM "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-shared-memory/"
    click SESSION "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-session/"
    click SIM "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-simulation/"
    click BULLET "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-bullet-simulation/"
    click LOGGER "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-session-logger/"
    click VIS_CORE "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-session-visualizer/"
    click VIS_JFX "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-session-visualizer-jfx/"
    click APP "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-simulation-construction-set/"
    click SYM "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-symbolic/"
    click EXAM "https://github.com/ihmcrobotics/simulation-construction-set-2/tree/develop/scs2-examples/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef engine fill:#90EE90,stroke:#000
    classDef session fill:#FFFFE0,stroke:#000
    classDef logger fill:#FFA500,stroke:#000
    classDef viz fill:#D8BFD8,stroke:#000
    classDef example fill:#D3D3D3,stroke:#000
    classDef app fill:#B0C4DE,stroke:#000
```
