Repository navigation
Troubleshooting
Start with the known issues and note your installed release. If the problem persists, follow Reporting Bugs so there is enough information to reproduce it.
The app is ad-hoc signed, not Developer ID signed or notarized. Download it from this project’s Releases, verify the checksum, and follow Installation → macOS approval. Only approve a copy you trust. A Sparkle update signature is separate from Apple’s initial approval process.
Check that the Mac is Apple Silicon and runs macOS 26 or newer. Install the app in Applications and eject the DMG before launching. Do not copy just the engine executable out of the bundle; its libraries and resources are required.
Preserve the relevant launcher log and crash report. An Intel Mac or an older macOS version is not supported by these builds.
Start the normal macOS Steam client and sign in first, then fully quit and reopen Zero-K. The port does not require Zero-K’s Steam-store installation. Try ordinary Zero-K account login or offline play to separate a Steam connection problem from a general startup problem.
Start with Low graphics, Retina text and UI, and MetalFX, HDR, GPU sharing and DisplayLink off. Fully restart after changing Retina mode. Compare the same map and camera before and after changing one setting. Full Retina draws more world pixels; optional features do not guarantee a speedup.
For HDR brightness or color problems, test with macOS HDR display output off first. This is separate from the game’s lighting/HDR controls. If enabling a feature logs a fallback warning, include that warning in your report.
This is an unresolved reported issue during some live multiplayer joins. Capture a screenshot and preserve infolog.txt before changing settings or reloading the UI. Note whether it happens on first join, catch-up, reconnect, and replay playback. /luaui reload rebuilds LuaUI, but it has not been confirmed to recover this particular problem. See Known Issues.
Retina mode and notchful fullscreen need a complete app quit/reopen. Starting a new battle is not a full restart. Graphics features added in newer source may be absent from an older release. Check the option’s configuration page before editing files.
Disable three-finger tilt and use Option + two fingers. Check system-reserved gestures and Trackpad configuration. A camera gesture is separate from tap-to-click or secondary click.
Finish the game and quit normally; Sparkle waits for the engine and helper to exit. Do not run Homebrew upgrades at the same time. You can replace the app with the latest DMG while keeping Application Support. Local builds without the public verification key have updating disabled. See Updating and Uninstalling.
A matching version string alone does not make a different engine compatible. Check for a new ZkMacOS release and include the server’s required version in a report. Do not edit the reported version to bypass the check. Port maintainers follow Engine Updates.
Use Building and Testing for compiler, SDK, cache and native-library failures, or Creating a Release for preflight/signing/upload failures.
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