# marcushcarter/ballistic2d architecture

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

- Interactive diagram: https://gitdiagram.com/marcushcarter/ballistic2d
- Repository: https://github.com/marcushcarter/ballistic2d

## Overview

1. **What this repo is**
   - Ballistic2D is a C++ 2D game/editor codebase built around a shared engine core plus two Windows entrypoints: a **game** executable and an **editor/launcher** executable.
   - The architecture is split into reusable libraries and platform-specific startup code, which makes it easy to diagram as a layered application rather than a single monolith.

2. **Top-level build and packaging**
   - `CMakeLists.txt` is the main build orchestrator.
   - `cmake/EmbedAssets.cmake` indicates assets are embedded into the binary, not just loaded from disk.
   - `cmake/Version.gen.h.in` suggests version metadata is generated at build time.
   - The repository vendors third-party dependencies under `thirdparty/`, so external runtime dependencies are mostly built from source with the project.

3. **Executable boundary: platform/windows**
   - `platform/windows/main_game.cpp` and `platform/windows/main_editor.cpp` are the OS-specific entrypoints.
   - `platform/windows/console_wrapper.cpp` and the `.rc`/manifest files show Windows-specific packaging, icons, and console behavior.
   - These files are the bridge between the Windows subsystem and the cross-platform application layer.

4. **Application layer: the high-level runtime modes**
   - `core/application/` contains the app-level abstractions:
     - `application.*` likely defines the common app lifecycle.
     - `game_application.*` and `editor_application.*` are the two concrete runtime modes.
   - This is the main “mode selection” boundary: same engine foundation, different behavior depending on whether the user runs the editor or the game.

5. **Core engine services**
   - `core/rendering/renderer.*` is the central rendering abstraction used by the higher-level apps.
   - `core/error/` provides error handling and macros, indicating the engine has a shared failure/reporting path.
   - `core/version.h` and `core/io/embedded_resource.*` are supporting facilities for runtime metadata and packaged assets.

6. **Rendering stack**
   - `drivers/opengl/` contains the OpenGL backend:
     - `rendering_device_driver_opengl.*` is the low-level rendering device implementation.
     - `ballistic_opengl.h` likely aggregates OpenGL-specific definitions.
   - `assets/shared/shaders/` contains `blit.vert` and `blit.frag`, implying a minimal shared shader pipeline for textured blitting or framebuffer presentation.
   - The renderer boundary is therefore: app logic -> core renderer -> OpenGL driver -> GPU.

7. **Windowing and input boundary**
   - `drivers/glfw/window_driver_glfw.*` uses GLFW as the window/system layer.
   - This sits beneath the application layer and above the rendering backend, providing the OS window and likely input events.
   - On the diagram, GLFW should be shown as the platform-agnostic window/input adapter feeding the app and rendering system.

8. **UI/editor overlay**
   - `drivers/imgui/imgui_driver.*` integrates Dear ImGui.
   - This is likely used by the editor UI, launcher, and in-tool debugging panels rather than the shipped game loop.
   - It is a separate driver layer attached to the same window/rendering context as the rest of the engine.

9. **Asset and image loading pipeline**
   - `core/io/image_loader.*` plus `core/io/impl/stb_image_impl.cpp` show image decoding is handled through stb_image.
   - `core/io/embedded_resource.*` suggests some assets are accessed from compiled-in resources rather than the filesystem.
   - Together, this is a distinct data path: asset source -> embedded resource or loader -> runtime graphics/UI use.

10. **Third-party dependencies**
   - `thirdparty/glad` provides OpenGL function loading.
   - `thirdparty/glfw` provides windowing/input.
   - `thirdparty/imgui` provides the editor UI.
   - `thirdparty/glm` provides math types.
   - `thirdparty/stb` provides image decoding.
   - These are all vendored, so they are architecturally part of the build, not external services.

11. **Subsystem relationships**
   - The main dependency direction is bottom-up:
     - platform entrypoints start the app
     - app classes coordinate runtime mode
     - core services handle rendering, IO, and errors
     - drivers implement windowing, OpenGL, and UI
     - third-party libraries back those drivers
   - This makes the repo a classic layered engine/editor architecture with narrow platform-specific edges.

12. **How to draw the diagram**
   - Draw two top-level executables: **Editor** and **Game**.
   - Both flow into the shared **Application/Core** layer.
   - Under that, show separate service blocks for **Renderer**, **IO/Assets**, and **Error Handling**.
   - Under the renderer, show **GLFW windowing**, **ImGui UI**, and **OpenGL device driver**.
   - Add **embedded assets/shaders** as a resource input into rendering and UI.
   - Keep **Windows platform code** and **vendored third-party libraries** as external/adjacent support layers rather than core business logic.

