Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/magefree/mage/llms.txt

Use this file to discover all available pages before exploring further.

XMage is a Maven multi-module Java project. Getting a local development environment running requires a JDK, Apache Maven, Git, and an IDE — after that, a single command builds every module from the root pom.xml. This page walks through each step from cloning the repository to booting both the server and client on your own machine.

​
Prerequisites

Before cloning, make sure the following tools are available on your PATH:
ToolMinimum versionNotes
JDK8The project’s source and target compatibility is 1.8; newer JDKs (11, 17, 21) compile it without issue — CI uses JDK 17
Apache Maven3.6Manages all module builds and dependencies
Gitany recentUsed to clone and manage branches
IDE—IntelliJ IDEA is recommended; Eclipse also works
The root pom.xml sets <java.version>1.8</java.version> for both <source> and <target> in maven-compiler-plugin, so the compiled bytecode runs on Java 8 runtimes. You can freely compile with a newer JDK (the GitHub Actions CI workflow uses JDK 17 via actions/setup-java). If you see warnings about preview features or deprecated flags, they are harmless.

​
Full Setup Walkthrough

1
Clone the repository
2
Clone the official XMage repository from GitHub:
3
git clone https://github.com/magefree/mage.git
cd mage
4
If you plan to contribute, fork the repository first and clone your fork instead (see Workflow).
5
Build all modules (skip tests for speed)
6
From the repository root, run a full Maven install. The -DskipTests flag skips the JUnit test suite so the initial build finishes quickly:
7
mvn install -DskipTests
8
This compiles and installs every module declared in the root pom.xml — Mage, Mage.Common, Mage.Server, Mage.Sets, Mage.Client, Mage.Plugins, Mage.Server.Plugins, Mage.Server.Console, Mage.Tests, Mage.Verify, and Mage.Reports — into your local Maven repository.
9
The equivalent Makefile target is:
10
make build   # runs: mvn install package -DskipTests
11
Run the test suite
12
To execute the full JUnit integration test suite (located in Mage.Tests/):
13
mvn test
14
Tests are run by maven-surefire-plugin 3.1.2 with a tree-view reporter. Failed tests print a full stack trace; successful tests are silent by default.
15
Import into IntelliJ IDEA
16
  • Open IntelliJ IDEA and choose File → Open.
  • Select the repository root directory (mage/).
  • IntelliJ detects the root pom.xml and automatically imports all 11+ Maven modules. Each module (Mage, Mage.Server, Mage.Client, …) appears as a separate source root in the Maven side panel.
  • Let IntelliJ finish indexing and downloading dependencies before proceeding.
    • 17
    For Eclipse, use File → Import → Existing Maven Projects and select the same root directory.
    18
    Configure a run configuration for the server
    19
    Create a new Application run configuration in IntelliJ:
    20
    FieldValueMain classmage.server.MainModule classpathMage.ServerWorking directory$PROJECT_DIR$/Mage.ServerVM options-Dxmage.config.path=config/config.xml
    21
    The server reads its configuration from Mage.Server/config/config.xml relative to the working directory by default. To point to a different file, change the -Dxmage.config.path property accordingly.
    22
    To enable test mode — which turns off password checks, enables cheat commands, skips deck validation, and prevents idle-disconnect during debugging — add the system property:
    23
    -Dxmage.testMode=true
    24
    Test mode is automatically enabled for developer builds (builds that version.isDeveloperBuild() returns true for). It provides fast-game buttons, cheat commands, simplified registration and login, and disables connection-validation pings so the IDE debugger does not cause client disconnects.
    25
    Configure a run configuration for the client
    26
    Create a second Application run configuration:
    27
    FieldValueMain classmage.client.MageFrameModule classpathMage.ClientWorking directory$PROJECT_DIR$/Mage.Client
    28
    Launch the server run configuration first, wait for it to print MAGE SERVER version: …, then start the client.
    29
    Verify the connection
    30
    In the client’s connect dialog, enter:
    31
  • Server: localhost
  • Port: 17171 (the default from config/config.xml)
  • Username / Password: any value when test mode is active (authentication is bypassed)
    • 32
    A successful connection confirms the environment is working correctly.

    ​
    Useful Build Commands

    # Build everything, skip tests
mvn install -DskipTests

# Run all tests
mvn test

# Build and package distributable zip files for client and server
make package

# Generate JaCoCo HTML coverage report (output: Mage.Reports/target/site/jacoco-aggregate/index.html)
mvn install -Djacoco.skip=false -Dmaven.test.failure.ignore=true

# Generate JaCoCo XML coverage report (for SonarCloud upload)
mvn install -Djacoco.formats=XML -Djacoco.skip=false -Dmaven.test.failure.ignore=true

# Clean all build artifacts
mvn clean
# or
make clean

    ​
    Developer Wiki Resources

    The XMage wiki contains detailed supplementary guides for developers:

    Build docs developers (and LLMs) love

    Get started for freeTalk to us