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.

Lumina builds on Windows (10 1803 or newer, x64) and Linux (x64). Pick your platform in the tabs below; the choice follows you down the page.

Prerequisites

Windows

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.

Linux

• GCC 13 or newer, or Clang against a libstdc++ that new. The floor is <format>. The tree is 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, so pin a stable one if a build fails inside External/ or ThirdParty/.
• .NET 10 SDK. Compiles the engine’s C# layer (LuminaSharp) and your game scripts. Download.
• X11 development packages. GLFW links these directly, so without them the build gets a long way and then fails at link rather than at configure time.
• The Vulkan loader and a driver, at run time. These are not needed to compile: the Vulkan headers are vendored and entry points are resolved with dlopen, so a machine with no driver at all still builds a working editor it cannot launch.

On Debian or Ubuntu:

# 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

Note

A Wayland session works. GLFW runs through XWayland, which is why the X11 packages are required rather than the Wayland ones.

GPU requirements

These apply on both platforms. You need a GPU and driver supporting Vulkan 1.4 and mesh shaders (VK_EXT_mesh_shader). Both are hard requirements. The renderer draws all geometry through mesh shaders, with no vertex and index path to fall back to, so a device that cannot run them is rejected at startup with an explicit message rather than failing later.

In practice that means:

Vendor	Minimum
NVIDIA	Turing (GTX 16 series, RTX 20 series) or newer
AMD	RDNA2 (RX 6000) or newer
Intel	Arc

If you see the rejection message, update your drivers first. Mesh shader support arrived in drivers well after the hardware did. The message names every GPU it considered and why each was refused, so compare that list against vulkaninfo --summary: a card missing from it entirely is a driver the Vulkan loader cannot see, not a card below the floor.

The Vulkan SDK is optional on both platforms. 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 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

Windows

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, builds LuminaBuildTool, 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

   Each solution configuration pairs a build configuration with a target type, for example Development Editor, Development Game, or Shipping Editor. The only platform is x64.

   The build configuration half decides the compile:

   • 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 and verbose logging.

   The target type half decides what gets built. Editor 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.

Linux

1. Clone the repository

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

2. Run setup

   Run this from the repository root.

   ./Setup.sh

   This is a one-shot setup for a fresh clone. It verifies your prerequisites (including the Vulkan runtime and your GPU’s mesh shader support), builds LuminaBuildTool, downloads and extracts the prebuilt dependency bundle (see External dependencies), configures the git hooks, and offers to add LUMINA_DIR to your shell profile.

   Linux has no user environment store to persist a variable to, which is why that last step is a prompt rather than something setup does silently. It is declined by default under -Yes and in any non-interactive run.

3. Build

   ./LuminaBuild.sh Build Lumina -TargetType=Editor

   The reflection generator is a prerequisite of that target and builds itself first, so this is the only command you need.

   Two flags decide what you get. -Configuration picks the compile:

   • Development (the default), 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 and verbose logging.

   -TargetType decides what gets built: Editor includes all editor tooling, and Game is a runtime-only build with no editor.

4. Run

   ./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 is at Binaries/Linux64/Lumina-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.

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

5. Set up code completion

   ./GenerateProjectFiles.sh

   This writes a compile_commands.json at the repository root, describing how every source in the workspace is compiled. No solution is generated on Linux, because nothing there can open one.

   Point your editor at the repository root and it picks the database up: clangd and the VS Code clangd extension find it with no configuration, and Rider or CLion offer it when you open the folder.

Rider plugin

Optional, and only useful if you work on the engine’s C++ in Rider. Install Lumina Engine from the JetBrains Marketplace, or from inside Rider under Settings, Plugins, Marketplace, searching for Lumina Engine.

It adds a Lumina menu under Tools, plus a toolbar group, wrapping LuminaBuildTool: Build, Rebuild, Run, Clean, Generate Project Files, and Regenerate Reflection. Compiler errors in the console are clickable, and the same commands are available as a run configuration.

It also highlights REFLECT, PROPERTY, FUNCTION, and the other reflection macros, and checks their specifiers against the Reflector’s own table, so a misspelled specifier is underlined in the editor with the same message the build prints as LRT1009. Completion inside a macro offers only the specifiers that macro accepts, hovering one explains what it does, and the plugin’s tool window lists them all.

