# jwalts37/retroflightsim architecture

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

- Interactive diagram: https://gitdiagram.com/jwalts37/retroflightsim
- Repository: https://github.com/jwalts37/retroflightsim

## Overview

##### Main Components
a. **Browser Host & Web Platform**
– The ultimate runtime environment: HTML5 + Canvas/WebGL + Audio APIs.
b. **Entry Point & Bootstrapping**
– `src/index.html`, `webpack.config.js` → Builds `dist/index.html` & `bundle.js`.
c. **Core Kernel / Game Loop**
– `src/script/core/kernel.ts` orchestrates the fixed-timestep update and render cycle.
d. **Configuration Service**
e. **Input Subsystem**
– Keyboard & Joystick devices under `src/script/input/devices`.
f. **Audio Subsystem**
– `audioResources.ts` loads `.ogg` assets; `audioSystem.ts` plays engine loops, effects.
g. **State Management**
– `src/script/state/game.ts` + camera updaters. Holds world state, game definitions, and camera logic.
h. **Physics Engine**
– Models (debug, arcade, realistic) in `src/script/physics/model`, plus particle emitters under `particles`.
i. **Scene Graph & Rendering Pipeline**
– Scene setup in `src/script/scene/scene.ts`, entity management, materials & shaders, plus Canvas/WebGL painters and helpers in `src/script/render`.
j. **OSD / UI Layer**
– On-screen display panels under `src/script/osd`, overlays, HUD, messages.
k. **Asset Data**
– GLTF/GLB models in `assets/`, Blender sources in `data/`.

##### Relationships & Interactions
– The **Kernel** drives the cycle:
1) Read **Config** (palette, profile) & **Input** (keyboard/joystick)
2) Update **Game State** (controls, physics, particles)
3) Update **Camera** via camera updaters
4) Execute **Render Pipeline** (scene traversal, shader passes, canvas painter)
5) Dispatch **Audio** events (engine sound, effects)
– **Assets** (models, audio loops) are loaded at startup by their respective subsystems.
– **Config Service** injects palette definitions into the renderer for day/night and IR modes.
– **Physics Engine** writes back updated positions to the **Scene Graph**, which the **Renderer** reads.

##### Architectural Patterns & Principles
– **Modular Subsystems**: clear separation of concerns (Input, Audio, Physics, Render, State).
– **Entity-Component-System Flavor**: Entities in the scene, components (physics model, visual model, particle emitter).
– **Fixed-Timestep Game Loop** for determinism.
– **Dependency Injection** via services (ConfigService, AudioResources).
– **Immutable vs Mutable State**: state updates happen in a single pass per tick.

