Development HOWTO Guides

Introduction

Before proceeding, please read Project Overview and Setting up your Development Environment.

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:

• Adding a new card
• Adding a new token (TODO)
• Adding token support in new set
• Adding a new set

Add new card

1. Select card to implement (example: "Anvilwrought Raptor");
2. Find out all info about card on Scryfall. Anvilwrought Raptor;
3. Make sure it's not implemented yet -- search source code for Anvilwrought Raptor or the file AnvilwroughtRaptor.java (remove spaces)
4. Find old card with the same/similar abilities using Scryfall's advanced oracle search
5. Prepare empty card stub:
   • By use of the gen-card.pl perl script explained in Setting up your development evironment;
   • By creating a new .java class file and copying the source code from a similiar card:
     • 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 useless abilities/code from the old card;
6. Add card's abilities:
   • Copy paste code from a similar card;
   • Change and setup that code to your cards, e.g. change filter or condition;
   • Use IDE code completion to hint the correct class and method access
     • They all have same names as they would be on a card. E.g. Flying: this.addAbility(FlyingAbility.getInstance());
7. Add new card to set's list:
   • [ ! ] If you used the perl script in step 5. it will already have done this, so skip to step 8.
   • Find set's file in ..\Mage.Sets\src\mage\sets\YOUR_SET_NAME.java;
   • 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 has 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);
   • If XMage can't find your card name (see errors log or check it in deck editor)
     • You can try to delete all cards*.db files in developer folder -- it forces XMage to recreate a new database.
     • Alternatively try checking the box "Force update of card database" in the client application on its startup screen;
   • Make sure your card works fine and has the same text as it has on paper (hint: if card's have wrong or missing text then the ability settings was incorrect -- try to fix it first);
   • Warning: xmage doesn't update card text after changes, so you need to clean up \Mage.Client\db\ folder to generate cards database or run single unit test test_showCardInfo to check rules text in real time by command:
     • mvn install test -DfailIfNoTests=false -Dtest=VerifyCardDataTest#test_showCardInfo
   • 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 (card & set file) and open a pull request on github
   • Using git is mentioned in Development Workflow

Add new token

TODO

Add tokens support in new set

How XMage token work

All tokens are stored in a list at card-pictures-tok.txt. This is the "database" for tokens, and it is manually edited. Each token must be linked to real a token class, which is used in that set's card (So that the same token can have different images depending on the set):

How to add new tokens and downloads:

• Open the set's Scryfall token list;
  
• Take first token name and search on scryfall 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 ScryfallImageSupportTokens.java 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 the new set's java file in the ..\Mage.Sets\src\mage\sets\ folder, by copy-pasting a template from any other set (e.g. 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 (most likely: 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\DownloadPicturesService.java file;
   2. For each image source that you can download go to class file (example: ScryfallImageSource.java);
      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);