Requires Rider 2026.1 or 2026.2. The engine root is detected from the open solution, so there is nothing to configure.

External dependencies

The first run of setup downloads one prebuilt bundle for your platform 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.

Host	Asset	Download
Windows	External-Win64.zip	~192 MB
Linux	External-Linux64.tar.gz	~186 MB

Both unpack to roughly 671 MB. The Linux bundle is a tarball rather than a zip because its payload depends on symlinks and executable bits, and zip preserves neither: Slang and libclang ship versioned filenames with the plain name symlinked onto them, and slangc, the Tracy tools and the .NET host all need to be executable.

The two bundles are built to coexist in one External/ tree, so a machine that builds for both platforms installs both and neither overwrites the other.

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 Engine/Tools/LuminaBuildTool/Modes/SetupMode.cs.

Windows

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

Linux

sha256sum External-Linux64.tar.gz

To run setup without the prompt (for CI), pass --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 your platform’s asset from the external-deps release manually and extract it so you have an External/ folder in the repository root.

After pulling

Source files are discovered at build time, so a plain pull just needs a rebuild. Regenerate project files when modules or plugins were added or removed, or to refresh what your editor sees.

Windows

GenerateProjectFiles.bat

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

Linux

./GenerateProjectFiles.sh

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

Build features

Optional engine features (the Tracy profiler, Vulkan validation, NVIDIA Aftermath, verbose logging) are configured in Engine/Build/BuildConfiguration.json, which is read on every build. Each is auto, on, or off; auto lets the engine decide per configuration. You can override any of them for a single build from the command line, like this.

Windows

LuminaBuild.bat Build Lumina -Tracy=off -Validation=on -VerboseLogging=off

Linux

./LuminaBuild.sh Build Lumina -Tracy=off -Validation=on -VerboseLogging=off

Troubleshooting

Both platforms

Symptom	Fix
”No GPU meeting the renderer’s requirements was found”	The message lists every GPU it rejected and why. If every one says no VK_EXT_mesh_shader, the hardware is below the GPU floor. If a GPU you expected is missing from the list entirely, the Vulkan loader is not seeing its driver; compare against vulkaninfo --summary.
”.NET 10 SDK not installed”	Install the .NET 10 SDK, then run dotnet --list-sdks and confirm a 10.x entry appears.
SHA-256 mismatch, setup aborts	The download was corrupted or intercepted. Delete the archive and re-run setup, or grab it manually from the releases page.
Dependency download fails or hangs	A firewall, proxy, or antivirus is blocking it. Download the archive 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 from the correct clone, then restart your IDE so it picks up the new value.

Windows

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.
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.
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.

Linux

Symptom	Fix
error: the .NET SDK is required, but you installed it	dotnet-install.sh puts it in $HOME/.dotnet and persists nothing. The engine’s scripts look there anyway, but your own shell will not until you add it to PATH.
A build failure inside External/ or ThirdParty/	Usually a compiler newer than the tree has been built with. Pin a stable one: sudo apt-get install -y g++-15 && export CXX=g++-15 CC=gcc-15.
Link failure on stdc++_libbacktrace or stdc++exp	The archive behind std::stacktrace was renamed in GCC 14, and the toolchain probes for whichever one your compiler ships. If it fails anyway, the compiler is probably not the one you think it is; check CXX.
The build uses fewer cores than the machine has	Deliberate, and the reason is logged. Parallelism is capped to fit available memory, because overcommitting it gets the desktop session killed rather than the build. Override with -MaxParallel=<n>.
A hybrid-graphics laptop starting on the wrong GPU	The discrete GPU is preferred whenever it enumerates. If it does not appear in vulkaninfo --summary, the proprietary driver is not loaded, and no engine setting works around that.
LUMINA_DIR unset in new shells	Setup only offers to write it to your profile, and never does so unattended. Add export LUMINA_DIR="/path/to/LuminaEngine" to your shell profile yourself.

Still stuck? Open an issue or ask on Discord.