Repository navigation
Contributing
ZkMacOS spans several repositories. Put the change in the repository that owns the behavior, and keep the central pins in sync after the source commits are ready.
Search issues for the problem. For a large feature or architectural change, open an issue to discuss the concrete behavior first. A bug report is useful even if you cannot provide a fix.
Use the existing architecture and coding style. Keep related functionality together, avoid abstractions without a demonstrated need, and leave unrelated refactoring out of the PR. Read any AGENTS.md, contribution instructions and license headers in the component you edit.
| Change | PR target |
|---|---|
| App bootstrap, defaults, build/release scripts, packaging and central tests |
ZkMacOS, main
|
| Engine rendering, input, Retina, platform behavior or native menus |
RecoilEngine fork, macos/2026.07.04
|
| Lobby settings and bundled macOS game widgets |
Chobby fork, macos-port
|
| Launcher and native Steam helper |
Infrastructure fork, macos-port
|
| AI/AngelScript ARM64 support |
CircuitAI fork, codex/macos-arm64
|
| Player/developer guides | This wiki; see the documentation section below |
The engine version branch may change when Zero-K changes its required release. Check the current source lock and Engine Updates, rather than guessing a newer upstream target.
- Follow Environment Setup and Building and Testing.
- Create a feature branch in the relevant checkout. The repositories under
external/are independent Git repositories; the central repository ignores their working files. - Make the smallest complete fix and add/update the checks that establish its behavior.
- For graphics/input changes, run the appropriate native checks and manually test on a supported Mac. Describe the actual hardware, macOS, scene and settings tested. Automated checks do not establish multiplayer synchronization or broad hardware support.
- Update affected wiki instructions when a user option or workflow changes.
- Push to your fork and open a PR against the component/branch above.
Fresh component checkouts may be detached at their pins. For example:
git -C external/recoil switch -c codex/fix-descriptionIf you cannot push to the project’s fork, fork that component into your GitHub account and add your fork as a separate push remote. Do not repoint an upstream project’s release tag or force-push its history to carry a port change.
Explain the problem, the observable behavior after the change, the issue/reproduction it addresses, and how it was checked. Include relevant screenshots or logs for visible behavior, reviewed for private data. State any remaining limitations; distinguish a successful build from a tested game session.
Keep commits focused and preserve attribution/license notices. Disclose substantial AI assistance and what was reviewed/tested. This project’s existing AI disclosure does not make generated changes automatically correct. If proposing a change directly upstream instead of to a ZkMacOS fork, follow that upstream project’s separate contribution and AI policies.
For a change spanning components, link the related PRs. Merge/push the component commits first, then update sources.lock.json in a central PR. CircuitAI’s commit is pinned by the engine submodule. Do not add a new central engine/lobby/AI patch as a substitute for committing the owning fork.
The wiki is a separate Git repository:
git clone https://github.com/smallketchup82/ZkMacOS.wiki.git
cd ZkMacOS.wikiIf you have write access, edit the relevant Markdown page and update _Sidebar.md when adding or renaming a page. Use links such as [Installation](Installation) for other wiki pages and full repository URLs for source files. Keep player instructions separate from implementation/validation notes.
Without wiki write access, open a ZkMacOS issue with the proposed Markdown or corrections. The wiki does not use the central repository’s normal PR workflow. GitHub’s wiki documentation explains its Git-based editing model.
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