Build from source
Build the editor, the player, the dedicated server and the tools from the engine repository on Windows. Install four tools once; the build fetches and pins everything else.
Building from source gives you the same programs as the download, built on your machine, plus the tests and the tools to change the engine.
What you need
Install these once. The versions in the last column are the ones the engine is built and tested with; newer patch releases work too.
| Tool | Minimum | Tested with | Where |
|---|---|---|---|
| Visual Studio 2022 or its Build Tools, with the Desktop development with C++ workload (MSVC v143 x64 tools and a Windows 11 SDK) | 2022 (version 17) | 17.14 | visualstudio.microsoft.com |
| CMake | 3.26 | 4.1.0 | cmake.org |
| Git | any | 2.49 | git-scm.com |
Vulkan SDK (for glslc, the shader compiler, and the Vulkan headers) | 1.3 | 1.4.313.2 | vulkan.lunarg.com |
| Python 3 (tests, documentation and validation tools) | 3.10 | 3.13 | python.org |
You also need a GPU with Vulkan 1.2, descriptor indexing (bindless) and dynamic rendering to run the editor and the player, and about 40 GB of free disk space for a Debug and a Release build. The dedicated server needs no GPU.
Do not install .NET for the engine: the repository pins its own .NET SDK and runtime (Config/DotNetToolchain.json) and keeps them inside the build folder. Every C++ library is pinned to an exact commit in ThirdParty/CMakeLists.txt and downloaded by the first configure.
C:\Dev\KroysEngine. Some packaging and test paths come close to the 260-character Windows path limit.Check your machine
From the repository root, the prerequisite check names anything missing or too old and how to fix it. -Fix also downloads the pinned .NET toolchain.
Every line should read [OK]; [WARN] means a different version than the tested one, which usually works. Open a new terminal after installing a tool, so its PATH and VULKAN_SDK are seen.
PowerShell
git clone <repository-url> C:\Dev\KroysEngine cd C:\Dev\KroysEngine powershell -ExecutionPolicy Bypass -File Tools/CheckPrerequisites.ps1 -Fix
Get the pinned .NET toolchain
-Fix above already did this. Otherwise run the setup script once: it downloads the SDK and runtime versions listed in Config/DotNetToolchain.json, verifies their SHA-512 hashes and unpacks them under build/Tools/DotNet.
PowerShell
powershell -ExecutionPolicy Bypass -File Tools/SetupDotNet.ps1
Configure and build
The checked-in presets configure a Visual Studio build. The first configure downloads the pinned third-party libraries, so it takes several minutes; later builds are incremental.
The build produces the whole product in build/bin/Debug: the launcher KroysEngine.exe, the editor KroysEditor.exe, the player KroysPlayer.exe, the dedicated server KroysDedicatedServer.exe and the command-line tools (kroys-cook, kroys-upgrade, kroys-worldgen, KroysGamePackager). Use the windows-msvc-release build preset for an optimised build in build/bin/Release.
To build only the editor and what it needs:
PowerShell
cmake --preset windows-msvc-debug cmake --build --preset windows-msvc-debug
PowerShell
cmake --build build --config Release --target KroysEditor
Check the build
The tests run with CTest. A full run takes a while; run a subset with -R.
Tools/RunTests.ps1 -Configuration Debug gives a short report with one line per test. Before you change the engine, read Validation.
PowerShell
ctest --preset windows-msvc-debug ctest --test-dir build -C Debug -R "Kroys.Docs" --output-on-failure
Start the editor
KroysEngine.exe opens the launcher, where you create or open a project. To open a project straight in the editor:
The editor finds the documentation, templates, samples and the .NET SDK in the repository. Continue with Your first project.
PowerShell
build\bin\Debug\KroysEngine.exe build\bin\Debug\KroysEditor.exe --project "C:\Games\MyGame\MyGame.kproject"
Build the download
Tools/BuildEngineDistribution.ps1 builds the Release programs and writes the same zip the download is, with its checksum, to Dist. See Releases.
PowerShell
powershell -ExecutionPolicy Bypass -File Tools/BuildEngineDistribution.ps1
When something fails
| Message | Fix |
|---|---|
Could NOT find Vulkan or glslc was not found | Install the Vulkan SDK and open a new terminal, so VULKAN_SDK is set |
Could not create named generator Visual Studio 17 2022 | Install Visual Studio 2022 (version 17) with the C++ workload; a newer Visual Studio alone does not provide this generator |
dotnet SDK executable was not found or a managed build error | Run Tools/SetupDotNet.ps1 |
| Errors while cloning dependencies in the first configure | Check the network connection and that git is on PATH, then configure again |
| A path longer than 260 characters | Clone into a shorter folder, such as C:\Dev\KroysEngine |
KroysEngine 0.1.0 documentation, built from the engine repository by Tools/BuildDocsSite.py.