Setting up your Development Environment

Content

• About Java
• About build
• About IDE
  • IntelliJ
  • Netbeans
  • Visual Studio Code
  • Eclipse
• Code style and formatting
• About other tools and technologies
  • Maven
  • Git
  • Perl
  • H2 database
  • JBoss
• Where to go from here

Java

• For client/server developing: Oracle's JAVA 8 JDK;
• For launcher app developing: Oracle's JAVA 7 JDK;
• Alternative developing JDK: any OpenJDK distr with java 11+ like temurin/adoptium

Newer versions of the JDK can be used for developing or private servers, but it’s incompatible with public servers running java 8.

(Download Java 8 JDK here)

(Download Java 7 JDK here)

OpenJDK and command line support

If you need to execute commands in terminal like maven builds, tests running, etc - then must set up JAVA_HOME environment variable to your JDK folder. Possible error:

• No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK

Build

There are some auto-generated sources, so you must run full maven build to generate it before using IDE's build and run features. See below for commands example.

XMage uses Apache Maven to compile and build. Maven in 5 minutes Be sure to follow their installation guide.
Maven is a standardized way of building Java projects. It would be a good idea to get basic knowledge regarding Maven before starting developing.

Full build (use it on first build from scratch):

• from root folder: mvn clean install -DskipTests

