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 iOS

The iOS build (iPhone and iPad) is cross-compiled on a Mac with Xcode installed — the Command Line Tools alone carry no iOS SDK. CMake's own iOS support is used (no toolchain file): CMAKE_SYSTEM_NAME=iOS together with the SDK (CMAKE_OSX_SYSROOT, iphoneos or iphonesimulator), the architecture (CMAKE_OSX_ARCHITECTURES, arm64 for devices; the simulator runs the Mac's own architecture) and the minimum iOS version (CMAKE_OSX_DEPLOYMENT_TARGET, 14.0 is the default and the lowest the launch screen in the Info.plist supports). None of the prebuilt dependency archives cover iOS, so SDL2, OpenAL Soft, Ogg/Vorbis and libcurl are downloaded as source and compiled as part of the build (CMake 3.18 or newer), like libopenmpt, lz4 and Zstd already are everywhere; zlib comes from the SDK.

cmake -B build -G Xcode \
    -D CMAKE_SYSTEM_NAME=iOS \
    -D CMAKE_OSX_ARCHITECTURES=arm64 \
    -D CMAKE_OSX_DEPLOYMENT_TARGET=14.0 \
    -D NCINE_IOS_DEVELOPMENT_TEAM=<Apple Developer team ID>

The Xcode generator produces a project that signs the application with the given team (automatic signing) and installs it on a connected device from Xcode itself. Without a team the bundle is left unsigned, which is what the simulator wants. The same configuration works with Ninja (or Makefiles), which is the quickest way to an unsigned bundle for the iOS Simulator of the Mac's own architecture:

cmake -B build -G Ninja \
    -D CMAKE_SYSTEM_NAME=iOS \
    -D CMAKE_OSX_SYSROOT=iphonesimulator \
    -D CMAKE_OSX_ARCHITECTURES=$(uname -m) \
    -D CMAKE_OSX_DEPLOYMENT_TARGET=14.0 \
    -D CMAKE_BUILD_TYPE=Release
cmake --build build

A device bundle built this way has to be signed before a device accepts it: NCINE_IOS_CODESIGN_IDENTITY and NCINE_IOS_PROVISIONING_PROFILE run codesign after the build (or use the Xcode generator). See Platform-specific parameters for iOS for the parameters behind both.

The result is the flat jazz2.app bundle (assembled at build time, there is no install or CPack step): the executable, the Info.plist, the icons scaled from Sources/Icons/1024px.png and the Content directory copied from NCINE_CONTENT_DIR. The original game files go to the application's Documents/Source directory, which the bundle exposes through file sharing (the Files app, or Finder); the converted cache lives in Library/Caches, where the system may reclaim it (it is then rebuilt on the next start), and the trace log Jazz2.log is written next to Source. A simulator build is installed and started with:

xcrun simctl boot <device UDID from `xcrun simctl list devices`>
xcrun simctl install booted build/jazz2.app
xcrun simctl launch --console booted jazz2.resurrection

Metal is the default rendering backend (the same backend and offline MSL as on macOS, see NCINE_PREFERRED_RHI), with the OpenGL|ES 3.0 profile of the OpenGL backend as the alternative — Apple deprecated it in iOS 12 but still ships it, and it is the one the iOS Simulator can run on a Mac without a Metal-capable GPU. SDL2 is the only window backend: it provides the UIKit window, the touch, game-controller and keyboard input, the on-screen keyboard and the application lifecycle (the game suspends whenever it leaves the foreground, as on Android). LAN server discovery uses multicast, which iOS 14 and newer only allow with the com.apple.developer.networking.multicast entitlement granted by Apple; without it, servers are joined by address.

Building for consoles

Ten 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, but every one of them also needs its toolchain installed, its own packaging step and, on most 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.

Building for Amiga systems

The game also runs natively on three Amiga systems, all of them rendering with the same CPU software rasterizer the desktop build can use, because none of them has graphics hardware it could use instead:

The classic toolchain needs a specific branch and a few one-time additions to its prefix, the two PowerPC ones come as container images, and the m68k port picks a performance preset by measuring the machine at startup. All of it is documented on Building for Amiga systems.

Building for PortMaster handhelds

Linux handhelds with a custom firmware supported by PortMaster (e.g. Anbernic RG34XX/RG35XX family, R36S, TrimUI Smart Pro) run the regular Linux build with the SDL2 backend and the OpenGL|ES 3.0 profile. What makes it a separate build is the environment: these firmwares ship old system libraries, so it has to be built against an old glibc (Ubuntu 20.04, glibc 2.31), with libopenmpt compiled in, libstdc++ linked statically and OpenSSL bundled next to the executable, while SDL2 and OpenGL|ES are always taken from the firmware. The .github/workflows/portmaster.yml workflow builds both aarch64 and x86_64 and assembles the port in the layout of the PortMaster-New repository, using the launcher script and metadata from "Sources/PortMaster". The original game files are expected in "ports/jazz2/Source".

Running the dedicated server as a container

The dedicated server is published as a multi-architecture (amd64 and arm64) container image, so a server operator doesn't have to build anything:

docker pull ghcr.io/deathkiller/jazz2-server:latest

Running it takes no more than pointing the server at the game files and its configuration:

docker run -d -i --name jazz2-server --restart unless-stopped \
    -p 7438:7438/udp -p 7438:7438/tcp \
    -v "$PWD/Source:/app/Source:ro" \
    -v "$PWD/Config:/app/Config" \
    -v jazz2-cache:/app/Cache \
    ghcr.io/deathkiller/jazz2-server:latest

The original Jazz Jackrabbit 2 files are never part of the image, they have to be provided as a volume, just like for a local installation — "./Source/" above. The server reads its configuration from the first command-line argument (defaults to "/app/Config/Jazz2.Server.config" in the image), converts the game files into "/app/Cache" on the first start, and takes console commands from standard input, so "docker attach" opens the server console. The "./Config/" directory has to be writable by uid 1000, the unprivileged user the server runs as. Both SIGINT and SIGTERM shut the server down cleanly, so "docker stop" disconnects the peers and delists the server from the online server list before the process exits. See Multiplayer for how to configure and administer the server, and ServerConfiguration for all configuration properties.

The image is described by the Dockerfile in the repository root, which builds the server with DEDICATED_SERVER — no window or audio backend is compiled, so no graphics or audio libraries are needed and the image contains only libcurl, OpenSSL and zlib besides the game. To build it from sources instead of pulling it:

docker build -t jazz2-server .

The docker-compose.yml next to the Dockerfile describes the whole setup declaratively and covers both cases: "docker compose up -d" runs the published image, "--build" builds it from the sources in the repository. It also parameterizes the instance name, the port and the two host directories, so several servers can run on a single host — each as its own Compose project with its own configuration directory, as described at the top of the file. Two properties deserve attention in that case:

• ServerPort and WsPort have to match the published port. The port is not only announced to the server list, it is also the last part of the identifier the server is listed under (the rest comes from the preferences file, so two instances that share a configuration directory are told apart by their ports alone).
• ServerAddressOverride has to be set for a public server. The container sees only its own address on the Docker network, which is of no use to a player on the internet.

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
  • Defaults to OFF if DEDICATED_SERVER, NCINE_BUILD_FLATPAK or NCINE_BUILD_LIBRETRO is enabled — the tool is not part of any of those artifacts
• NCINE_BUILD_SHADER_COMPILER (default ON) — Build the offline ShaderCompiler tool
  • It runs on the build machine, so it's skipped for every cross-compiled target
  • Defaults to OFF in the same configurations as NCINE_BUILD_ASSET_PACKER
  • The generated shader headers are committed to the repository, so turning it off never affects the game
• 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, Nintendo Switch and iOS, where it is also the only choice) — 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", "GXM" on PS Vita, "Metal" on iOS) — 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 with the MSVC toolchain only)
    • Vulkan — Uses Vulkan, on a device with VK_KHR_maintenance1 or Vulkan 1.1 (for the negative-height viewport every pass is drawn through; every current desktop driver and MoltenVK have one) — on macOS through MoltenVK: the backend enables the portability extensions the loader needs, but the Vulkan SDK's loader and MoltenVK have to be installed or shipped next to the executable
    • Metal — Uses Metal (macOS and iOS; the offline MSL sources are compiled on the device at load time, no Xcode is needed to build for macOS)
    • GXM — Uses sceGxm directly (PlayStation Vita only), see PlayStation Vita
    • RSX — Uses libgcm directly (PlayStation 3 only), see PlayStation 3
    • PVR — Fixed-function PowerVR backend on top of KallistiOS (Sega Dreamcast only), see Sega Dreamcast
    • GX — Fixed-function GX backend for Flipper/Hollywood (Nintendo Wii and Nintendo GameCube only), see Nintendo Wii and Nintendo GameCube
    • GU — Fixed-function GU backend driving the Allegrex GE through sceGu (PlayStation Portable only), see PlayStation Portable
    • GS — Fixed-function Graphics Synthesizer backend writing GIF packets directly (PlayStation 2 only), see PlayStation 2
    • RDP — Fixed-function Reality Display Processor backend driving libdragon's rdpq queue (Nintendo 64 only), see Nintendo 64
    • LegacyGL — Fixed-function OpenGL 1.x backend, whose targets are MorphOS' TinyGL and AmigaOS 4.1's MiniGL, see Hardware rendering through TinyGL and Hardware rendering through MiniGL (selectable on the desktop too, where it is how that path is developed and looked at)
    • Software — Uses custom software renderer (no hardware acceleration, lower visual quality and performance)
  • Only GXM, OpenGL (through vitaGL, which pins the profile to ES2) and Software are available on PS Vita
  • Only LegacyGL (the default) and Software are available on MorphOS and AmigaOS 4.1; AmigaOS 3.x is pinned to Software, see Building the project for Amiga systems
  • Pinned to the console's only rendering backend on Nintendo 64 (RDP), Sega Dreamcast (PVR), Nintendo Wii and Nintendo GameCube (GX), PlayStation Portable (GU), PlayStation 2 (GS) and PlayStation 3 (RSX), see Building the project for consoles
  • RSX is the only one of those pins that is a shader backend — the RSX is a programmable part, so the PlayStation 3 keeps the post-processing chain the fixed-function consoles lose
