Developer Getting Started

Java

Install the latest JAVA SE JDK 7 or JDK 8 package (link to download)
There are also Java SE Development Kit (JDK) Cobundles that include Java JDK and Netbeans that you can use.

IDE

We recommend using NetBeans or IntelliJ (do not support GUI form design) for developing. You can still use Eclipse if you want to.

Instructions for:

Netbeans;
IntelliJ IDEA;
Visual Studio Code (VSC);
Eclipse.

Netbeans

Steps to retrieve, build and run XMage

Install NetBeans. We recommend installing at least version 7.2 because it has Git support by default. 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
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.

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.
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.

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.
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.
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.

IntelliJ IDEA

Retrieving, building and running XMage with Jetbrain IntelliJ

Download and install IntelliJ IDEA from the official website. The Community Edition is free and contains everything that's needed to start.
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.
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.
You will then need to create a couple of Run Configurations. Alternatively, everything else could be done from the Terminal window found in IntelliJ (should have a 'Terminal') link at the bottom of the screen.
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 you got heap size error while running maven task then go to project settings maven -> runner and add that default VM option: "-Xmx1000m". 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

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.
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.
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

Pick 'Maven' from the popup. Name is '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".
You can create another Maven configuration that does not skip tests by redoing the previous step and removing -DskipTests.
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

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).
Repeat the previous step by replacing instances of 'server' with 'client'. The Main class should also be mage.client.MageFrame.
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.
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.
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

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.
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.

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.

Visual Studio Code (VSC)

Steps to retrieve, build and run XMage

Install VSC (if your version can't works with project and freezes then you can install VSC Insiders);
Clone xmage project to any directory;
Open that folder in VSC;
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;

Restart IDE and re-open project - it's can ask to import maven configuration and start to scan project files. Wait until finished;
Open terminal window and enter mvn install -DskipTests -- maven must build all project files;
If you see error messages then open Problems tab and filter it by error;
Open View -> Debug and press Add Configuration -- selects java and VSC generates config for you;
Open that config, delete all lines and add that:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "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;

Eclipse

Steps to retrieve, build and run XMage

Install Eclipse;
Clone xmage project to any directory: git clone https://github.com/magefree/mage.git;
Change Eclipse default file encoding to UTF-8: Window -> Preferences -> General -> Workspace : Text file encoding;
Open command line window in xmage root folder and enter mvn install -DskipTests -- maven must build all project files;
Open Eclipse and start to import new project from dir;
After import completed wait some time for background project scanning finished;
If you got build error messages like missing JFX then select each maven project in packages 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;
Open Project -> Build to test all builds fine;
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

Open extra menu from run button in toolbar and select "Organize Favourites" -> Check on client and server configs;
Now you can run client and server apps;

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.

Tools

Maven

MAGE is a Maven project so it’s a good idea to have it. A guide on installing it can be found here.

To run a Maven task, just open up a console/terminal, go to XMage's root (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 from 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. 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)

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 in your /[your_project_dir]/utils/ directory and start 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. 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.

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. 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.