Fast build (use it as pre-step in you IDE's run/debug):

• from root folder: mvn install -DskipTests

Release build (use it to generate distributing files for your custom server):

• from mage/Utils/ folder: perl build-and-package
• This will yield a file called mage-bundle.zip with folders for client and server as well as the according scripts to start them. This will not include the launcher.

Possible build errors and warnings

All

• java: package mage.game.result.ResultProtos does not exist
  • Fix: run full maven build to create auto-generated source by command mvn install -DskipTests
• Can't find packge to download com.googlecode.jspf
  • Fix: choose JDK 1.8 for the project by File -> Project structure SDK (IntelliJ)

IntelliJ

• internal java compiler error
  • Fix: increase compiler's heap size to 1500 or 3000 MB by Settings -> Build -> Compiler -> Build process heap size;
  • 
• Cannot resolve symbol 'result'
  • Fix: install Protocol Buffers plugin to your IntelliJ IDE and reload maven's pom-file from the root folder;

IDE

We recommend using IntelliJ for coding (latest version) and NetBeans 8.2 for GUI developing. You can still use another IDE tools or editors too, but be careful with code formation and generation. Most xmage's developers uses IntelliJ IDEA. If you use Windows then you must enable git to auto convert line endings to unix style by command:

• git config --global core.autocrlf true (more info);

Instructions for:

• IntelliJ IDEA (preferred IDE for code editing);
• Netbeans (preferred IDE for GUI design);
• Visual Studio Code (VSC);
• Eclipse.

IntelliJ IDEA

Retrieving, building and running XMage with Jetbrain IntelliJ

1. Download and install IntelliJ IDEA from the official website. The Community Edition is free and contains everything that's needed to start. (The Community Edition download is below the "Ultimate" edition on the download page.)
2. Run IntelliJ and navigate to File -> New -> New from Version Control -> Git, use https://github.com/magefree/mage.git/ as the Git Repository URL then click "Clone". Make sure that the path to where the project is cloned has no directories with spaces in their name. Alternatively, you can use the git command line to checkout the repository first and use File -> New -> New from Existing Source and find the pom.xml file at the root of the repository. On the next screens you can leave everything as-is and click "Next" a few times to create the project. Again, make sure not to put the repo anywhere where its filepath contains spaces.
3. File -> Project Structure -> Project SDK and change it to java 1.8;
4. If you see the following message: "Frameworks detected Protobuf Facet and Web frameworks", click "Configure" and OK to close the popup. Afterwards you should see another message regarding the output directory for Protobuf Facet. Click "Configure" once again. When asked to provide a path, select the root of the project.
5. You will then need to create a couple of Run Configurations (see below). Alternatively, everything else could be done from the Terminal window found in IntelliJ (should have a 'Terminal') link at the bottom of the screen.
6. If you got OutOfMemory Exception while building or testing project from IDE then open Settings -> Build -> Compiler and increase Build process heap size to 1500 MB. (If this still doesnt work, try increasing to 3000, or 3200)
7. If you got heap size error while running maven task then go to project settings maven -> runner and add that default VM option: "-Xmx1000m".
8. Note: The built-in GUI designer in IntelliJ IDEA will not edit the .form files used by XMage. Each form has a .java file associated with it that can be edited but developers wishing to use a GUI designer will need to use Netbeans'. There is a non-free plugin that provides a designer for Netbeans forms in IntelliJ but it has not been confirmed to work.

IntelliJ Run Configurations

1. Navigate to Run -> Edit Configurations... and create the following by first clicking the green + in the top right corner and entering create the run configurations describe below as needed.
2. If you got error about missing import mage.game.result.ResultProtos then that's OK -- you must build full project first by maven command clean install -DskipTests. After that auto-generated classes will be added to project and you can IDE build utils without maven.
3. Open Project structure menu and select Project SDK to 1.8 (don't use 9.0 -- you will got compilation errors);

Maven building and testing

1. Pick 'Maven' from the popup. Name it 'Clean Install'. Change the working directory to the root of the application (This should be the full path, not shortened to ~/IdeaProjects/...). Set the Command line to clean install -DskipTests and click "Apply".
2. You can create another Maven configuration that does not skip tests by redoing the previous step and removing -DskipTests.
3. You can create fast built and install configuration for project parts, example, client: create Maven configuration with command line clean install -DskipTests and working directory set to ..mage_path\Mage.Client.

Running server and client

1. Pick 'Application' from the popup and name it 'Run Server'. Set mage.server.Main as the Main class. Click the '...' button next to Working directory and choose the root of the Mage.Server directory. Then, select mage-server from the Use classpath of module dropdown. "Before launch" window may contain "Build" task by default, in such case delete it (by pressing red minus icon).
2. Repeat the previous step by replacing instances of 'server' with 'client'. The Main class should also be mage.client.MageFrame and Mage.Client as root directory.
3. You may want to configure server in the test mode. To do so, repeat step 1 and set -testMode=true as the Program arguments. More about testing.
4. You can add before launch task for build and install new version of client or server before running: open Run Client configuration, press add button in before launch task's list, select Run Maven Goal and in dialogue window choose working directory as ..mage_path\Mage.Client and command line as install -DskipTests. It will built and install all changed files before every run and work much faster when Clean Install.
5. out of memory exceptions errors and extensive memory consumption can be catch on build and run. It can be useful to set some VM Options in the project configuration screen. This speeds up the application start and assigns the available memory for the JVM:

• for server: -Xss16m -Xms512m -Xmx512m -XX:PermSize=64m -XX:MaxPermSize=256m -Xverify:none
• for client: -Xverify:none -client -Xss2m -Xms512m -Xmx512m -XX:+PerfBypassFileSystemCheck

JUnit tests

1. To create a run configuration that runs all tests, choose Maven as the configuration type, the application root as the working directory and use test as the command line.
2. Configurations for specific tests can also be created the same way by adding -Dtest=<ClassName> to the command line. You can use wildcard and regular expressions to match class names or modules. More info on the Maven Surefire Plugin page.
3. Another way of creating configurations for specific tests is to create it the same way as above but setting the working directory as the one you want to test.

Using configurations

All the configurations created above should be available in the dropdown menu at the top right of the IntelliJ window. Each run configuration should also create a new tab in the "Run" window at the bottom. Any console output would be visible there.

To run the program, first build it ("Clean Install" Run option), then run server and lastly run client ("Run Server", "Run Client" Run options).

Running JUnit tests directly from IntelliJ

To enable running JUnit tests from IntelliJ without involving Maven, some compiler changes are needed due to the overall size of the project. In Preferences -> Build, Execution, Deployment -> Compiler change the setting Build process heap size to 3200. In Preferences -> Build, Execution, Deployment -> Compiler -> Java Compiler change the setting Use Compiler to Eclipse. Now open the module Mage.Tests, navigate to the test folder and use the JUnit framework to execute whatever test or test suite you want.

Check currently opened card file bu JUnit test

It allows to check current card rules with mtgjson data. Example use cases: you are adding a new card to xmage or fixing card rules.

• Open new JUnit run configuration and set:
  • Module: mage-verify
  • VM options: -ea -Dxmage.showCardInfo=$FileNameWithoutExtension$
  • Resource type: Method
  • Class name: mage.verify.VerifyCardDataTest
  • Method name: test_showCardInfo
• Now you can run that configuration at any time for opened card file;
• 

Netbeans

Steps to retrieve, build and run XMage

1. Install NetBeans 8.2. More recent versions can be broken with xmage (e.g. can't open some dialogs for edition).

• Install newest maven version and change IDE settings to use it instead bundled maven version (if you don't change then you will get https 501 error on project build):
  • Tools -> Options -> Java -> Maven -> Maven Home
• Also best you add/install the plugin Change Line Endings on Save to avoid problems with line endings, that cause changes of all lines of a file if only some lines are changed.
• It's a good idea to raise the java memory netbeans may use by editing the netbeans.conf file in the netbeans "etc" subdirectory. There is a line starting with "netbeans_default_options=". You can set the java memory used by adding/changing the following parameters (raise the values if you have more memory available).
• -J-Xms756m -J-Xmx756m

2. Change NetBeans code format settings for more compatibility with XMage's code style (IntelliJ IDEA style is default):

• editor -> formating -> java -> comments -> javadoc -> enabled align parameter and enabled align return;
• editor -> formating -> java -> alignment -> multiline alignment -> enabled method parameters.

3. Start NetBeans and clone the code repository from there: Team -> Git -> Clone.

• this is the URL for the repository: https://github.com/magefree/mage.git/
• select the master branch
• set the repository path to one that does NOT contain spaces (i.e. use c:\MyRepo instead of c:\My Repo). Maven has issues with spaces in your java installation and sometimes repository path.

4. Now you can use File -> Open Project and point to the location where you downloaded XMage to open the project. Open the "Mage Root" project and activate the checkbox "Open Required Projects". Now all the XMage projects should be opened and shown in the "Projects" view.
5. Build the complete project (with dependencies) by selecting the "Mage Root" project and choosing "Build with Dependencies" from the context menu. (At least on Windows and Linux systems it's necessary to deactivate the "Compile On Save" option in the project Properties -> Build -> Compile panel for the "Mage Client", "Mage Server" and "Mage Tests" project to successfully build the project). Don't worry if the test project brings up some failures. That often happens if we've created some test cases for existing bugs and the bugs aren't fixed yet. If all builds before the Test project you're already fine to run the server and the client.

• If you use the Java 64-bit version you can get a "BUILD FAILURE" by compiling the "Mage Sets" project. Then the Maven child process that compiles the project needs more memory to compile this project. You can raise the used memory for this task in the project properties. Open the Project properties of "Mage Sets" and select the "Actions". Select the action "Build project" and add the String "Env.MAVEN_OPTS=-Xms2048m -Xmx2048m" to the "Set Properties" field. You can also assign more memory to speed it up more. Try to build the project again. (thanks to Set MAVEN_OPTS within Netbeans). If you are running IntelliJ, increase the "Build process heap size" setting under Build, Execution, Deployment -> Compiler.

6. Run "Mage Server" project by selecting the project and selecting "Run" from the context menu (Main Class to select: "mage.server.Main"). Maybe you need to set some options for the virtual machine in the Run section of the project properties to avoid out of memory exceptions.
   e.g. -Xss16m -Xms512m -Xmx512m -XX:PermSize=64m -XX:MaxPermSize=256m -Xverify:none
   Since Java 8 the MaxPermSize is no longer needed because the memory handling in Java 8 was changed.
7. Run "Mage Client" project by selecting the project and selecting "Run" from the context menu (Main Class to select: "mage.client.MageFrame"). Connect to the local XMage server you started and check if all works as intended. It can be useful to set some VM Options in the Run tab of the project properties.
   -Xverify:none -client -Xss2m -Xms512m -Xmx512m -XX:+PerfBypassFileSystemCheck
   This speeds up the application start and assigns the available memory for the JVM.
8. That's it. Now you can improve XMage and send us your code additions.

Notes

Even though Netbeans has native support for both Maven and Git, it’s still useful to have them installed external to the IDE too.

If you catch a runtime errors like "Uncompilable source code - Erroneous tree type" while running app from another IDE then you must open NetBeans and disable Compile on save:

• Project -> Properties -> Build -> Compiling -> Compile on save
• 

Visual Studio Code (VSC)

Steps to retrieve, build and run XMage

1. Install VSC
   • (If your VSC version doesnt work with the project and freezes, install VSC Insiders);
2. Clone xmage project to any directory;
3. Open that folder in VSC;
4. Install extensions by Files -> Preferences -> Extensions:
   • Language Support for Java(TM) by Red Hat;
   • Debugger for Java;
   • Java Extension Pack;
   • Maven for Java;
   • Java Test Runner;
5. Restart IDE and re-open project
   • It might ask to import maven configuration and start to scan project files. Wait until finished;
6. Open terminal window and run mvn install -DskipTests -- maven must build all project files;
   • If you experience errors, a possible solution is to run the command in a terminal outside VS Code
7. If you see error messages then open Problems tab and filter it by Error;
   • Some errors are false positives and will not cause errors when building the project
8. Open Run -> Add Configuration -- select java and VSC generates config for you;
   • This file might already exist, and will just open it
9. Open that config, delete all lines and add that:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "Debug (Launch) - Current File",
            "request": "launch",
            "mainClass": "${file}"
        },
        {
            "type": "java",
            "name": "Run Client",
            "request": "launch",
            "mainClass": "mage.client.MageFrame",
            "projectName": "mage-client",
            "cwd": "${workspaceFolder}/Mage.Client"
        },
        {
            "type": "java",
            "name": "Run Server",
            "request": "launch",
            "mainClass": "mage.server.Main",
            "projectName": "mage-server",
            "cwd": "${workspaceFolder}/Mage.Server"
        }
    ]
}

• Now you can run client and server apps

10. If you want to run tests from IDE (Java Test Runner Extension), change the test config to run it from ${workspaceFolder}/Mage.Tests folder:
    • Go to File -> Preferences -> Setttings;
    • Search java.test, select Java Test Runner and press edit in settings.json;
    • Add that config (help with all commands):

{
    "...other settings..." : "",

    "java.test.config": {
        "name": "xmage test run",
        "workingDirectory": "${workspaceFolder}/Mage.Tests"
    }
}

• Now you can run tests from IDE:

11. It can be useful to run single unit test (more about testing) like VerifyCardDataTest.test_showCardInfo to check fix in card rules without real game run:

• Choose "Main menu -> Terminal -> Add task" or create tasks.json in .vscode folder;
• Add new task configuration:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "run showCardInfo",
            "type": "shell",
            "command": "mvn",
            "args": ["install", "test", "'-Dxmage.showCardInfo=${fileBasenameNoExtension}'", "'-Dsurefire.failIfNoSpecifiedTests=false'", "'-Dxmage.build.tests.treeViewRunnerShowAllLogs=true'", "'-Dtest=VerifyCardDataTest#test_showCardInfo'"],
            "options": {
                "cwd": "${workspaceFolder}/Mage.Verify"
            },
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared",
                "showReuseMessage": false,
                "clear": true
            },
            "problemMatcher": []
        }
    ]
}

