XMage: a self-hosted Magic rules engine with 32,000 cards and an AI opponent

What XMage solves, and for whom

Playing Magic online usually means trusting someone else's server with your collection, your rules disputes, and your connection. XMage takes the other route: it is a rules-enforcement engine you can run yourself. The README describes it as "a full rules-enforcement engine for playing Magic against other players or computer AI, online or on your own server," with support for over 32,000 unique cards and more than 91,000 reprints across official sets plus custom sets such as Star Wars.

The audience is specific. First, players who want AI opponents without a network connection: the README states you can host your own server and play against the AI and friends, "including fully offline, with no internet connection required." Second, playgroups that want a private server with their own house rules. Third, developers, because the repository ships Mage.Tests, Mage.Verify and a documented test mode for reproducing game situations. If you only want a quick match on your phone, this is not the project for you, and the README never claims otherwise.

Server-side enforcement and the module layout

The architectural claim that matters most is in the feature list: "Cheat-proof by design: all rules and hidden information are enforced server-side. Clients never see or act on data they're not authorized to." That single sentence explains the whole split. The client renders and sends intents; the server decides what is legal and what a player is allowed to know. Anything that depends on hidden information, such as a library search or a face-down card, stays on the server side of that boundary.

The repository layout reflects that split. Mage.Server, Mage.Server.Console and Mage.Server.Plugins hold the server side; Mage.Client is the GUI; Mage.Common is shared code; Mage.Sets contains the card implementations; Mage.Tests and Mage.Verify are the test and card-verification modules. A top-level pom.xml and a Makefile tie the modules together, so the build is one Maven reactor rather than a set of independent projects.

Multiplayer is handled in the same process. The README lists two-player duels and multiplayer games including Commander with up to 10 players, plus drafts, tournaments and single games with sideboarding, and tournaments with elimination or Swiss handling for up to 16 players. Ratings use Glicko.

Installing XMage and starting a first game

The README does not give a package-manager install. It says: "Download files and follow install instructions on http://xmage.today/" and notes that you need Java version 8 or later to run the launcher. It also recommends unpacking to a path such as D:\games\xmage and explicitly warns against Program Files or the Downloads folder, which is a Windows-oriented instruction about write permissions and file paths.

If you want to build from source instead, the Makefile in the repository root defines the targets. Note that the build target skips tests:

mvn install package -DskipTests

The test target runs the full suite with game-log printing disabled, and the card verification target is scoped to a single Maven module:

mvn test -B -Dxmage.dataCollectors.printGameLogs=false

mvn -B -pl Mage.Verify \
  -Dxmage.dataCollectors.printGameLogs=false \
  -Dtest=VerifyCardDataTest \
  -Dxmage.tests.verifyCheckSetCodes="$(VERIFY_CHECK_SET_CODES)" \
  test

The packaging target builds the client and server zips and copies them into a deploy directory, which the Makefile lets you override:

TARGET_DIR=my_custom_directory make deploy

For a first real game, the README is blunt about the AI path: "If you want to play with AI opponents then must run 'server' app via the launcher and connect to it via localhost." So the sequence is: start the launcher, start the server, then connect the client to localhost. Nothing in the README describes a single-click mode that starts both for you.

Memory tuning is the documented performance lever

The README does not promise a frame rate or a match duration, and it does not describe a profiler. It describes exactly one tuning knob, and it is the JVM heap. The instructions are to open the launcher, go to Settings, then the Java tab, then the Client java options text field, and add or change the flag to -Xmx3000m or another value based on free memory. The README recommends 2000m for a 1080p desktop and 3000m for a 4K desktop, and adds a hard ceiling: "It's useless to give 5+ GB memory."

That last sentence is the interesting one. It is an admission that the client's memory use plateaus, so throwing RAM at the problem stops helping. If you play many AI games, the README recommends setting the same value in the Server java options field. The stated purpose of the flag is to increase performance or fix micro-freezes, not to fix crashes, so treat it as a tuning step for stutter rather than a general remedy.

Where XMage breaks down

The README's own FAQ list is the most honest part of the project. It links to known problems on every platform: freezes on startup with a white, blue or black screen; image downloads that stop partway; a client that fails to run with a "could not open ...jvm.cfg" error; missing text or tiny buttons in the launcher; and on Windows, ugly cards and GUI drawing artifacts plus pixelated images, icons and text.

The macOS entries are the sharpest limitation. One FAQ entry covers a launcher that will not open, and another covers running on M1 and M2 machines. The README lists cross-platform support for Windows, Linux and macOS, but the troubleshooting list shows that Apple silicon has been a live problem rather than a solved one. Linux has its own entries for non-standard hardware such as a Raspberry Pi and for GUI drawing artifacts.

There is also a scope limit that is easy to miss. The README describes a launcher and a public server at xmage.today, and its own server-status page is marked "temporarily out of service." Nothing in the README describes a mobile client, so if your group plays on phones, XMage is the wrong tool and you should look at a client that ships one.

XMage against Forge and Cockatrice

The closest comparison in the open-source Magic space is Forge, which also implements rules enforcement and AI opponents in Java. The practical difference is not the feature list but the packaging: XMage ships a launcher with a client and server split, and its README is written around downloading that launcher from xmage.today and running the server app for AI games, while Forge is distributed and run through its own launcher and Android build. If your constraint is running AI games on a phone, Forge has a documented Android path and XMage does not, at least not in this README.

Cockatrice is the other common alternative, and the difference there is philosophical rather than technical. Cockatrice is a tabletop client: players move cards and resolve effects themselves, and the software does not adjudicate. XMage enforces the rules server-side, which is exactly why its FAQ is full of graphics and JVM issues rather than rules arguments. Choose Cockatrice when your group wants to shortcut or house-rule interactions freely; choose XMage when you want the engine to tell you that a play is illegal.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-12, the same date as the xmage_1.4.61V1 release. Before that, xmage_1.4.60V3 landed on 2026-07-11 and xmage_1.4.60V2 on 2026-06-28. That cadence tells you what upgrading costs: releases arrive often, and each one ships new card implementations, so a private server that lags behind will not recognize newly printed cards for its players.

The licence is MIT, which is permissive and places few obligations on anyone redistributing the code. Two practical notes, not legal advice: the README credits torch icons to Freepik via Flaticon, and card images and set data come from elsewhere, so the MIT grant on the code does not automatically cover every asset you might redistribute. If you fork and ship a server, check the asset provenance separately.

The real upgrade cost is on the developer side. Mage.Sets holds card implementations, and the repository provides a verification module and a Makefile target that scopes verification to specific set codes, which is the project's own answer to keeping a large card pool consistent. Contributing a card means writing Java and running that verification, not editing data files.

Editorial conclusion

Adopt XMage if you want full server-side rules enforcement, offline AI games, or a private server for a fixed playgroup, and if you are comfortable running a Java launcher and editing Java options for memory. Do not adopt it if you need a mobile client, a signed desktop installer, or a hosted service that someone else operates, because the README points to a launcher download and a wiki rather than an app store or a managed deployment. Before committing, verify two things: that the launcher runs on your platform (the FAQ list already names macOS M1/M2 and Raspberry Pi cases), and that your machine has enough free memory for the recommended -Xmx2000m or -Xmx3000m client flag, since the README calls 5+ GB useless.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes