Building from Source
Sources: Chinese build instructions, contributor instructions. Developer index.
This guide is for changing the engine. Script-only games use the prebuilt SDK.
Tools and checkout
Use Git, CMake 3.21 or newer, a C++20 compiler and a Vulkan development environment. CMake builds most third-party libraries from pinned sources; host window/audio development packages are still required.
main contains the latest official release; everyday contributions target dev. Initial configuration downloads the pinned third-party/ repository. external/* is managed separately through submodules. See dependencies.
Windows
Install Visual Studio 2026 with Desktop development with C++, CMake, Ninja and Git for Windows. The current Windows Debug and Release Makefile targets use Ninja and MSVC through cmake/with-msvc.cmd, which finds compiler setup with vswhere. Visual Studio 2022 is also supported; explicitly configured Visual Studio projects must select the matching installed generator.
Install the Vulkan SDK, set VULKAN_SDK to its directory and add its Bin directory to PATH so glslc is available. Open a new terminal after environment changes. Run Makefile targets with make and Git Bash available.
Linux / WSL2
Use GCC with C++20 support, CMake, Git, Ninja, pkg-config and development packages for X11/Wayland, ALSA/PulseAudio, zlib, PNG, bzip2 and Brotli. Install Vulkan headers/loader and a shader compiler (glslc); verify the executable rather than assuming a package name supplies it. The Chinese README lists the Ubuntu packages.
The prepared Linux CI environment uses GCC. Switching compilers changes standard-library requirements; a compiler-only installation may be insufficient.
macOS
Install Xcode Command Line Tools, CMake and the macOS Vulkan SDK with MoltenVK. Load its environment in each build shell:
CMake must find Vulkan on the Apple host. The distributed macOS SDK already bundles the runtime loader and MoltenVK; this setup is for engine development.
Build targets
From the repository root:
The platform/type appears in the build directory, such as build/win32-debug or build/macosx. Choose parallelism for available memory; the first dependency build is much slower than incremental builds.
A manually configured build has three stages:
Multi-configuration generators require --config Debug or --config Release. Prefer the Windows Makefile targets to keep generator/compiler setup consistent.
Incremental builds and profiles
CMake can automatically discover sccache on PATH. Request it explicitly or disable discovery:
A compiler cache shares reusable outputs; each checkout still needs its own CMake/Ninja build directory. Module trimming avoids compiling unused domains. A complete dependency installation can be reused read-only through EVENGINE_THIRD_PARTY_BINARY_DIR; see dependencies.
EVENGINE_MODULE_LINKAGE=SHARED is the Windows/Linux development default; macOS, mobile and WebAssembly keep OBJECT by default. Cross-group symbols need the correct EVENGINE_API_<GROUP> export macro; Linux visibility can hide missing Windows exports until link time. Release/package targets explicitly use OBJECT for the shipped executable. Keep these modes distinct when diagnosing failures.
Mobile builds
Android needs ANDROID_HOME, ANDROID_NDK and JAVA_HOME:
For iOS, use macOS/Xcode. make build/ios-debug builds a device application; make build/ios-sim-debug builds the simulator path. Device installation requires signing. Consult the Chinese Android/iOS instructions for full toolchain/template setup.
Check and run
Run source checks and affected tests before submitting changes. make devlab exercises hot reload/debugging. Missing headers, unavailable SDKs or changed generators need environment/configuration repairs before engine behavior changes.
Assertions use EV_PARAM_CHECK / EV_ASSERT in src/engine/common/Assert.h. Debug enables them; non-Debug builds remove them by default. Explicitly retain them with -DEVENGINE_ENABLE_ASSERTS=ON.