• 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, iOS, 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 (also the only profile on iOS, whose OpenGL|ES has no EGL for the ES2 vertex-array-object entry points)
  • 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_N64_SIZE_OPTIMIZATION (default ON, offered on Nintendo 64 only) — Compile the parts of the port that are not in the frame loop for size (-Os) instead of speed
  • The console's 8 MB of RDRAM is shared by the code, the framebuffers and the whole heap, so the binary's size is the game's memory: the cold sources — level loading, the content conversion, the menus — give back RDRAM the levels then have. The frame loop itself keeps -O2; building everything for size cost about a fifth of the frame rate when it was measured, see Limits and known issues
• NCINE_WITH_THREADS (default ON except on Emscripten, Nintendo 64, PlayStation 2, PlayStation 3, the classic Amiga and MorphOS) — Allow to use multiple threads for better performance
  • Multiplayer requires threads, so it's compiled out where they are unavailable
  • Each of those targets is off for its own reason, none of them a configuration choice — see Limits and known issues, Limits and known issues, Limits and known issues, Limits and known issues and What differs from a desktop build. The PlayStation Portable is not among them: it runs on pspdev's pthread-embedded, with a smaller stack than elsewhere (see Limits and known issues)
• 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, iOS, Emscripten and UWP) — Enable better exception handling
• NCINE_WITH_LZ4 (default ON on the Nintendo 64, Sega Dreamcast, PlayStation 2 and Nintendo GameCube, OFF elsewhere) — Enable LZ4 support, built from source with the target's own toolchain (NCINE_DOWNLOAD_DEPENDENCIES, see cmake/FindLz4.cmake). These consoles cannot convert the game data on the device, so they only ever get a tree prepared by the asset packer, and that tree carries their sprite sheets and tilesets in LZ4 — see LZ4 sprite sheets and tilesets. A build without it refuses such a file instead of misreading it
• NCINE_WITH_WEBP deprecated — Enable .webp image file support, requires libwebp library
• NCINE_WITH_AUDIO (default ON) — Enable audio support, requires OpenAL library on desktop; the consoles use their own backends, see Audio backends
• NCINE_WITH_VORBIS (default ON) — Enable .ogg audio file support, requires libvorbis library
• NCINE_WITH_OPENMPT (default ON, forced OFF on Nintendo 64, PlayStation Portable, PlayStation 2, the classic Amiga, and wherever NCINE_WITH_XMP is on — which by default also covers the Dreamcast, the Wii, the GameCube, the 3DS and the PS Vita) — Enable module music audio file support, requires libopenmpt library
  • NCINE_COMPILE_OPENMPT (default OFF, forced ON on PlayStation Portable and PlayStation 3) — Download and compile libopenmpt library from source automatically. Neither SDK packages the library, and the runtime fallback the desktop platforms use needs a dynamic loader no console has
  • See Limits and known issues, Limits and known issues and Limits and known issues for why it's disabled on those — the reasons are unrelated to each other. The PlayStation 3 builds it from source in the library's single-threaded mode (see PlayStation 3)
• NCINE_WITH_XMP (default ON on the Dreamcast, Nintendo Wii, Nintendo GameCube, Nintendo 3DS, PlayStation Portable, PlayStation 2, PS Vita and the classic Amiga, OFF elsewhere) — Play module music with libxmp instead of libopenmpt. Available on every platform: it is how a machine that cannot afford libopenmpt gets music at all, and a legitimate choice anywhere else that would rather spend the CPU elsewhere
  • The two are alternatives — turning this on turns NCINE_WITH_OPENMPT off
  • The library is downloaded and built from source by the configure step (cmake/Findlibxmp.cmake, pinned by hash), so nothing has to be installed
  • It is far lighter — an integer mixer rather than a floating-point one — but it does not read MO3, so four of the game's tracks are silent under it, and its playback is less exact than libopenmpt's on the edge cases
• 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