Repository navigation
Development Setup
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 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 --installinstalls command-line tools when they are absent. -
Install Homebrew using its official instructions.
-
Install Rosetta for the legacy Mono build toolchain:
softwareupdate --install-rosetta --agree-to-license
-
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 --versionThe 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.gitDo not add a duplicate if upstream is already configured. Continue to Building and Testing, Contributing, or Engine Updates.
ZkMacOS source · Download the DMG · Report a bug · Get help
Unofficial, experimental Zero-K client. These guides describe the current source; older releases may differ.
- Getting Started
- Playing Zero-K
- Development
- Contributing
- Environment Setup
- Build and Release
- Internals and Validation
- Licensing and Credits
- Source · Downloads