Contributing
ManaBrew is GPL-3.0-or-later and developed in the open at github.com/witchesofthehill/manabrew. Read the repository’s CONTRIBUTING guide before opening a pull request.
How the repository is organized
Section titled “How the repository is organized”| Area | Path | Stack |
|---|---|---|
| Client UI | src/ | React + TypeScript |
| Desktop shell | src-tauri/ | Tauri (Rust) |
| Rules engine | forge-engine/crates/ | Rust workspace |
| Java reference | forge/ (submodule) | Forge, read-only |
| Parity harness | forge-parity/ | Rust + Java side-by-side |
| This website | website/ | Astro + Starlight |
The parity philosophy
Section titled “The parity philosophy”The Rust engine is a port of Forge, not a reimplementation. Every engine change mirrors the corresponding Java code — same file names, same control flow — and is verified by a parity harness that runs both engines with identical decks, seeds, and choices, then compares the game traces. Most contributions are parity fixes: find a card that diverges, locate the rule the Rust port is missing, and port it.
AI-assisted development
Section titled “AI-assisted development”ManaBrew is developed with substantial AI assistance, openly. The workflow suits it: Java Forge is an external oracle, so a model can propose an engine fix but the parity harness decides whether behavior actually matches. AI is never treated as a rules authority. If you use AI in a contribution, review the generated diff yourself, test it, and make sure every behavioral claim traces back to Forge or a documented convention — see AI_USAGE.md.
Building your own client or engine
Section titled “Building your own client or engine”The wire protocol between frontends and engine backends is specified in PROTOCOL.md — message shapes, game-state snapshots, prompts, and actions. Unlike the GPL-licensed implementation, the spec itself is CC-BY-4.0, so independent clients and engines can implement it without license entanglement.
Where to start
Section titled “Where to start”- Join the Discord and say hi.
- Browse open issues.
- Play a game at manabrew.app and report anything that behaves differently from paper Magic.
Community standards
Section titled “Community standards”All project spaces follow the Code of Conduct. Security vulnerabilities go through private reporting, never public issues.