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
    • Luau Scripting
  • Screenshots
  • Getting Started
    • Requirements
    • Installation
    • Build Configuration
    • Troubleshooting
  • Asset Formats
    • Free Asset Resources
  • Documentation
    • Coding Standards
  • 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.

---

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

Luau Scripting

• Full ECS access from Luau: create systems, query entities, modify components
• Hot-reloadable scripts for iterating on gameplay without recompiling
• Automatic binding generation: C++ components are exposed to Luau via reflection
• Built-in Luau script profiling through Tracy

---

Screenshots

Show more screenshots

2026-01-28.22-17-28.mp4

---

Getting Started

Requirements

• Windows 10 (1803 or newer) or Windows 11, 64-bit
• Visual Studio 2022 with the MSVC v143 toolset (17.8 or newer)

Note

JetBrains Rider is the recommended IDE for Lumina development, but it is not required.

Installation

1. Clone the repository

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

2. Run setup

   Setup.bat

   This downloads and extracts all external dependencies, persists the LUMINA_DIR environment variable, configures git hooks, and generates Lumina.sln. No Python is required; it uses the curl.exe and tar.exe bundled with Windows.

   If the download fails, manually download External.zip, extract it into the LuminaEngine/ folder, then run GenerateProjectFiles.bat.

3. Open the solution

   Open Lumina.sln 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.

Feature	What it controls	"auto" default
Tracy	Tracy CPU/GPU profiler (LUMINA_PROFILE_*)	Debug + Development; off in Shipping
Validation	Vulkan validation + sync layers	Debug only
Aftermath	NVIDIA Nsight Aftermath GPU crash dumps	NVIDIA machines, Debug + Development
VerboseLogging	LOG_TRACE / LOG_DEBUG / LOG_INFO macros	Debug + Development; off in Shipping

"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

Tip

• Missing v143 toolset? Install it via Visual Studio Installer -> Individual Components -> MSVC v143 Build Tools.
• "Cannot find .generated.h" error? Build again; Visual Studio sometimes needs a second pass to pick up generated files.
• C1076 compiler limit reached? Retry the build; this is a known intermittent issue with a font file.
• "Application control policy blocked this file"? Disable Windows 11 Smart App Control.
• Build still failing? Submit an issue or reach out on Discord.

Note

Setup.bat persists LUMINA_DIR automatically via setx. To set it manually:

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

Caution

After pulling or merging, delete Binaries/ and Intermediates/ and run GenerateProjectFiles.bat to regenerate the solution.

---

Asset Formats

Lumina supports the following asset formats:

Category	Formats
Models	GLTF, GLB, FBX, OBJ
Textures	PNG, JPG

Free Asset Resources

• Khronos glTF Sample Assets
• Kenney 3D Assets
• Flightradar24 3D Models

---

Documentation

Getting Started

Coding Standards

Lumina follows a consistent naming convention:

Prefix	Usage	Example
F	Internal engine types (non-reflected)	FRenderer, FTexture
C	Reflected classes	CTransform, CMeshRenderer
S	Reflected structs	SVertex, SMaterial

General rules:

• PascalCase for all identifiers
• Tabs for indentation
• Braces on new lines
• Descriptive variable names

See CONTRIBUTING.md for the complete guidelines.

---

Contributing

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.

Library	Purpose
basis_universal	GPU texture compression with runtime transcoding to BC7/ETC/ASTC
ConcurrentQueue	Lock-free queue supporting multiple producers and consumers
EASTL	EA Standard Template Library optimized for game development
EnTT	Fast entity component system with sparse-set storage and signals
FastGLTF	High-performance glTF 2.0 parser with full specification support
GLFW	Multi-platform window and input library for OpenGL and Vulkan
GoogleTest	C++ testing framework with assertions, fixtures, and test discovery
ImGui	Immediate-mode GUI for rapid tool development
JoltPhysics	Multi-threaded physics engine with continuous collision detection
Luau	Efficient, optionally-typed scripting language derived from Lua
MeshOptimizer	Mesh optimization for vertex cache, overdraw, and buffer compression
Miniaudio	Single-file audio playback and capture library
Nlohmann JSON	Modern JSON library with STL compatibility
NVIDIA Aftermath	GPU crash debugging and post-mortem dump analysis
OpenFBX	Lightweight FBX loader for geometry, skeletons, and animation
RenderDoc	Graphics debugger integration for frame capture and analysis
RPMalloc	Lock-free, thread-caching memory allocator
Slang	Modern shader language and compiler with SPIR-V / HLSL output
SPDLog	Fast C++ logging library with async mode and multiple sinks
stb_image	Single-header image loading library
TinyObjLoader	Lightweight OBJ parser with MTL material support
Tracy	Real-time frame profiler with sampling, GPU zones, and lock contention tracking
vk-bootstrap	Vulkan initialization helper that reduces boilerplate
Volk	Vulkan meta-loader for runtime function loading
Vulkan	Low-level graphics API providing explicit GPU control
VulkanMemoryAllocator	Memory management library for Vulkan with defragmentation
xxHash	Extremely fast non-cryptographic hash algorithm

---

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