Building the project

Building on Android

Android build requires Android SDK and NDK installed, see Get started with the NDK. Assembling APK files also requires Gradle. Path to Gradle can be supplied by GRADLE_HOME environment variable if not detected automatically. The build can be configured using a similar command as above:

mkdir build
cmake -B build -D CMAKE_BUILD_TYPE=Debug \
    -D NCINE_BUILD_ANDROID=ON \
    -D NCINE_UNIVERSAL_APK=ON \
    -D NCINE_NDK_ARCHITECTURES="arm64-v8a;armeabi-v7a"

See Platform-specific parameters for Android for more details. Then following commands can be used to build the project and assemble the APK file:

make -j $(nproc) -C build
cd build
gradle assembleDebug

Alternatively, replace assembleDebug with assembleRelease to create release APK file.

Building on Windows

On Windows, Visual Studio can be used. Using already included .sln is not recommended, because it requires manual configuration and doesn't support all features and parameters. Instead the project can be opened as CMake directory directly in Visual Studio, or it can be configured using a similar command as above:

mkdir build
cmake -B build -D CMAKE_BUILD_TYPE=Debug -A x64 ^
    -D CMAKE_SYSTEM_PROCESSOR=x64 ^
    -D NCINE_CREATE_CONTENT_SYMLINK=ON

See Platform-specific parameters for Windows for more details. To build it for 32-bit operating system, use Win32 instead of x64. To change version of VS toolset, use -D CMAKE_GENERATOR_TOOLSET=… parameter. By default CMake creates a new Visual Studio .sln solution and project files in "build" directory that can be opened easily afterwards. Building with Clang-CL compiler is also possible specifying -T ClangCL parameter.

Building for Xbox (Universal Windows Platform)

The same commands can be used as for Windows, but two additional parameters must be specified to change the target:

cmake -B build -D CMAKE_BUILD_TYPE=Debug -A x64 ^
    -D CMAKE_SYSTEM_PROCESSOR=x64 ^
    -D CMAKE_SYSTEM_NAME=WindowsStore ^
    -D CMAKE_SYSTEM_VERSION="10.0"

Additionaly, a code-signing certificate is required to create an installable .msixbundle package. See Platform-specific parameters for Universal Windows Platform for more details.

Building for consoles

Six consoles are supported, each cross-compiled with its own SDK and its own CMake toolchain file. The build is configured the same way as above — "Build<Platform>.sh" scripts in the repository root wrap it — but every one of them also needs its toolchain installed, its own packaging step and, on four of them, a game content tree prepared in advance with AssetPacker. All of that is documented in depth on a page of its own:

See Building for consoles for the toolchain installation, deployment to the device or an emulator, how to read the game's log on each of them, and what each console does and does not support. The game can also be built as a libretro core for RetroArch, see Libretro core.

Build configuration parameters

By default it tries to find the first available backend for the currently installed libraries. GLFW is usually preferred over SDL2, because it's more lightweight. On the other hand, SDL2 usually has better gamepad support and better support in general. The following parameters can be used to customize the build:

• CMAKE_BUILD_TYPE — Build configuration
  • Possible values: Debug, Release
• CMAKE_INSTALL_PREFIX (default "/usr/local") — Install prefix on Unix systems
• NCINE_CONTENT_DIR (default "./Content") — Path to the "Content" game data directory
  • Some build targets include "Content" directory directly inside the executable package (e.g., Android)
• NCINE_CREATE_CONTENT_SYMLINK (default OFF) — Create symbolic link to the "Content" game data directory in target directory
  • Ignored on Android, Emscripten, Nintendo Switch and UWP platforms
• NCINE_DOWNLOAD_DEPENDENCIES (default ON) — Download all missing dependencies automatically
• NCINE_BUILD_ASSET_PACKER (default ON) — Build the offline AssetPacker tool
  • It runs on the build machine, so it's skipped for every cross-compiled target
• NCINE_BUILD_LIBRETRO (default OFF) — Build as a libretro core instead of an executable, see Libretro core
  • Only Software and OpenGL are valid values of NCINE_PREFERRED_RHI in this configuration
