Releases

Config/EngineVersion.json holds the engine version, in semantic versioning: MAJOR.MINOR.PATCH, with an optional -prerelease suffix such as 0.2.0-preview.1. It is the only place the version is written. The build compiles it into the editor title and Help › About, the player's log and usage text, the game packager's usage text and every package's Managed/runtime-manifest.json, crash reports and save games; the download is named after it.

In an installed engine the same file marks the engine folder: the editor, the packager and the script host look for Config/EngineVersion.json (or CMakeLists.txt in a checkout) above their own folder and find the documentation, templates, samples and the .NET SDK relative to it.

Add every change users notice to the Unreleased section of CHANGELOG.md when you make it, under Added, Changed, Fixed or Removed. Write for the people who use the engine: what they can do now, not how it was built.

NewRelease.py sets the version in Config/EngineVersion.json, moves the Unreleased section of CHANGELOG.md into ## [0.2.0] - <date> with a new empty Unreleased section above it, updates the engine version on the What's new page and rebuilds this documentation, and writes Dist/release-notes-0.2.0.md for the download page. It refuses a version that is not newer than the current one (except the first release of the version already in the file, when CHANGELOG.md has no section for it yet, as for 0.1.0) and an empty Unreleased section. --notes-only writes the release notes of the current version again. It never commits, tags, uploads or publishes.

The script builds the Release programs, stages the download in a short scratch folder and writes to Dist:

The zip is deterministic: entries are sorted and carry one fixed time stamp. The report (Artifacts/Distribution/<timestamp>/distribution.json) lists the size per folder, the system libraries the programs import and the time of each step. Dist is ignored by Git.

The programs (launcher, editor, player, game packager, dedicated server, MCP host, kroys-cook, kroys-upgrade, kroys-worldgen) with the Visual C++ runtime next to them; the engine assets with the shaders compiled; the documentation site; the C# scripting API project, the managed engine runtime and the C# plugin SDK, built without symbols or build paths; the native plugin SDK; the plugin samples; the project templates; the pinned .NET SDK and runtime; glslc from the pinned Vulkan SDK in Tools\ShaderCompiler (see below); LICENSE.txt, THIRD-PARTY-NOTICES.txt, CHANGELOG.md and README.txt. Engine source code, tests and test programs never ship.

Before the zip is written, the staged folder is audited; any finding fails the build:

• No source code or build artifacts: no .pdb, .obj, .ilk or .exp, and C, C++, C# and shader sources only in the scripting API project, the templates, the samples and the SDK headers.
• No developer paths: every file, binary or text, is searched for the repository path, its top-level folder, the user profile and the user name, as UTF-8 and UTF-16, in any case and slash direction.
• No missing system libraries: every library a shipped program imports is in the download or part of Windows. The Vulkan loader comes with the graphics driver and is loaded on demand.
• Complete notices: THIRD-PARTY-NOTICES.txt is generated from the license files of everything shipped, as listed in Config/ThirdPartyNotices.json. A third-party dependency the build declares, or a font in the download, without an entry there fails the build.
• The shader compiler with its licenses: Tools\ShaderCompiler\glslc.exe must be the binary pinned in Config/ThirdPartyNotices.json (shaderCompiler: Vulkan SDK version and SHA-256), with the license texts of shaderc, glslang (including the Bison special exception), SPIRV-Tools and SPIRV-Headers next to it and in THIRD-PARTY-NOTICES.txt, and with the C++ runtime files it imports in its own folder.

The editor compiles material and shader graphs to SPIR-V with glslc. The download ships it unmodified from the Vulkan SDK the engine builds with (Config/ThirdPartyNotices.json, shaderCompiler), and an installed engine uses only that file, <engine>\Tools\ShaderCompiler\glslc.exe, never a glslc from the Vulkan SDK or PATH; a source checkout keeps looking in VULKAN_SDK and on PATH. The license texts live in ThirdParty/Licenses, copied byte for byte from the upstream revisions that shaderc's release pins; its README lists the sources and says how to update them with a new Vulkan SDK.

The distribution gate of Tools/RunReleaseGates.ps1 proves the download works on its own:

1. builds the zip and checks it against its checksum,
2. unpacks it into a scratch folder and checks the installation holds exactly the zip's files,
3. creates a project from a template in the unpacked editor, opens it, plays and stops (no SDK, build tool or .NET on PATH, an isolated user profile, no dialogs, network bound to 127.0.0.1),
4. opens a custom material graph in the unpacked editor, adds a node and compiles it with the bundled glslc (no Vulkan SDK),
5. builds a C# plugin sample with the shipped .NET SDK and plugin SDK,
6. packages the project with the unpacked game packager, compiling its scripts,
7. boots the packaged game from its own zip the same way.

The gates run on a development machine with a scrubbed environment. Before a release is published, check it once on a Windows machine that never had development tools installed, for example a fresh virtual machine:

1. Install Windows 10 or 11 (x64) with its updates and the current GPU driver; in a virtual machine, enable 3D acceleration with Vulkan support. Install nothing else.
2. Copy KroysEngine-<version>-win64.zip and its .sha256 file onto it. Compare Get-FileHash <zip> -Algorithm SHA256 with the checksum file.
3. Run Unblock-File on the zip, then unpack it to C:\KroysEngine.
4. Start KroysEngine.exe. Confirm the launcher opens and Help › About in the editor shows the version.
5. Create a project from the Third Person template. Confirm the scripts compile (no errors in the Console) and Play runs the game; stop it.
6. Open a material in the Material Editor, add a node and link it: it compiles without the Vulkan SDK.
7. Open Help, then the manual, and press F1 over a panel: the offline documentation opens.
8. In the Plugin Manager, create a C# plugin from a sample, save it and confirm it builds and loads.
9. File › Build & Export..., Build Gameplay & Export. Copy the package's zip to a second folder, unpack it and start the game there.
10. Repeat steps 4 and 9 from a Windows account without administrator rights.
11. Write the result, the Windows build and the GPU into the release notes; any failure blocks the release.

To check a source build the same way, install only the tools in Build from source on a clean machine, clone the repository and follow that page from Check your machine to Start the editor.