Lumina Game Engine

A modern, high-performance game engine built with Vulkan

Website • Discord • Documentation

Contents

• Lumina Game Engine
  • Contents
  • Overview
  • Features
    • Rendering
    • Architecture
    • Editor
    • Performance
    • C# Scripting
  • Documentation
  • Screenshots
  • Getting Started
    • Requirements
    • Installation
    • Build Configuration
    • Troubleshooting
  • Contributing
    • Workflow
    • Requirements
  • Third-Party Dependencies
  • Acknowledgments
  • License
  • Connect

Overview

Lumina is a modern C++ game engine built from the ground up with Vulkan. It is designed for learning and experimentation with real-world engine architecture, demonstrating professional design patterns including a reflection system, an ECS-based gameplay layer, and modern rendering techniques.

It is well suited for:

• Learning modern game engine architecture
• Experimenting with Vulkan rendering techniques
• Building prototypes on a clean, modular codebase
• Understanding how engines such as Unreal and Godot work internally

Contributions are recognized in several ways, including Steam keys for popular games and public acknowledgment in the Discord community. Lumina improves through the work of motivated contributors who help push the engine forward.

Features

Rendering

• Vulkan-powered renderer with automatic resource tracking and barrier placement
• Forward+ pipeline with clustered lighting for efficient multi-light scenes
• PBR materials authored through a material graph compiled to shader code

Architecture

• Entity Component System (ECS) built on EnTT for high-performance gameplay code
• Reflection system driving automatic serialization and editor integration
• Modular design with clean separation of concerns

Editor

• ImGui-based editor with real-time scene manipulation
• Scene hierarchy for entity management
• Component inspector with UI generated automatically via reflection

Performance

• Multi-threaded task system built with fibers.
• Custom memory allocators built on RPMalloc
• Built-in profiling through Tracy integration

C# Scripting

• C# scripting via LuminaSharp, a CoreCLR host that bundles the .NET 10 runtime
• EntityScript-based gameplay with full ECS access: Registry.View queries, C# entity systems, and component reads and writes
• Reflection-driven C++ to C# bindings generated automatically by the Reflector
• Hot-reloadable scripts for iterating on gameplay without recompiling
• High-level gameplay APIs through the World facade: Physics, Navigation, Input, Messages, and GameplayTags

Documentation

Getting Started

Screenshots

Show more screenshots

https://github.com/user-attachments/assets/3d797479-fc47-4b8f-baf4-87315709d0c2

Getting Started

Requirements

• Windows 10 (1803 or newer) or Windows 11, 64-bit
• Visual Studio 2026 (18.0 or newer) with the MSVC v143 toolset and the ".NET desktop development" workload
• .NET 10 SDK (x64)

Installation

1. Clone the repository

   git clone https://github.com/mrdrelliot/luminaengine
   cd LuminaEngine
   

2. Run setup

   Setup.bat
   

   It downloads one prebuilt dependency bundle (External.zip, ~671 MB), verifies it against a SHA-256 hash pinned in this repo (once the maintainer records it, see DEPENDENCIES.md), persists the LUMINA_DIR environment variable, configures git hooks, and generates Lumina.slnx.

   The bundle contains the .NET 10 runtime (C# scripting), LLVM/Clang 19 (reflection codegen), the Slang shader compiler, RenderDoc, and Tracy. Each is open source; DEPENDENCIES.md lists every component with its version, purpose, upstream source, and license, and explains how to fetch them yourself instead of using the bundle.

   To skip the prompt for unattended/CI runs, pass --yes (or set LUMINA_SETUP_YES=1). If the download fails, manually download External.zip, extract it into the LuminaEngine/ folder, then run GenerateProjectFiles.bat.

3. Open the solution

   Open Lumina.slnx in Visual Studio.

4. Build and run

   • Set Lumina as the startup project.
   • Choose the Development or Debug configuration. Debug is significantly slower but enables full debugger functionality.
   • Select a platform: Editor (default, includes editor tooling) or Game (runtime only, no editor).
   • Press F5, or use Build -> Run.

5. Start developing

   • Open the Sandbox project to experiment.
   • Or copy Templates/Blank/ to create a new project, then run its GenerateProject.bat to produce a solution.

Build Configuration

Optional engine features are controlled from a single file, BuildScripts/BuildConfig.lua. Each feature is "auto", "on" (force into every configuration) or "off" (strip from every configuration), and the choices are baked in when you regenerate the solution.

"off" is a true strip: e.g. Tracy = "off" drops the Tracy library from the build entirely and turns every profiling macro into a no-op, and VerboseLogging = "off" removes LOG_TRACE/DEBUG/INFO (warnings and errors are always kept). Aftermath auto-enables only when an NVIDIA GPU is detected on the machine generating the solution.

For a one-off build (e.g. a profiling-free package) you can override any feature on the command line without editing the file, the flag wins:

GenerateProjectFiles.bat --tracy=off --validation=on --verbose-logging=off

Regenerating prints the resolved feature set, e.g. [Lumina] Build features: Tracy=auto (Debug, Development) Validation=auto (Debug) Aftermath=auto (Debug, Development) VerboseLogging=auto (Debug, Development) [NVIDIA GPU].

Troubleshooting

setx LUMINA_DIR "C:\path\to\lumina"

Contributing

See CONTRIBUTING.md for the complete guidelines.

Contributions are welcome, whether they are bug fixes, features, or documentation improvements.

Workflow

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Make your changes following the coding standards.
4. Add tests where applicable.
5. Commit with clear messages: git commit -m "Add amazing feature".
6. Push to your branch: git push origin feature/amazing-feature.
7. Open a pull request.

Requirements

• Clean, well-documented code
• Adherence to existing architecture patterns
• Tests where appropriate
• Updated documentation as needed

Third-Party Dependencies

Listed alphabetically.

Acknowledgments

Lumina is inspired by and learns from these open-source engines:

• Spartan Engine - Feature-rich Vulkan engine
• Kohi Game Engine - Educational engine series
• Lumix Game Engine - Fully working indie engine
• ezEngine - Professional open-source engine
• Godot - High-quality open-source engine
• Unreal Engine - Industry-standard engine

Thanks to the game engine development community for sharing knowledge and resources.

License

Lumina is licensed under the Apache 2.0 License.

Copyright 2024 Dr. Elliot

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Connect

• Blog: dr-elliot.com
• Discord: Join the community
• GitHub: mrdrelliot/lumina