• Now you can run it by "Main menu -> Terminal -> Run task" and check output logs for current opened file

Eclipse

Steps to retrieve, build and run XMage

1. Install Eclipse;
2. Clone xmage project to any directory: git clone https://github.com/magefree/mage.git;
3. Change Eclipse default file encoding to UTF-8: Window -> Preferences -> General -> Workspace : Text file encoding;
4. Open command line window in xmage root folder and enter mvn install -DskipTests -- maven must build all project files;
5. Open Eclipse and start to import new project from dir;
6. After import completed wait some time for background project scanning finished;
7. If you got build error messages like missing JFX then select that project in packages list and go to Project -> Properties -> Java Build Path -> Libraries tab -> find JRE system library. Press edit and change to alternative JRE, select jre1.8.0_201 (or current xmage's java version) and press finish;
8. Open Project -> Build to test all builds fine;
9. Open Run -> Run Configurations and add new java application:

• To run server:
  • Name: Run Server;
  • Project: mage-server;
  • Main class: mage.server.Main
  • Program arguments: -testMode=true
• To run client:
  • Name: Run Client;
  • Project: mage-client;
  • Main class: mage.client.MageFrame

10. Open extra menu from run button in toolbar and select Organize Favourites. Check on client and server configs;
11. Now you can run client and server apps.

Code style and formatting

Main code format style and import organization is IntelliJ IDEA (default settings). Use it by <CTRL+O>, <CTRL+L> in IntelliJ IDE. If you use NetBeans then need to change some code format settings for more compatibility (see Netbeans section). If you use Windows then you must enable git to auto convert line endings to unix style by command:

• git config --global core.autocrlf true (more info);

Other tools and technologies

Maven

To run a Maven task, just open up a console/terminal, go to XMage's root folder (you'll see a pom.xml file there), type mvn, and add any of the following parameters:
clean <- cleans the project
install <- builds the project
-DskipTests <- skips the tests

