Linux & macOS guide

Linux x86-64 preview package (setup.sh)

Each GitHub release ships DKB-Setup-0.3.0+a5796d9-linux-x86_64.tar.gz (3.0 MB, SHA-256 a040ae22418fea0b…). Unlike the Windows archive, the Linux package distributes the source tree and an automated setup.sh script that compiles a native binary on your machine:

1. System requirements: Linux x86-64 with kernel 6.7 or later, Clang, Ninja, Python 3.12+, uv, SDL3, and the .NET SDK (for the shader translator). Source builds are verified on both NVIDIA and AMD GPUs.
2. Check host packages: Unpack the tarball and run the dependency checker first:

   tar -xzf DKB-Setup-0.3.0+a5796d9-linux-x86_64.tar.gz
   cd DKB-Setup-*
   ./setup.sh --check

3. Build from your dump: Point setup.sh at your 1.0.0 or 3.2.0 .nup file (or --exefs and --romfs directories) and choose an output directory without shell-special characters (#189):

   ./setup.sh --nup "/path/to/Donkey Kong Bananza.nup" --dest ~/Games/DKB

4. Known Linux installer workaround (Issue #200): If dkb_shaders fails on Python 3.12 venvs with ModuleNotFoundError: No module named 'compression' or No module named 'zstandard', install zstandard into .venv (uv pip install --python .venv/bin/python zstandard) and ensure tools/xlate has executable permissions (chmod +x).
5. RecompLauncher integration (PR #213): Upstream PR #213 adds recomplauncher.json, play.sh and --prepare --source support so Linux and macOS packages can be set up directly inside RecompLauncher.

Linux RADV & Wayland notes

• Under Mesa RADV, feedback loops automatically default to the pass-restart path (added in v0.2.0), and audio requests a 240-frame period by default.
• If you encounter a crash walking through the tunnel from the Lagoon Layer to the Hilltop Layer on Linux, track Issue #126 (spin-lock patches were added in v0.3.0).
• On Wayland 1440p displays with fractional scaling (e.g., 130% in KDE Plasma), menu and dialogue fonts rasterized via nn::fontll::ScalableFontEngine at 48 px can appear soft next to the sharp 3D scene (Issue #214).

macOS ARM64 Apple Silicon preview (setup.command & Metal)

For Apple Silicon Macs running macOS 14.4 or later, download DKB-Setup-0.3.0+a5796d9-macos-arm64.zip (3.3 MB, SHA-256 0ed9dd53cf801b90…):

• Fixing the macOS build in v0.3.0: PR #178 resolved a duplicate instance_ext_present definition in vk_device.c that previously broke macOS compilation, and v0.2.0 hashed SPIR-V once per shader (#119) and skipped unchanged texture re-uploads (#120) for MoltenVK.
• Current boot status: Running setup.command builds the game on Apple Silicon with MoltenVK and boots cleanly to the mode select screen (docs/building.md). Gameplay beyond mode select is not verified yet, and destructible terrain is missing because Metal lacks geometry shaders (requiring an upcoming vertex-stage replacement).
• Native Metal backend preparation (#151, #179): In v0.3.0, PR #179 moved SPIR-V rewrites into spirv_rewrite.c / gfx_spirv.c, moved constant-buffer c0 fill into gfx_c0.c, and routed all host graphics calls through a unified GfxBackend interface to prepare step 1 of the native Metal renderer.