helios is a custom game framework built from first principles, written in modern C++23.
Before building helios, ensure your system meets the required software prerequisites. See PREREQUISITES.md for detailed installation instructions for your platform.
Quick Summary:
- CMake 4.0+
- C++23-capable compiler (MSVC 2022, GCC 13+, Clang 17+)
- OpenGL 4.5+ support
- Ninja or Make (optional but recommended)
# Clone
git clone https://github.com/thorstensuckow/helios.git
cd helios
# Configure
cmake -S . -B build
# Build
cmake --build build --config Release
# Run an example
cd build/examples/scoring_demo/Release
./scoring_demo- C++23 module-based architecture (
.ixxinterface units) - SparseSet-based Entity-Component-System with versioned handles and type-erased systems
- Hierarchical scene graph with selective transform inheritance
- Phase-based game loop (
Pre/Main/Post) with typed passes and double-buffered event buses - Compile-time typed command buffer and handler routing
- Type-indexed resource registry for managers, command buffers, and handlers
- Template-based state management (
GameState,MatchState) with transition guards - Object pooling with prefab cloning via component reflection
- Spawn scheduling with configurable profiles, rules, and placers
- Grid-based collision detection with layers and masks
- Health, damage, scoring, timer, and lives systems
- OpenGL 4.5+ rendering backend with shader and material system
- FreeType-based text rendering
- UI system with menus, anchored transforms, and text components
- ImGui debug overlay (FPS, camera, gamepad, logging, state visualization)
- Fluent builder APIs for game object and spawn configuration
- Strongly-typed identifiers (
StrongId<Tag>) with FNV-1a hashing - Developed and tested on Windows (MSVC 2022); Linux and macOS are untested
helios is an educational project to explore the intricacies of game engine architecture. Each component is built from first principles: the primary goal is to apply and analyze modern software engineering in a performance-critical domain while implementing the mathematical building blocks of 2D and 3D graphics.
The framework uses a modern C++23 module-based architecture (.ixx interface units), providing a clean and robust dependency graph for fast compilation. External dependencies are fetched via CMake FetchContent (GLFW 3.4, GLAD 2.0.8, FreeType 2.14.1, Dear ImGui).
The initial rendering backend is implemented using OpenGL 4.6.
Note: If the build fails due to compiler or CMake version issues, refer to PREREQUISITES.md.
The development process emphasizes understanding both the mathematical foundations and the rationale behind established patterns, such as trade-offs between indirect and direct data storage, the division of labor between CPU-side culling and GPU-side clipping, or the performance characteristics of SparseSet-based ECS versus inheritance-based designs.
This project originated as a semester project for a computer science degree. The design principles, architecture, and prototypical implementation for the first milestone are documented in the following technical report:
- [Suc25] Suckow-Homberg, Thorsten: helios: Design and prototypical implementation of a C++ game framework (2025), ResearchGate
.
├── benchmarks/ # Performance benchmarks for selected modules
├── docs/ # Documentation and core-concepts guides
│ └── core-concepts/ # Architectural documentation (ECS, commands, state, ...)
├── examples/ # Example applications (9 demos)
├── include/
│ ├── ext/ # Platform extensions (GLFW, OpenGL, ImGui)
│ └── helios/ # Framework module interface units (.ixx)
├── tests/ # Unit tests (Google Test / CTest)
└── website/ # Docusaurus project website
- C++23 compatible compiler:
- MSVC 19.38+ (Visual Studio 2022)
- GCC 13.2+
- Clang 17+
- CMake 4.0+
- Git
# Configure
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
# Build
cmake --build build --config Release
# Run tests
cd build
ctest -C Release --output-on-failureNote: helios has only been tested on Windows with MSVC 2022. The commands below are provided for reference but are untested.
# Configure
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
# Build
cmake --build build
# Run tests
cd build
ctest --output-on-failure| Option | Description |
|---|---|
-DCMAKE_BUILD_TYPE=Debug |
Build with debug symbols |
-DCMAKE_BUILD_TYPE=Release |
Build optimized release version |
-DBUILD_TESTING=OFF |
Disable test targets |
-DBUILD_EXAMPLES=OFF |
Disable example targets |
-DBUILD_BENCHMARKS=OFF |
Disable benchmark targets |
After building, example executables are located in:
build/examples/<example_name>/Release/
Available examples:
| # | Example | Description | Guide |
|---|---|---|---|
| 1 | simple_cube_rendering | Rotating wireframe cube -- core rendering concepts | Tutorial |
| 2 | game_controller_input | Gamepad input handling | Tutorial |
| 3 | spaceship_control | Game loop, command pattern, ImGui overlay, camera follow | Tutorial |
| 4 | spaceship_shooting | Twin-stick shooter with bullet pooling and aiming | Tutorial |
| 5 | enemy_spawn | Timed spawning with object pooling and random placement | Tutorial |
| 6 | collision_detection | Grid-based spatial partitioning and collision events | Tutorial |
| 7 | render_text_demo | FreeType-based text rendering with orthographic projection | Tutorial |
| 8 | scoring_demo | Full scoring, health, timer, state management, and UI pipeline | Tutorial |
| 9 | runtime_test | Interactive stress test -- object count vs. FPS measurement | Tutorial |
- API Documentation -- Overview of the helios framework and module structure
- Examples -- Tutorials and code samples for all 9 example applications
- Testing -- Running tests, debugging failures, test patterns
- Coding Style Guide -- C++ coding conventions and module structure
- Doxygen Style Guide -- Documentation standards
- Contributing Guide -- How to contribute, commit conventions
- Issue Submission Guide -- Guidelines for bug reports, feature requests, and refactoring proposals
- Changelog -- Chronological list of notable changes
Architectural documentation for the major subsystems:
| Topic | Description |
|---|---|
| ECS Architecture | Entity-Component-System overview (EntityHandle, EntityManager, SparseSet, View, System) |
| Component System | Composition-based entity design |
| Component Lifecycle | Lifecycle hooks: onAcquire, onRelease, enable/disable, cloning |
| Component Registry | Modular component registration and bootstrap |
| Game Loop Architecture | Phases, passes, commit points, and event propagation |
| Command System | Compile-time typed command buffering and handler routing |
| Event System | Double-buffered event buses with phase/pass propagation |
| Resource Registry | Type-indexed O(1) service locator |
| State Management | GameState / MatchState hierarchical state machines |
| Spawn System | Spawn scheduling, profiles, and builder DSL |
| Object Pooling | Prefab-based entity recycling |
| Sparse Set | O(1) component storage data structure |
| Text Rendering | FreeType glyph rendering pipeline |
| Scene Graph | Hierarchical scene organization with transform inheritance |
| GameObject Builder | Fluent builder pattern for entity construction |
| Conventions | Coordinate systems, matrix storage, units |
external/doxygen/doxygen.exe docs/Doxyfile.inThe generated HTML documentation will be available in docs/api/html/.
Please read our Contributing Guide and Issue Submission Guide for details on:
- Commit conventions (Conventional Commits)
- Code style requirements
- Pull request process
- Testing guidelines
- Submitting bug reports, feature requests, and refactoring proposals
- Follow Conventional Commits:
feat:for new featuresfix:for bug fixesrefactor:for code improvements- Use
!for breaking changes (e.g.,feat!:)
- Write tests for new features
- Update documentation
- Run
clang-formatbefore committing
This project is licensed under the MIT License. See LICENSE file for details.
- Discussions -- Ask questions, share ideas
- Issues -- Report bugs or request features
- Contact: thorsten@suckow-homberg.de
Active Development -- helios is an educational project under active development. The project has progressed through 5 milestones:
| Milestone | Status | Description |
|---|---|---|
| 1 | Complete | Application layer, event system, input, rendering pipeline |
| 2 | Complete | Camera refactor, ImGui tooling, frame pacing, scene graph |
| 3 | Complete | Physics, collision detection, shooting mechanics, ECS components |
| 4 | Complete | Game loop architecture, spawn system, object pooling, modular reorganization |
| 5 | Complete | SparseSet ECS refactor, ResourceRegistry, typed commands, state management, scoring, health, text rendering, UI |
APIs may change as the framework evolves. See CHANGELOG.md for migration guides on breaking changes.
This project is inspired by and builds upon concepts from industry-standard game engines and graphics frameworks. Special thanks to the authors of the referenced literature below.
- [Vri20] de Vries, Joey: Learn OpenGL (2020), Kendall & Wells
- [RTR] Akenine-Möller, Tomas; Haines, Eric; Hoffman, Naty: Real-Time Rendering, 4th ed. (2018), A. K. Peters, Ltd.
- [Gre19] Gregory, Jason: Game Engine Architecture, 3rd ed. (2018), A K Peters/CRC Press
- [She07] Sherrod, Allen: Data Structures and Algorithms for Game Developers (2007), Charles River Media
- [HDMS+14] Hughes, John F. et al.: Computer Graphics - Principles and Practice, 3rd ed. (2014), Addison-Wesley
- [KSS17] Kessenich, John; Sellers, Graham; Shreiner, Dave: The OpenGL Programming Guide, 9th ed. (2017), Addison Wesley
- [Str22] Stroustrup, Bjarne: A Tour of C++, 3rd ed. (2022), Addison-Wesley
- [PJH23] Pharr, Matt; Jakob, Wenzel; Humphreys, Greg: Physically Based Rendering, 4th ed. (2023), MIT Press
- [DP11] Dunn, Fletcher; Parberry, Ian: 3D Math Primer for Graphics and Game Development, 2nd ed. (2011), CRC Press
- [Gla95] Glassner, Andrew S. (ed.): Graphics Gems. AP Professional / Academic Press, Boston, 1995.
- [Len16] Lengyel, Eric: Foundations of Game Engine Development (2016), Terathon Software LCC
- [Eri05] Ericson, Christer: Real-Time Collision Detection (2005), CRC Press
- [HS99] Havran, Vlastimil and Sixta, Filip: Comparison of Hierarchical Grids (1999), https://www.realtimerendering.com/resources/RTNews/html//rtnv12n1.html#art3
- [Rey99] Reynolds, Craig W.: Steering Behaviors for Autonomous Characters (1999), https://www.red3d.com/cwr/papers/1999/gdc99steer.pdf