Installation

This page builds the engine itself. Once it is running you will create a game project from inside the editor, covered in Your First Project.

Prerequisites

Lumina builds on Windows (10 1803 or newer, x64). Install these first. Both are free.

• Visual Studio 2026 (18.0 or newer) with the Desktop development with C++ and .NET desktop development workloads. The C# scripting layer targets .NET 10, and only the MSBuild bundled with Visual Studio 18.0+ can build that target. Older Visual Studio fails with NETSDK1209, and installing a standalone SDK does not fix it, because Visual Studio uses its own bundled MSBuild. Download.
• .NET 10 SDK (x64). Compiles the engine’s C# layer (LuminaSharp) and your game scripts. Download.

The Vulkan SDK is optional. It is only needed for the validation layers in Debug builds; the engine bundles its own Vulkan headers and the loader ships with your GPU drivers.

Note

Setup.bat checks all of this before it builds anything and prints exactly what is missing, so a fresh clone fails fast with a clear message instead of a cryptic error deep in the build. Everything else (the compilers, shader tools, and runtime listed under External dependencies) is fetched for you.

Build the editor

1. Clone the repository

   git clone https://github.com/MrDrElliot/LuminaEngine
   cd LuminaEngine

2. Run setup

   Run this from the repository root.

   Setup.bat

   This is a one-shot setup for a fresh clone. It verifies your prerequisites, bootstraps premake5.exe into Tools/, downloads and extracts the prebuilt dependency bundle (see External dependencies), persists the LUMINA_DIR environment variable, configures the git hooks, and generates Lumina.sln.

3. Open the solution

   Open Lumina.sln in Visual Studio 2026.

4. Set the startup project

   In the Solution Explorer, right-click Lumina and choose Set as Startup Project.

5. Choose a configuration and platform

   Pick a configuration.

   • Development, for day-to-day work. Fast, with Tracy and logging enabled.
   • Debug, for full debugger support. Significantly slower to compile and run.
   • Shipping, for packaging. Strips profiling, verbose logging, and the editor.

   Then pick a platform. Editor (the default) includes all editor tooling, and Game is a runtime-only build with no editor.

   Start with Development | Editor.

6. Build and run

   Press F5. Visual Studio builds every module and launches the editor.

   On first launch the editor has no project loaded, so it opens its project browser. Continue to Your First Project.

External dependencies

The first run of Setup.bat downloads one prebuilt bundle, External.zip (~671 MB), from this repository’s GitHub Releases (the external-deps tag) and extracts it into External/. It is a release asset, not a committed file, so it stays out of git history.

Caution

Setup reaches out to the internet to fetch this bundle. Before downloading anything it prints exactly what it will fetch and waits for a [Y/n] confirmation, so nothing leaves or enters your machine without your say-so. After the download it is integrity-checked against a SHA-256 hash recorded in the repository; a corrupted, tampered, or swapped file is rejected, deleted, and setup aborts. Answer n at the prompt to cancel and download nothing.

The bundle is entirely open source. Its full sources, versions, and licenses are in DEPENDENCIES.md.

Library	Size	Used for
.NET 10 runtime + hosting headers	78 MB	the CoreCLR host for C# scripting
LLVM / Clang 19 (libclang)	337 MB	parsing C++ headers for reflection code generation
Slang	155 MB	compiling .slang shaders to SPIR-V
RenderDoc	24 MB	in-app GPU frame capture
Tracy	77 MB	the CPU/GPU profiler

To verify the download yourself, compare its hash against the one in BuildScripts/Actions/Setup.lua.

powershell -NoProfile -Command "(Get-FileHash External.zip -Algorithm SHA256).Hash"

To run setup without the prompt (for CI), pass Setup.bat --yes. If you would rather not download the bundle at all, fetch each library from its upstream and lay it out under External/ yourself; DEPENDENCIES.md lists the exact paths.

Tip

If the automatic download fails (a firewall, proxy, or antivirus blocking it), download External.zip from the external-deps release manually, extract it so you have an External/ folder in the repository root, then run GenerateProjectFiles.bat.

After pulling

After pulling or merging, regenerate the solution so new and removed source files are picked up.

GenerateProjectFiles.bat

If you still see unexpected errors, delete Binaries/ and Intermediates/, then run GenerateProjectFiles.bat again.

Build features

Optional engine features (the Tracy profiler, Vulkan validation, NVIDIA Aftermath, verbose logging) are configured in BuildScripts/BuildConfig.lua and baked in when you regenerate the solution. You can override any of them for a single regeneration from the command line, like this.

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

Troubleshooting

Symptom	Fix
NETSDK1209, or “Visual Studio is too old for net10.0”	You are on Visual Studio 2022 or older. Install Visual Studio 2026 (18.0+). A standalone .NET SDK will not fix this, because Visual Studio uses its own bundled MSBuild.
”.NET 10 SDK not installed”	Install the .NET 10 SDK (x64), then run dotnet --list-sdks and confirm a 10.x entry appears.
dotnet works in a terminal but Visual Studio still cannot build net10.0	Visual Studio builds with its own MSBuild, not the one on PATH. The fix is the Visual Studio 2026 install above, not the standalone SDK.
External.zip SHA-256 mismatch, setup aborts	The download was corrupted or intercepted. Delete External.zip and re-run Setup.bat, or grab it manually from the releases page.
Dependency download fails or hangs	A firewall, proxy, or antivirus is blocking it. Download External.zip manually and extract it into the repo root (see above).
“wrong engine” errors, or it links a different clone	A stale LUMINA_DIR. Re-run Setup.bat from the correct clone, then restart Visual Studio so it picks up the new value.
Missing v143 toolset	Visual Studio Installer, Individual Components, MSVC v143 Build Tools.
”Cannot find .generated.h”	Build again. Visual Studio sometimes needs a second pass to pick up generated files.
”Application control policy blocked this file”	Disable Windows 11 Smart App Control.

Still stuck? Open an issue or ask on Discord.