Skip to content

Development Setup

smallketchup82 edited this page Oct 29, 2026 · 1 revision

Use an Apple Silicon Mac running macOS 26 or newer. The renderer requires Metal 4. Building also needs Apple’s compiler/SDK tools, Homebrew, Git, Mono MSBuild, the .NET SDK, and the native dependencies listed in the Brewfile.

The resulting app is self-contained. Mono, Rosetta, Homebrew and a separately installed .NET runtime are build-time requirements, not player requirements.

Install the tooling

  1. Install Xcode or Apple’s command-line tools with a macOS 26-or-newer SDK. Open Xcode once if you use it and complete its setup. xcode-select --install installs command-line tools when they are absent.

  2. Install Homebrew using its official instructions.

  3. Install Rosetta for the legacy Mono build toolchain:

    softwareupdate --install-rosetta --agree-to-license
  4. Clone the build repository and install its dependencies:

    git clone https://github.com/smallketchup82/ZkMacOS.git
    cd ZkMacOS
    brew bundle --file=Brewfile --no-upgrade
    export PATH="/Library/Frameworks/Mono.framework/Commands:$PATH"

Keep that Mono commands directory on your development shell’s PATH if msbuild is otherwise unavailable. The build script explicitly uses Homebrew’s pkg-config, avoiding Mono’s unrelated copy.

The helper SDK is selected by global.json, currently .NET 10.0.403 with latest-patch roll-forward. Check dotnet --list-sdks if the selected SDK is missing; install the matching .NET 10 SDK rather than editing the project to whatever SDK happens to be installed. The engine uses GCC 16; Metal/Swift integration uses Apple’s toolchain.

Useful checks from the repository root:

xcrun --show-sdk-version
dotnet --version
msbuild -version
brew --prefix gcc
uv --version
gh --version

Fetch the component repositories

The build fetches them automatically. To prepare them without building:

UV_CACHE_DIR="$PWD/build/uv-cache" uv run --no-project --python python3 python scripts/fetch-sources.py
UV_CACHE_DIR="$PWD/build/uv-cache" uv run --no-project --python python3 python scripts/fetch-assets.py
Location Repository / maintained branch Responsibility
This repository ZkMacOS, main Native bootstrap, defaults, tests, build/release tooling and packaging
external/recoil RecoilEngine, macos/2026.07.04 Engine, input, rendering and native application-menu integration
external/chobby Chobby, macos-port Lobby, macOS settings and bundled game widgets
external/infrastructure Zero-K-Infrastructure, macos-port Launcher and ARM64 Steam helper
external/recoil/AI/Skirmish/CircuitAI CircuitAI, codex/macos-arm64 AI and its Apple ARM64/AngelScript support

sources.lock.json pins exact fork commits. CircuitAI is pinned by the engine’s .gitmodules URL and gitlink. assets.lock.json pins external archives and checksums. Engine/lobby/AI changes are committed in the forks, not applied as a central patch stack. Only the Mesa and create-dmg dependency patches remain here.

A fresh checkout may be detached at its pinned commit. Create a branch before editing. Source preparation preserves existing developer changes and warns if a local revision differs; release preflight requires clean checkouts at the pins, including recursive submodules.

For tag merges in a freshly cloned engine fork, add its upstream remote if it does not already exist:

git -C external/recoil remote -v
git -C external/recoil remote add upstream https://github.com/beyond-all-reason/RecoilEngine.git

Do not add a duplicate if upstream is already configured. Continue to Building and Testing, Contributing, or Engine Updates.

Clone this wiki locally