• NCINE_PREFERRED_BACKEND (default "GLFW", "SDL2" on PS Vita and Nintendo Switch) — Preferred core backend
  • Possible values: GLFW, SDL2, SDL3
  • Ignored on Android, UWP and the consoles with a bespoke window backend
• NCINE_PREFERRED_RHI (default "OpenGL") — Preferred rendering backend (RHI)
  • Possible values:
    • OpenGL — Uses the OpenGL family (which profile is chosen with NCINE_RHI_GL_PROFILE)
    • D3D11 — Uses Direct3D 11 (Windows only)
    • Vulkan — Uses Vulkan
    • Software — Uses custom software renderer (no hardware acceleration, lower visual quality and performance)
  • Pinned to the console's only rendering backend on Sega Dreamcast (PVR), Nintendo Wii and Nintendo GameCube (GX) and PlayStation Portable (GU); any other value is a configure error there, see Building for consoles
• NCINE_RHI_GL_PROFILE — Which profile of the OpenGL family the OpenGL backend targets
  • Possible values:
    • Core — OpenGL 3.3 core profile (GLSL 330, uniform buffer objects, gl_VertexID)
    • ES3 — OpenGL|ES 3.0, and WebGL 2.0 on Emscripten (ESSL 300 es)
    • ES2 — OpenGL|ES 2.0 (ESSL 100, no uniform buffer objects, no gl_VertexID, no buffer mapping)
  • Defaults to ES3 on Android, Emscripten, Nintendo Switch, ARM Linux and ANGLE builds, and to Core elsewhere; pinned to ES2 on PS Vita (vitaGL is an OpenGL|ES 2.0 implementation) and to ES3 for the libretro core
  • Every profile builds on every platform that can provide the matching client library, so an ES2 build on Android or on the desktop is a normal configuration — it is how the low-end paths are tested without the target hardware
• NCINE_RHI_USE_FB16 (default OFF) — Use 16-bit (RGB565) color surfaces instead of RGBA8
  • Trades color depth (and destination alpha, which reads as opaque) for memory and bandwidth. Being a performance option, each backend applies it as deep as it pays off there: the OpenGL backend uses it for every color surface it can — a 5/6/5 default framebuffer and RGB565 scene, blur and rescale render targets — while the Software backend uses it for the screen buffer only, since its rasterizer works on RGBA8 internally either way and packed render targets would only add a conversion per span
  • Only offered for the Software and OpenGL backends; the consoles present through a format their hardware fixes, and 5/6/5 swap chains are not reliably available on D3D11/Vulkan
• NCINE_VERSION_FROM_GIT (default ON) — Set current game version from Git repository automatically
• NCINE_WITH_THREADS (default ON except on Emscripten and PlayStation Portable) — Allow to use multiple threads for better performance
  • Multiplayer requires threads, so it's compiled out where they are unavailable
• NCINE_WITH_ANGLE (default OFF except on UWP) — Enable Google ANGLE library support
• NCINE_WITH_GLEW (default ON) — Use GLEW library, only offered for NCINE_RHI_GL_PROFILE=Core
• NCINE_WITH_BACKWARD (default ON except on Android, Emscripten and UWP) — Enable better exception handling
• NCINE_WITH_WEBP deprecated — Enable .webp image file support, requires libwebp library
• NCINE_WITH_AUDIO (default ON) — Enable audio support, requires OpenAL library
• NCINE_WITH_VORBIS (default ON) — Enable .ogg audio file support, requires libvorbis library
• NCINE_WITH_OPENMPT (default ON, forced OFF on PlayStation Portable) — Enable module music audio file support, requires libopenmpt library
  • NCINE_COMPILE_OPENMPT (default OFF) — Download and compile libopenmpt library from source automatically
  • See Limits and known issues for why it's disabled on PlayStation Portable
• NCINE_WITH_ANGELSCRIPT (default OFF) — Enable AngelScript scripting support
  • ANGELSCRIPT_VERSION_TAG allows to specify the version to be downloaded if NCINE_DOWNLOAD_DEPENDENCIES is enabled
• NCINE_WITH_LUA deprecated — Enable Lua scripting support
• NCINE_WITH_IMGUI (default OFF) — Enable integration with Dear ImGui library
  • IMGUI_VERSION_TAG allows to specify the version to be downloaded