How marcushcarter/ballistic2d works
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: application.h Application · editor_application.h Editor app · CMakeLists.txt CMake · rendering_device_driver_opengl.h OpenGL driver
Components 23
Build
Build orchestration and packaging
- CMake · Top-level build and packaging entry point
CMakeLists.txt - Embed assets · Build-time asset embedding support
cmake/EmbedAssets.cmake - Version template · Build-generated version metadata
cmake/Version.gen.h.in
Windows
Windows entrypoints and packaging
- Game main · Windows startup for the game executable
platform/windows/main_game.cpp - Editor main · Windows startup for the editor executable
platform/windows/main_editor.cpp - Console wrapper · Windows console and process wrapper
platform/windows/console_wrapper.cpp
App Core
Shared application lifecycle and engine services
- Application · Shared app lifecycle and mode coordination
core/application/application.h - Game app · Concrete game runtime behavior
core/application/game_application.h - Editor app · Concrete editor/runtime tooling behavior
core/application/editor_application.h - Errors · Shared failure reporting and macros
core/error/error.h
IO & Assets
Resource loading and embedded assets
- Embedded resource · Access to compiled-in resources and packaged data
core/io/embedded_resource.h - Image loader · Image decoding and loading pipeline
core/io/image_loader.h
Rendering
Shared rendering abstraction
- Renderer · Shared rendering interface used by the app layer
core/rendering/renderer.h
Drivers
Platform and backend integrations
- GLFW window · Windowing and input integration via GLFW
drivers/glfw/window_driver_glfw.h - ImGui driver · Dear ImGui integration for editor and tooling UI
drivers/imgui/imgui_driver.h - OpenGL driver · Low-level OpenGL device implementation
drivers/opengl/rendering_device_driver_opengl.h
Third-party
Vendored dependencies
- GLAD · Loaded OpenGL function bindings
thirdparty/glad/include/glad/glad.h - GLFW · Vendored window and input library
thirdparty/glfw - ImGui · Vendored immediate-mode UI library
thirdparty/imgui - GLM · Vendored math types and helpers
thirdparty/glm - stb_image · Vendored image decoding implementation
thirdparty/stb
Assets
Packaged shaders and editor resources
- Blit vertex · Shared vertex shader for blit/present
assets/shared/shaders/blit.vert - Blit fragment · Shared fragment shader for blit/present
assets/shared/shaders/blit.frag
Connections 27
- 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