Main entry points: [`core/application/application.h`](https://github.com/marcushcarter/ballistic2d/blob/main/core/application/application.h) (Application), [`core/application/editor_application.h`](https://github.com/marcushcarter/ballistic2d/blob/main/core/application/editor_application.h) (Editor app), [`CMakeLists.txt`](https://github.com/marcushcarter/ballistic2d/blob/main/CMakeLists.txt) (CMake), [`drivers/opengl/rendering_device_driver_opengl.h`](https://github.com/marcushcarter/ballistic2d/blob/main/drivers/opengl/rendering_device_driver_opengl.h) (OpenGL driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_cmake_root["CMake<br/>build orchestrator<br/>[CMakeLists.txt]"]
  node_embed_assets["Embed assets<br/>cmake module<br/>[EmbedAssets.cmake]"]
  node_version_template["Version template<br/>generated header template<br/>[Version.gen.h.in]"]
end

subgraph group_platform_windows["Windows"]
  node_main_game["Game main<br/>windows entrypoint<br/>[main_game.cpp]"]
  node_main_editor["Editor main<br/>windows entrypoint<br/>[main_editor.cpp]"]
  node_console_wrapper["Console wrapper<br/>windows launcher"]
end

subgraph group_core_app["App Core"]
  node_application_base["Application<br/>runtime lifecycle<br/>[application.h]"]
  node_game_app["Game app<br/>runtime mode<br/>[game_application.h]"]
  node_editor_app["Editor app<br/>runtime mode"]
  node_error_system(("Errors<br/>error handling<br/>[error.h]"))
end

subgraph group_core_io["IO & Assets"]
  node_embedded_resource["Embedded resource<br/>asset resource"]
  node_image_loader["Image loader<br/>asset loader<br/>[image_loader.h]"]
end

subgraph group_core_render["Rendering"]
  node_renderer["Renderer<br/>render abstraction<br/>[renderer.h]"]
end

subgraph group_drivers["Drivers"]
  node_window_driver["GLFW window<br/>window/input adapter"]
  node_imgui_driver["ImGui driver<br/>ui overlay<br/>[imgui_driver.h]"]
  node_opengl_driver["OpenGL driver<br/>graphics backend"]
end

subgraph group_thirdparty["Third-party"]
  node_glad["GLAD<br/>opengl loader<br/>[glad.h]"]
  node_glfw["GLFW<br/>windowing lib"]
  node_imgui["ImGui<br/>ui library"]
  node_glm["GLM<br/>math library"]
  node_stb["stb_image<br/>image decoder"]
end

subgraph group_assets["Assets"]
  node_shader_blit_vert["Blit vertex<br/>shader asset<br/>[blit.vert]"]
  node_shader_blit_frag["Blit fragment<br/>shader asset<br/>[blit.frag]"]
end

node_cmake_root -->|"includes"| node_embed_assets
node_cmake_root -->|"generates"| node_version_template
node_cmake_root -->|"builds"| node_main_game
node_cmake_root -->|"builds"| node_main_editor
node_main_game -->|"starts"| node_application_base
node_main_editor -->|"starts"| node_application_base
node_console_wrapper -->|"wraps"| node_main_editor
node_application_base -->|"selects"| node_game_app
node_application_base -->|"selects"| node_editor_app
node_application_base -->|"uses"| node_renderer
node_application_base -->|"reports"| node_error_system
node_game_app -->|"runs on"| node_window_driver
node_editor_app -->|"runs on"| node_window_driver
node_editor_app -->|"uses"| node_imgui_driver
node_renderer -->|"backed by"| node_opengl_driver
node_window_driver -->|"wraps"| node_glfw
node_opengl_driver -->|"loads via"| node_glad
node_imgui_driver -->|"wraps"| node_imgui
node_opengl_driver -->|"uses"| node_shader_blit_vert
node_opengl_driver -->|"uses"| node_shader_blit_frag
node_embedded_resource -->|"serves"| node_shader_blit_vert
node_embedded_resource -->|"serves"| node_shader_blit_frag
node_image_loader -->|"depends on"| node_stb
node_editor_app -->|"loads"| node_image_loader
node_editor_app -->|"reads"| node_embedded_resource
node_game_app -->|"reads"| node_embedded_resource
node_renderer -->|"uses"| node_glm

click node_cmake_root "https://github.com/marcushcarter/ballistic2d/blob/main/CMakeLists.txt"
click node_embed_assets "https://github.com/marcushcarter/ballistic2d/blob/main/cmake/EmbedAssets.cmake"
click node_version_template "https://github.com/marcushcarter/ballistic2d/blob/main/cmake/Version.gen.h.in"
click node_main_game "https://github.com/marcushcarter/ballistic2d/blob/main/platform/windows/main_game.cpp"
click node_main_editor "https://github.com/marcushcarter/ballistic2d/blob/main/platform/windows/main_editor.cpp"
click node_console_wrapper "https://github.com/marcushcarter/ballistic2d/blob/main/platform/windows/console_wrapper.cpp"
click node_application_base "https://github.com/marcushcarter/ballistic2d/blob/main/core/application/application.h"
click node_game_app "https://github.com/marcushcarter/ballistic2d/blob/main/core/application/game_application.h"
click node_editor_app "https://github.com/marcushcarter/ballistic2d/blob/main/core/application/editor_application.h"
click node_renderer "https://github.com/marcushcarter/ballistic2d/blob/main/core/rendering/renderer.h"
click node_window_driver "https://github.com/marcushcarter/ballistic2d/blob/main/drivers/glfw/window_driver_glfw.h"
click node_imgui_driver "https://github.com/marcushcarter/ballistic2d/blob/main/drivers/imgui/imgui_driver.h"
click node_opengl_driver "https://github.com/marcushcarter/ballistic2d/blob/main/drivers/opengl/rendering_device_driver_opengl.h"
click node_embedded_resource "https://github.com/marcushcarter/ballistic2d/blob/main/core/io/embedded_resource.h"
click node_image_loader "https://github.com/marcushcarter/ballistic2d/blob/main/core/io/image_loader.h"
click node_error_system "https://github.com/marcushcarter/ballistic2d/blob/main/core/error/error.h"
click node_glad "https://github.com/marcushcarter/ballistic2d/blob/main/thirdparty/glad/include/glad/glad.h"
click node_glfw "https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/glfw"
click node_imgui "https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/imgui"
click node_glm "https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/glm"
click node_stb "https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/stb"
click node_shader_blit_vert "https://github.com/marcushcarter/ballistic2d/blob/main/assets/shared/shaders/blit.vert"
click node_shader_blit_frag "https://github.com/marcushcarter/ballistic2d/blob/main/assets/shared/shaders/blit.frag"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake_root,node_embed_assets,node_version_template,node_glad,node_glfw,node_imgui,node_glm,node_stb toneBlue
class node_main_game,node_main_editor,node_console_wrapper,node_shader_blit_vert,node_shader_blit_frag toneAmber
class node_application_base,node_game_app,node_editor_app,node_error_system toneMint
class node_embedded_resource,node_image_loader toneRose
class node_renderer toneIndigo
class node_window_driver,node_imgui_driver,node_opengl_driver toneTeal
```

## Components

### Build

Build orchestration and packaging

- [CMake](https://github.com/marcushcarter/ballistic2d/blob/main/CMakeLists.txt): build orchestrator · Top-level build and packaging entry point · `CMakeLists.txt`
- [Embed assets](https://github.com/marcushcarter/ballistic2d/blob/main/cmake/EmbedAssets.cmake): cmake module · Build-time asset embedding support · `cmake/EmbedAssets.cmake`
- [Version template](https://github.com/marcushcarter/ballistic2d/blob/main/cmake/Version.gen.h.in): generated header template · Build-generated version metadata · `cmake/Version.gen.h.in`

### Windows

Windows entrypoints and packaging

- [Game main](https://github.com/marcushcarter/ballistic2d/blob/main/platform/windows/main_game.cpp): windows entrypoint · Windows startup for the game executable · `platform/windows/main_game.cpp`
- [Editor main](https://github.com/marcushcarter/ballistic2d/blob/main/platform/windows/main_editor.cpp): windows entrypoint · Windows startup for the editor executable · `platform/windows/main_editor.cpp`
- [Console wrapper](https://github.com/marcushcarter/ballistic2d/blob/main/platform/windows/console_wrapper.cpp): windows launcher · Windows console and process wrapper · `platform/windows/console_wrapper.cpp`

### App Core

Shared application lifecycle and engine services

- [Application](https://github.com/marcushcarter/ballistic2d/blob/main/core/application/application.h): runtime lifecycle · Shared app lifecycle and mode coordination · `core/application/application.h`
- [Game app](https://github.com/marcushcarter/ballistic2d/blob/main/core/application/game_application.h): runtime mode · Concrete game runtime behavior · `core/application/game_application.h`
- [Editor app](https://github.com/marcushcarter/ballistic2d/blob/main/core/application/editor_application.h): runtime mode · Concrete editor/runtime tooling behavior · `core/application/editor_application.h`
- [Errors](https://github.com/marcushcarter/ballistic2d/blob/main/core/error/error.h): error handling · Shared failure reporting and macros · `core/error/error.h`

### IO & Assets

Resource loading and embedded assets

- [Embedded resource](https://github.com/marcushcarter/ballistic2d/blob/main/core/io/embedded_resource.h): asset resource · Access to compiled-in resources and packaged data · `core/io/embedded_resource.h`
- [Image loader](https://github.com/marcushcarter/ballistic2d/blob/main/core/io/image_loader.h): asset loader · Image decoding and loading pipeline · `core/io/image_loader.h`

### Rendering

Shared rendering abstraction

- [Renderer](https://github.com/marcushcarter/ballistic2d/blob/main/core/rendering/renderer.h): render abstraction · Shared rendering interface used by the app layer · `core/rendering/renderer.h`

### Drivers

Platform and backend integrations

- [GLFW window](https://github.com/marcushcarter/ballistic2d/blob/main/drivers/glfw/window_driver_glfw.h): window/input adapter · Windowing and input integration via GLFW · `drivers/glfw/window_driver_glfw.h`
- [ImGui driver](https://github.com/marcushcarter/ballistic2d/blob/main/drivers/imgui/imgui_driver.h): ui overlay · Dear ImGui integration for editor and tooling UI · `drivers/imgui/imgui_driver.h`
- [OpenGL driver](https://github.com/marcushcarter/ballistic2d/blob/main/drivers/opengl/rendering_device_driver_opengl.h): graphics backend · Low-level OpenGL device implementation · `drivers/opengl/rendering_device_driver_opengl.h`

### Third-party

Vendored dependencies

- [GLAD](https://github.com/marcushcarter/ballistic2d/blob/main/thirdparty/glad/include/glad/glad.h): opengl loader · Loaded OpenGL function bindings · `thirdparty/glad/include/glad/glad.h`
- [GLFW](https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/glfw): windowing lib · Vendored window and input library · `thirdparty/glfw`
- [ImGui](https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/imgui): ui library · Vendored immediate-mode UI library · `thirdparty/imgui`
- [GLM](https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/glm): math library · Vendored math types and helpers · `thirdparty/glm`
- [stb_image](https://github.com/marcushcarter/ballistic2d/tree/main/thirdparty/stb): image decoder · Vendored image decoding implementation · `thirdparty/stb`

### Assets

Packaged shaders and editor resources

- [Blit vertex](https://github.com/marcushcarter/ballistic2d/blob/main/assets/shared/shaders/blit.vert): shader asset · Shared vertex shader for blit/present · `assets/shared/shaders/blit.vert`
- [Blit fragment](https://github.com/marcushcarter/ballistic2d/blob/main/assets/shared/shaders/blit.frag): shader asset · Shared fragment shader for blit/present · `assets/shared/shaders/blit.frag`

## Connections

- CMake → Embed assets: includes · Build uses asset embedding rules
- CMake → Version template: generates · Build generates version metadata
- CMake → Game main: builds · Build produces the game executable entrypoint
- CMake → Editor main: builds · Build produces the editor executable entrypoint
- Game main → Application: starts · Game entrypoint launches shared application lifecycle
- Editor main → Application: starts · Editor entrypoint launches shared application lifecycle
- Console wrapper → Editor main: wraps · Windows console helper supports the editor/runtime launch path
- Application → Game app: selects · Shared app layer instantiates the game mode
- Application → Editor app: selects · Shared app layer instantiates the editor mode
- Application → Renderer: uses · Application coordinates rendering services
- Application → Errors: reports · Shared lifecycle routes failures through common error handling
- Game app → GLFW window: runs on · Game mode uses window/input services
- Editor app → GLFW window: runs on · Editor mode uses window/input services
- Editor app → ImGui driver: uses · Editor mode attaches immediate-mode UI
- Renderer → OpenGL driver: backed by · Shared renderer is implemented by the OpenGL backend
- GLFW window → GLFW: wraps · Window driver is built on GLFW
- OpenGL driver → GLAD: loads via · OpenGL backend uses GLAD for function loading
- ImGui driver → ImGui: wraps · UI driver integrates Dear ImGui
- OpenGL driver → Blit vertex: uses · OpenGL backend consumes shared presentation shader
- OpenGL driver → Blit fragment: uses · OpenGL backend consumes shared presentation shader
- Embedded resource → Blit vertex: serves · Embedded resource path can provide packaged assets
- Embedded resource → Blit fragment: serves · Embedded resource path can provide packaged assets
- Image loader → stb_image: depends on · Image loading is implemented with stb_image
- Editor app → Image loader: loads · Editor mode can load images and UI resources
- Editor app → Embedded resource: reads · Editor mode consumes embedded assets and metadata
- Game app → Embedded resource: reads · Game mode can consume packaged resources
- Renderer → GLM: uses · Rendering stack relies on shared math types