##### Essential Details to Capture
– **Asset Loading** phase (at startup).
– **ConfigService** feeding into multiple subsystems (Render uses palette, Input uses keyboard layout).
– **State** as the single source of truth for world and camera data.
– The two separate output channels:
- Visual → Canvas/WebGL (scene + OSD)
- Audio → Web Audio API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External / Browser Host
    subgraph "Browser Host & Web Platform"
        direction TB
        BrowserAPIs["HTML5 Canvas/WebGL<br/>Web Audio API"]:::external
    end

    %% Entry & Build
    subgraph "Entry Point & Bootstrapping"
        direction TB
        IndexHTML["src/index.html"]:::external
        WebpackConfig["webpack.config.js"]:::external
        EntryTS["src/script/index.ts"]:::external
        IndexHTML -->|loads| EntryTS
        EntryTS -->|bundles via Webpack| WebpackConfig
    end

    %% Kernel Core Loop
    Kernel["Core Kernel<br/>(fixed-timestep loop)"]:::core

    %% Subsystems
    subgraph "Subsystems"
        direction TB
        ConfigService["Config Service"]:::service
        InputSubsystem["Input Subsystem"]:::service
        AudioSubsystem["Audio Subsystem"]:::service
        StateMgmt["State Management"]:::service
        PhysicsEngine["Physics Engine"]:::service
        SceneRender["Scene & Render Pipeline"]:::service
        OSD["OSD / UI Layer"]:::service
    end

    %% Assets & Data
    subgraph "Asset Data"
        direction TB
        Models["3D Models (.gltf/.glb)"]:::data
        AudioFiles["Audio Files (.ogg)"]:::data
        BlendSources["Blender Sources"]:::data
    end

    %% Build Output
    subgraph "Build Output (dist)"
        direction TB
        OutHTML["dist/index.html"]:::external
        OutBundle["dist/bundle.js"]:::external
        OutStyle["dist/style.css"]:::external
        OutAssets["dist/assets/**"]:::external
    end

    %% Startup Flow
    BrowserAPIs -->|boot| IndexHTML
    IndexHTML -->|init| Kernel
    Kernel -->|load config| ConfigService
    Kernel -->|load assets| Models
    Kernel -->|load assets| AudioFiles
    ConfigService -->|provide palettes/profiles| SceneRender
    Kernel -->|listen| InputSubsystem
    Kernel -->|initialize| AudioSubsystem
    Kernel -->|init state| StateMgmt
    Kernel -->|init physics| PhysicsEngine
    Kernel -->|init scene| SceneRender
    Kernel -->|init OSD| OSD

    %% Frame Loop
    Kernel -->|"1) Read Input"| InputSubsystem
    Kernel -->|"2) Update State"| StateMgmt
    StateMgmt -->|"provides world data"| PhysicsEngine
    PhysicsEngine -->|"updates positions"| SceneRender
    Kernel -->|"3) Update Camera"| StateMgmt
    Kernel -->|"4) Render Frame"| SceneRender
    SceneRender -->|draw| BrowserAPIs
    Kernel -->|"5) Play Audio"| AudioSubsystem
    AudioSubsystem -->|play via| BrowserAPIs
    Kernel -->|"6) Draw UI"| OSD
    OSD -->|overlay draw| BrowserAPIs

    %% Build step
    EntryTS -->|Webpack build| OutHTML
    EntryTS --> OutBundle
    EntryTS --> OutStyle
    Models --> OutAssets
    AudioFiles --> OutAssets

    %% Click events for component mapping
    click IndexHTML "https://github.com/jwalts37/retroflightsim/blob/main/src/index.html"
    click WebpackConfig "https://github.com/jwalts37/retroflightsim/blob/main/webpack.config.js"
    click EntryTS "https://github.com/jwalts37/retroflightsim/blob/main/src/script/index.ts"
    click Kernel "https://github.com/jwalts37/retroflightsim/blob/main/src/script/core/kernel.ts"
    click ConfigService "https://github.com/jwalts37/retroflightsim/blob/main/src/script/config/configService.ts"
    click ConfigService "https://github.com/jwalts37/retroflightsim/blob/main/src/script/config/palettes/*.ts"
    click ConfigService "https://github.com/jwalts37/retroflightsim/blob/main/src/script/config/profiles/*.ts"
    click InputSubsystem "https://github.com/jwalts37/retroflightsim/blob/main/src/script/input/devices/keyboardControlDevice.ts"
    click InputSubsystem "https://github.com/jwalts37/retroflightsim/blob/main/src/script/input/devices/joystickControlDevice.ts"
    click AudioSubsystem "https://github.com/jwalts37/retroflightsim/blob/main/src/script/audio/audioResources.ts"
    click AudioSubsystem "https://github.com/jwalts37/retroflightsim/blob/main/src/script/audio/audioSystem.ts"
    click StateMgmt "https://github.com/jwalts37/retroflightsim/blob/main/src/script/state/game.ts"
    click StateMgmt "https://github.com/jwalts37/retroflightsim/blob/main/src/script/state/cameraUpdaters/*.ts"
    click StateMgmt "https://github.com/jwalts37/retroflightsim/blob/main/src/script/state/gameDefs.ts"
    click StateMgmt "https://github.com/jwalts37/retroflightsim/blob/main/src/script/state/stateUtils.ts"
    click PhysicsEngine "https://github.com/jwalts37/retroflightsim/blob/main/src/script/physics/model/arcadeFlightModel.ts"
    click PhysicsEngine "https://github.com/jwalts37/retroflightsim/blob/main/src/script/physics/model/debugFlightModel.ts"
    click PhysicsEngine "https://github.com/jwalts37/retroflightsim/blob/main/src/script/physics/model/realisticFlightModel.ts"
    click PhysicsEngine "https://github.com/jwalts37/retroflightsim/blob/main/src/script/physics/model/flightModel.ts"
    click PhysicsEngine "https://github.com/jwalts37/retroflightsim/blob/main/src/script/physics/particles/particleSystem.ts"
    click PhysicsEngine "https://github.com/jwalts37/retroflightsim/blob/main/src/script/physics/particles/emitters/*.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/scene/scene.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/scene/entity.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/scene/cameras/camera.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/tree/main/src/script/scene/entities/**"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/scene/materials/materials.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/scene/materials/shaders/*.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/scene/models/models.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/scene/models/lib/*.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/render/renderer.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/render/helpers.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/render/screen/canvasPainter.ts"
    click SceneRender "https://github.com/jwalts37/retroflightsim/blob/main/src/script/render/screen/*.ts"
    click OSD "https://github.com/jwalts37/retroflightsim/blob/main/src/script/osd/osdPanel.ts"

    %% Styles
    classDef data fill:#AED6F1,stroke:#2980B9,color:#154360
    classDef service fill:#ABEBC6,stroke:#27AE60,color:#145A32
    classDef core fill:#F5CBA7,stroke:#E67E22,color:#87421F
    classDef external fill:#D5D8DC,stroke:#A6ACAF,color:#566573
    class BrowserAPIs,OutHTML,OutBundle,OutStyle,OutAssets external
    class IndexHTML,WebpackConfig,EntryTS external
    class Kernel core
    class ConfigService,InputSubsystem,AudioSubsystem,StateMgmt,PhysicsEngine,SceneRender,OSD service
    class Models,AudioFiles,BlendSources data
```
