How marcushcarter/ballistic works
Purpose and Build Surface
Ballistic is a C++ graphics/game-engine-style runtime with an integrated editor, built through CMake. The root build composes core, drivers, editor, platform, and third-party code: CMakeLists.txt, core/CMakeLists.txt, editor/CMakeLists.txt. Assets can be embedded at build time via cmake/EmbedAssets.cmake.
Process Entry Points
Windows platform launch code selects the executable startup path and application mode: platform/windows/ballistic_main.cpp, platform/windows/ballistic_console_wrapper.cpp. Runtime application abstractions are centered in core/application/application.h and core/application/application.cpp; specialized editor and game applications are editor/editor_application.cpp and game/game_application.cpp.
Core Runtime and Project Boundary
The core layer owns application lifecycle, project state, asset identifiers, paths, logging, and image/resource access. Project-level state is represented by core/project/project.h and core/project/project.cpp; stable asset identity uses core/assets/guid.h. Embedded-resource and filesystem/image I/O form the asset-access boundary in core/io/embedded_resource.h, core/io/path.h, and core/io/image_io.h.
Rendering Architecture
Rendering is organized as a render graph executed by a renderer over a render context: core/rendering/render_graph.h, core/rendering/renderer.h, core/rendering/render_context.h. The graph/profiler boundary permits inspection of pass and resource execution through core/rendering/render_graph_profiler.cpp. Render paths select high-level modes—editor, game, project manager, or scene—via core/rendering/render_path/render_path.cpp and the headers under core/rendering/render_path/.
Render Features and Frame Flow
A chosen render path assembles feature passes into the graph. Core stages include geometry, visibility, presentation, and editor overlays: core/rendering/features/geometry_feature.cpp, core/rendering/features/visibility_feature.cpp, core/rendering/features/present_feature.cpp, core/rendering/features/editor/imgui_feature.cpp. Experimental/test graphics features (ambient occlusion, deferred lighting, subsurface scattering) are isolated under core/rendering/features/test/, indicating they are optional rather than the primary pipeline.
Platform and GPU Drivers
Rendering depends on Vulkan-specific context and device drivers: drivers/vulkan/context_driver_vulkan.cpp, drivers/vulkan/device_driver_vulkan.cpp, with Vulkan Memory Allocator implementation in drivers/vulkan/impl/vk_mem_alloc_impl.cpp. The native desktop boundary is Win32 windowing and dialogs: drivers/windows/window_driver_win32.cpp, drivers/windows/dialogs_win32.cpp. ImGui integration bridges editor UI to GPU textures through drivers/imgui/imgui_driver.cpp and drivers/imgui/imgui_texture_cache.cpp.
Editor Surface and Observability
The editor orchestrates UI, viewport rendering, project management, settings, console output, and profiling: editor/editor.cpp, editor/editor_ui.cpp, editor/viewport/viewport.cpp. It exposes runtime observability through render/resource/timeline profilers and memory profiling: editor/profiler/profiler.cpp, editor/profiler/profiler_resources.cpp, editor/memory_profiler/memory_profiler.cpp. External dependencies are vendored/submoduled under thirdparty/, notably ImGui, ImPlot, GLM, STB, and IconFontCppHeaders.
Main entry points: application.cpp Application lifecycle · editor.cpp Editor orchestration · render_graph.h Render graph · CMakeLists.txt CMake build
Components 21
Build
- CMake build · Composes runtime, editor, drivers, platform, and third-party code.
CMakeLists.txt - Asset embedding · Embeds assets into build outputs.
cmake/EmbedAssets.cmake
Application runtime
- Windows entry · Selects executable startup path and application mode.
platform/windows/ballistic_main.cpp - Application lifecycle · Base runtime application abstraction.
core/application/application.cpp - Editor application
editor/editor_application.cpp - Game application
game/game_application.cpp - Project state · Owns project-level state and asset identity.
core/project/project.cpp - Asset access · Provides embedded-resource, path, and image access.
core/io/embedded_resource.h
Rendering
- Render path selection · Chooses editor, game, project manager, or scene rendering.
core/rendering/render_path/render_path.cpp - Renderer · Executes rendering over a render context.
core/rendering/renderer.h - Render graph · Organizes passes and resources for a frame.
core/rendering/render_graph.h - Core render passes · Geometry, visibility, and presentation stages.
core/rendering/features/geometry_feature.cpp - Editor overlay pass
core/rendering/features/editor/imgui_feature.cpp - Render graph profiler · Inspects graph pass and resource execution.
core/rendering/render_graph_profiler.cpp
Platform & GPU drivers
- Vulkan context & device · Supplies Vulkan rendering context and device services.
drivers/vulkan/context_driver_vulkan.cpp - Win32 window & dialogs
drivers/windows/window_driver_win32.cpp - ImGui GPU bridge · Bridges editor UI textures to the GPU.
drivers/imgui/imgui_driver.cpp
Editor & observability
- Editor orchestration · Coordinates UI, viewport, project management, settings, and console.
editor/editor.cpp - Editor viewport
editor/viewport/viewport.cpp - Editor profiling · Exposes render, resource, timeline, and memory profiling.
editor/profiler/profiler.cpp
Other components
- Vendored dependencies · Includes ImGui, ImPlot, GLM, STB, and IconFontCppHeaders.
Connections 24
- CMake build → Asset embedding: includes
- CMake build → Application lifecycle: builds
- CMake build → Editor orchestration: builds
- Windows entry → Application lifecycle: starts
- Application lifecycle → Editor application: selects editor mode
- Application lifecycle → Game application: selects game mode
- Application lifecycle → Project state: owns lifecycle
- Project state → Asset access: resolves assets
- Application lifecycle → Render path selection: selects mode
- Render path selection → Render graph: assembles
- Core render passes → Render graph: adds passes
- Editor overlay pass → Render graph: adds overlay
- Renderer → Render graph: executes
- Renderer → Vulkan context & device: uses GPU services
- Render graph → Render graph profiler: reports execution
- Editor application → Editor orchestration: hosts
- Editor orchestration → Editor viewport: manages
- Editor viewport → Render path selection: drives editor rendering
- Editor orchestration → ImGui GPU bridge: renders UI through
- ImGui GPU bridge → Editor overlay pass: supplies textures
- Editor orchestration → Editor profiling: exposes
- Editor profiling → Render graph profiler: presents data
- Application lifecycle → Win32 window & dialogs: uses native windowing
- Vendored dependencies → Editor orchestration: provides UI libraries