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
  • Windows
  • Linux
  • Installation (Windows)
  • Installation (Linux)
  • 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.

[!NOTE] For more detailed information, go to: https://luminagameengine.com

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.

[!CAUTION] Lumina is an educational project under active development. APIs may change, and some features are experimental. If you encounter build issues, please reach out on Discord for assistance.

[!NOTE]

AI Usage

AI has been used selectively for tasks such as static analysis, research, build tooling, and scripting assistance.

The engine itself has been hand-crafted over the course of three years as a passion project. AI is treated as a tool where it provides value, nothing more, nothing less.

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

• In-house sparse-set Entity Component System with per-type storage layouts, typed views, and lifecycle signals
• 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

<img width="800" alt="Lumina screenshot" src="https://github.com/user-attachments/assets/086a1e5e-4d8d-4c98-be81-bc77287fba39" />
<img width="800" alt="Lumina screenshot" src="https://github.com/user-attachments/assets/66d739ca-f257-4350-b2f0-2e10d66f5591" />
<img width="800" alt="Lumina screenshot" src="https://github.com/user-attachments/assets/68e86207-20f2-4200-8649-257738b2855f" />
<img width="800" alt="Lumina screenshot" src="https://github.com/user-attachments/assets/a4c7c497-d975-47d2-a695-5342e11e8f44" />
<img width="800" alt="Lumina screenshot" src="https://github.com/user-attachments/assets/5343eff8-545a-47ca-a858-b2aa4f1fef71" />

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

Getting Started

Requirements

Every platform needs a GPU that supports Vulkan mesh shaders (VK_EXT_mesh_shader): NVIDIA Turing (GTX 16-series / RTX 20-series) or newer, AMD RDNA2 (RX 6000) or newer, or Intel Arc. The renderer's geometry pipeline is built on them, so the editor refuses to start on anything older and says so.

Windows

• 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)

[!IMPORTANT] The engine's C# layer (LuminaSharp) targets net10.0. Only Visual Studio 18.0+ (2026) can build that target, VS 2022 (17.x) fails with error NETSDK1209 even if you install the standalone .NET 10 SDK, because VS uses its own bundled MSBuild. Setup.bat validates this for you and stops with a clear message if anything is missing.

Linux

• A 64-bit distribution
• GCC 13 or newer, or Clang against a libstdc++ that new. The tree uses <format>, which is where that floor comes from. Built and tested with GCC 13-15; newer pre-release compilers tend to reject vendored third-party code for reasons that are not bugs in this engine.
• .NET 10 SDK
• X11 development packages, which GLFW links directly
• A Vulkan loader and driver at run time. These are not needed to compile: the Vulkan headers are vendored and volk resolves entry points with dlopen, so a machine with no driver builds a working editor it cannot launch.

On Debian or Ubuntu:

bash # build sudo apt-get install -y g++-13 pkg-config libx11-dev libxrandr-dev \ libxinerama-dev libxcursor-dev libxi-dev libxkbcommon-dev # run sudo apt-get install -y libvulkan1 mesa-vulkan-drivers vulkan-tools # .NET 10 SDK: https://dotnet.microsoft.com/download/dotnet/10.0

Setup.sh checks all of this and tells you what is missing, including whether any installed GPU actually reports VK_EXT_mesh_shader.

[!NOTE] No IDE is required. On Windows, JetBrains Rider and Visual Studio both open the generated solution. On Linux there is no solution: CLion reads the generated compile_commands.json for C++, and Rider opens the engine's C# projects.

Installation (Windows)

1. Clone the repository

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

1. Run setup

bash Setup.bat It downloads one prebuilt dependency bundle (External-Win64.zip, ~192 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.sln.

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-Win64.zip, extract it into the LuminaEngine/ folder, then run GenerateProjectFiles.bat.

1. Open the solution

Open Lumina.sln in Visual Studio.

1. Build and run

2. Set Lumina as the startup project.

3. Pick a configuration: Development Editor (default), Debug Editor for full debugger functionality at the cost of speed, or Development Game for the runtime without the editor.

4. Press F5, or use Build -> Run.

5. Start developing

6. Copy Templates/Blank/ to create a new project, then run its GenerateProject.bat to produce a solution.

Installation (Linux)

Every script below has a .bat counterpart of the same name on Windows, and takes the same arguments.

1. Clone the repository

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

1. Run setup

bash ./Setup.sh

It checks the prerequisites above, downloads one prebuilt dependency bundle (External-Linux64.tar.gz, ~186 MB), verifies it against a SHA-256 hash pinned in this repo, configures git hooks, and offers to add LUMINA_DIR to your shell profile.

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 prompts for unattended/CI runs, pass -Yes (or set LUMINA_SETUP_YES=1); an unattended run never edits your shell profile. If the download fails, fetch External-Linux64.tar.gz by hand and extract it into the LuminaEngine/ folder.

1. Build

bash ./LuminaBuild.sh Build Lumina -TargetType=Editor

The Reflector is a prerequisite of that target and builds itself first, so this is the only command you need. Add -Configuration=Debug for full debugger fidelity at the cost of speed, or -TargetType=Game for the runtime without the editor.

1. Run

bash ./LuminaBuild.sh Run Lumina -TargetType=Editor

Run locates the binary through the same rules the build used, so it always launches the configuration you name rather than whatever was built last. It takes the same -TargetType and -Configuration flags as Build, and anything after a bare -- is forwarded to the editor untouched. The executable itself is at Binaries/Linux64/Lumina-Editor-Development if you would rather launch it directly; it finds the engine relative to itself, so it does not care what directory you run it from.

1. Set up code completion

bash ./GenerateProjectFiles.sh

This writes compile_commands.json at the repository root. No solution is generated on Linux, because nothing here can open one. Point your editor at the repository root and it will pick the database up:

• clangd (and the VS Code clangd extension) finds it with no configuration.
• CLion: open the folder and select the compile database when prompted.

Rider is the tool for the engine's C# projects (LuminaBuildTool, LuminaSharp) rather than for the compile database.

Re-run it after adding or removing modules, plugins or sources. Ordinary source files are discovered at build time, and a build that changes a Build.cs refreshes the database on its own.

1. Start developing

Create a project from the editor, or copy Templates/Blank/ by hand and run its GenerateProject.sh. Every generated project ships both GenerateProject.bat and GenerateProject.sh, so a project created on one platform still works on the other.

Build Configuration

Optional engine features are controlled from a single file, Engine/Build/BuildConfiguration.json. 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.