For example, you can use the following command:
mvn clean install -DskipTests

Git

This is the versioning tool we're using. You can get it from here. If you aren't familiar with it, here is a quick rundown.

When cloning the repository you'll have a branch located on your PC. The commits you make will be on your local branch. If you want to send your changes to the server you have the following commands:
fetch <- it gets the latest changes, usually from the master branch (they aren't applied yet)
merge <branch> <- it merges the changes you've got using fetch within your local branch
pull <- it does a fetch immediately followed by a merge
rebase <branch> <- it applies your commits on top of the specified branch
push <- it pushes your commits to the server (master branch)

To avoid merge commits, you can use rebase. You use this when someone pushed changes to the server and you didn't have them locally when you commited. The GUI doesn't offer this feature, so you'll have to use the Git bash. Here are the commands you'll have to execute one after the other:
git fetch origin
git rebase origin/master

The first command fetches the latest changes from origin. The second command rewinds your changes, applies the fetched changes, and then recommits your changes on top of the new branch head. If there were merges that couldn't be automatically resolved, you'll still need to do them; however, this is rarely necessary while working on XMage.

Perl

In the Utils directory in the projects root directory you'll find a couple of Perl scripts. You'll need to have Perl installed to be able to use them. If you are Windows install Strawberry Perl. (Same as Perl just different name) Also install the Text-Template package for it (using the package manager or copy it manually to ..\Perl\lib\Text\ and rename it to Template.pm). Please make sure to read the readme.txt. This file isn't large but contains very useful information. (template.pm)

You have to be inside the /Util/ folder when running Perl scripts.

$ cd mage/Utils/
$ perl <perl-script>

Don't forget to create a file named author.txt in the "/mage/Utils/" directory in which you only write your username. This will be used for @author in the generated file.

Generate Skeleton for New Card. The script you should definitely be using whenever creating new cards is gen-card.pl. This generates the basic Java file for a card. It's a lot easier to create new cards with this script. Open a CMD/DOS window and run perl gen-card.pl. You'll be prompted to enter a card name. If you do, the script creates the basic Java file for this card (it also creates all the needed files, if the card exists in different sets). After that you only have to implement the abilities of the card.

Build Bundle. To build the project into a bundle including client and server with start-scripts, you can execute the according Perl script: ./Utils/build-and-package-console.pl. This will yield a file called mage-bundle.zip with folders for client and server as well as the according scripts to start them. This will not include the launcher.

H2 Database

XMage uses an H2 database in the client, server, and test project; it includes card and extension/set data to provide a faster access to the needed card data. XMage generates and read all db files by code, but there are many third party tools to view or edit H2 files. As example: http://www.h2database.com/html/quickstart.html If don't you see a newly implemented card after building the needed projects, it's probably because the card is not added to the client H2 db. The deck editor works with the H2 client db to show the included cards. After adding new cards in the IDE, you have to check the Force Database Update check box in the client's connect dialog window to get the client db updated. Alternatively, you can delete all files in the db folder of the client before connecting – also leading to a db copy of the server db. As the XMage server program is started, all missing card entries for the card db are generated from the card classes. Nothing happens for already existing card records. That means if you change the implementation of a card that influences the db record, you'll have to delete the db files of the server before starting the XMage server, so the changes to the card class will be reflected to the db file of the server.

JBoss

The client server communication of XMage is done by JBoss Remoting 2. Documentation

Where to go from here

A good starting point is to look for some simple cards that aren't implemented yet and try to implement them (always use the Perl script to generate the Java body of the new card). To know what you have to code in the card class, look for similar cards that are already implemented. It's best to use the included perl scripts to find what cards are already implemented and which need implementing on a per set basis. If you finish the coding them, you can do a pull request to commit the cards or fixes to the XMage main repository. We'll take a look at your committed code and merge it – or give you some feedback on what should be changed.

Further reading:

• Index of pages for developers at the Wiki Home
  • Also located in the sidebar to your right
• Read about the used tool on this page (take notice of the gen-card.pl script in the Perl section).
• Read about using Code Templates to help you code cards.