Developer HOWTO Guides

Introduction

Before proceed read getting started guide about tools and project structure.

Below you can found howto guides or developer's checklist. XMage have some usefull perl scripts in game's folder to generate code, build or process other dev tasks. But all actions can be done manually without perl installation.

Content:

• Project prepare and pull request creates
• Add new card
• Add new token (not done)
• Add tokens support in new set
• Add new set
• Test other pull request
• Build your own release

Project prepare and pull request creates

1. Make your own copy of xmage repository (fork it from xmage page):
2. Go to your project page and make new branch for all changes:
3. Use IDE tools to clone your github project:
4. Switch to your branch by IDE and make any commits to it;
5. Open your repository on github and press "new pull request button" to create PR for main xmage repository:

Add new card

1. Select card to implement (example: "Anvilwrought Raptor");
2. Find out all info about card (example from scryfall);
3. Make sure it's not implemented yet -- search source code for "card name";
4. Find old card with the same or similar abilities (use scryfall advanced oracle search or source code search);
5. Prepare empty card stub -- generate it by perl script or files copy-paste:
   • By use of the perl script (explained in the getting started guide);
   • By create new java class file and copy paste source code from any other card to it:
     • Rename java class to card name in Camel Case Notation without any special chars or spaces (example: Angrath, the Flame-Chained -> AngrathTheFlameChained);
     • Check out card type, cost and subtype of new card;
     • Remove not necessary abilities or code from old card;
6. Add card's abilities:
   • Use copy paste code from similar card;
   • Change and setup that code to your cards, e.g. change filter or condition;
   • Use IDE code complete to hint correct class and method access (they all have same names as they describe on card. Example for flying ability: this.addAbility(FlyingAbility.getInstance()););
7. Add new card to set's list (no need if you use perl script -- it's add cards to the list automatically):
   • Find set's file in ..\Mage.Sets\src\mage\sets\YOUR_SET_NAME.java;
   • Card's list by alphabetically order;
   • Copy paste line from any other card near and change it to your card;
   • Check out card name, card number, card rarity and card class name;
   • If your card have different images then add new line for each image but with different card numbers like "123a", "123b", "123c";
8. All done, now time to test:
   • Restart test server and client from your source in test mode (see testing strategy info);
   • If xmage can't find your card name (see errors log or check it in deck editor) then delete all cards*.db files in developer folder -- it's force to recreate new database;
   • Make sure your card work fine and have same text as it have on paper (hint: if card's have wrong or missing text then ability settings was incorrect -- try to fix it first);
   • Run all xmage tests, they all must be green (see xmage testing tools);
   • Try to download card image (use xmage download images window for card's set);
9. Commit changes (new card file and changes set file) and pull request it.

Add new token

TODO

Add tokens support in new set

How's xmage tokens works

All tokens list stores at card-pictures-tok.txt -- that's tokens "database" and that's list manually edited. Each token must be linked to real token class that used in set's card (that's help to use different token images for same name):

How's to add new tokens and downloads:

• Open set's tokens list at scryfall;
• Take first token name and search cards with (oracle:token set:m19 oracle:token_name) -- you can find all cards that uses that token;
• Search that cards source code in xmage and look at token creating code. It can use different token classes.
• Add each token usage in card-pictures-tok.txt. Tokens with same name but different images and classes must have different indexes (1,2,3) and classes:
• Open scryfall tokens source and add direct link to download image for same token's index;
• Same for emblems, but it must use specific name notations in tokens and scryfall files.

Add new set

1. Create new set's java file in ..\Mage.Sets\src\mage\sets\ folder by copy-paste template from any other set (example: ExplorersOfIxalan.java);
2. Setup official set code and release date (use scryfall for set's info);
3. Add new cards to set (see above);
4. Add new tokens to set (see above);
5. Setup set symbols download options:
   1. Go to ..\Mage.Client\src\main\java\org\mage\plugins\card\dl\sources\GathererSets.java;
   2. Add set's code to one of the supported list (example: symbolsBasic);
   3. Add replace code when source uses non standard codes (example: codeReplacements.put("CMA", "CM1"););
6. Setup card images download options:
   1. Find current supporting images sources DownloadSources in ..\Mage.Client\src\main\java\org\mage\plugins\card\images\DownloadPictures.java file;
   2. For each image source that you can download go to class file and add set's code to support list;
      1. Add set's code to supported (example for scryfall: supportedSets.add("OGW"););
      2. Add replace code when source uses non standard codes (example for scryfall: put("DD3GVL", "gvl"););
   3. If set's can be downloaded then remove that code from global ignore list (ignore.urls in C:\mage\Mage.Client\src\main\resources\image.url.properties file);
7. Setup token images download options:
   1. Some sources can support tokens download: if so then repeat cards images setup but search source code for tokens data (start with getTokenImages() method from java class, example: ..\Mage.Client\src\main\java\org\mage\plugins\card\dl\sources\TokensMtgImageSource.java);
   2. Add tokens data to ..\Mage.Client\src\main\resources\card-pictures-tok.txt;
   3. Find each new token class and add set's code to supported list tokenImageSets.addAll (example: ..\Mage\src\main\java\mage\game\permanent\token\SaprolingToken.java -- it's will help xmage to select token image on battlefield by set's priority (see image.url.properties file);

Test other pull request

If you want to test other pull request before merge.

Simple way:

1. Use github hints by click on "view command line instructions":

Difficult way:

1. Go to pull request page and save it's number like #4306;
2. Open git and run command to fetch new pull request to new branch: git fetch origin pull/4306/head:test-pull-request where:

• origin -- name of the xmage repository (to find out it in IntellJ IDEA go to VCS -> Git -> Remotes);
• 4306 -- pull request number;
• test-pull-request -- temporary branch for test;

3. Open new created branch by checkout test-pull-request;

Build your own release

If you want to build your own release (nightly build) and distribute it to your friends then follow that:

1. Install IDE and setup it to build xmage projects (see Developer Getting Started);
2. Build full source code for client and server by clean install -DskipTests maven command:
3. Build release packs for client and server by assembly:assembly maven command:
4. Download official release, run it, update all files, clean up it and prepare for re-release:

• Delete folder ..xmage\java (you can't distribute with client -- each OS used different java versions and must download it by launcher);
• Open installed.properties file in launcher folder and remove line java.version=... (it's help launcher to download new java on startup);
• You can also edit line xmage.version=1.4.29V4 (2018-05-01) to change it to current versions -- it's help disable update notification about "new version available" on startup;
• Delete all files and folders in ..xmage\mage-client\plugins\images (if you want distribute your client with card images and icons then do not clean it);
• Delete all files in ..xmage\mage-client\db and in ..\xmage\mage-server\db (it's help to re-create update cards data);

5. Copy zip-files and unpack it to that release folder with file replacement:

• ..\Mage.Client\target\mage-client.zip;
• ..\Mage.Server\target\mage-server.zip;

6. Zip all xmage folder and release that pack -- other users must download it, unzip, run launcher, update java and start to play (do not use "update" again after java download -- it's will rewrite your files with official release;
7. Some versions is not fully compatible with current official servers and potential can cause bugs and freezes -- try to use it with new server.