MTGOFormatData

Format data for use with MTGOArchetypeParser (https://github.com/Badaro/MTGOArchetypeParser).

Active Maintainers

Standard: Jiliac
Pioneer: Jiliac
Modern: Jiliac
Legacy: Jiliac
Pauper: Jiliac
Vintage: IamActuallyLvL1

Aliquanto, Lardach and Badaro also provide occasional help with archetypes.

Data Structure

All formats are required to be placed under the "Formats" folder.

/Formats/MYFORMAT

Each format must contain the following files and folders:

metas.json
color_overrides.json
/Archetypes
/Fallbacks

There's a description of each of these files below, but you can also check the /Formats/Modern folder to see a live example.

metas.json

This file contains the breakdown of metas for that particular format. This is used as one of the fields in the CSV file generated by MTGOArchetypeParser, and also specify the initial date it'll use for CSV generation.

The metas.json file contains an array of objects with a date (in yyyy-mm-dd format) and a name for each meta.

{
   Metas:
   [
      { "StartDate": "2020-06-25", "Name": "PostM21" },
      { "StartDate": "2020-09-16", "Name": "PostZendikarRising" }
   ]
}

color_overrides.json

This file is used to manually specify how some cards will be treated by the color detection engine. The main use for this is to specify multi-color lands strongly associated with 5C decks.

Notice that this file has a separate property for Lands and NonLands:

{
   "Lands":
   [
      { "Name": "Ancient Ziggurat", "Color": "WUBRG" },
      { "Name": "Sliver Hive", "Color": "WUBRG" }
   ],
   "NonLands": null
}

You can check the default color assignments for each card by looking at the /Formats/card_colors.json file. That file is auto-generated from the MTGJSON file following a few rules, and will be updated for each set release.

Archetypes

This folder should contain one file for each archetype defined. Each archetype has four properties:

Name
IncludeColorInName
Conditions
Variants

The Conditions define the rules for how to match an archetype. They are an array of objects containing two properties:

    {
      "Type": "InMainboard",
      "Cards": ["Ad Nauseam"]
    }

Type must be one of the following values:

InMainboard
InSideboard
InMainOrSideboard
OneOrMoreInMainboard
OneOrMoreInSideboard
OneOrMoreInMainOrSideboard
TwoOrMoreInMainboard
TwoOrMoreInSideboard
TwoOrMoreInMainOrSideboard
DoesNotContain
DoesNotContainMainboard
DoesNotContainSideboard

This work in conjunction with the Cards property to define the conditions for those rules to match.

InMainboard/InSideboard/InMainOrSideboard: The card listed is required in the MB/SB depending on which rule you use.
OneOrMoreInMainboard/OneOrMoreInSideboard/OneOrMoreInMainOrSideboard: At least one of the cards listed is required in the MB/SB depending on which rule you use.
TwoOrMoreInMainboard/TwoOrMoreInSideboard/TwoOrMoreInMainOrSideboard: At least two of the cards listed are required in the MB/SB depending on which rule you use.
DoesNotContain/DoesNotContainMainboard/DoesNotContainSideboard: The card listed must not be present in MB/SB depending on which rule you use.

If an archetype has multiple conditions, all must be satisfied for the archetype to match successfully.

To help understanding, here's two examples. This is the current "Ad Nauseam" archetype definition for Modern:

  "Conditions": [
    {
      "Type": "InMainboard",
      "Cards": ["Ad Nauseam"]
    },
    {
      "Type": "InMainboard",
      "Cards": ["Angel's Grace"]
    },
    {
      "Type": "InMainboard",
      "Cards": ["Phyrexian Unlife"]
    },
    {
      "Type": "InMainboard",
      "Cards": ["Pentad Prism"]
    }
  ]

It specifies four different cards with the "In Mainboard" rule, so the deck must contain all four cards to match successfully.

This is the current "Belcher" archetype definition for Modern.

  "Conditions": [
    {
      "Type": "InMainboard",
      "Cards": ["Goblin Charbelcher"]
    },
    {
      "Type": "TwoOrMoreInMainboard",
      "Cards": ["Simian Spirit Guide","Irencrag Feat","Chancellor of the Tangle","Desperate Ritual","Pyretic Ritual"]
    }
  ]

This deck has several possible configurations of rituals that can be used, which are listed in the "TwoOrMoreMainboard" condition. Any combination of "Belcher+2x Rituals" will be a successful match.

An archetype may also include multiple Variants. Each variant has the same structure as the archetype, and for a variant to match the deck needs to first match the "main" archetype rules, then match the variant rules. This is particularly useful when you have several similar archetypes that use similar "core" but still have enough differences that you want to tag them separetely. Check the Formats/Modern/Archetypes/Tron.js file for an example of variant usage.

Fallbacks

One of the challenges of automated tagging is how to work with "goodstuff" decks, that don't have specific archetype-defining cards, like generic "[Deck Color] Control" or "[Deck Color] Midrange" decks. There's way too many variations between these, and creating archetypes for all of them is rather cumbersome and difficult to maintain.

MTGOArchetypeParser supports an alternative to deal with these decks by using "Fallbacks", or "Piles". They are defined as a set of "Common Cards" that are frequently used in decks of this archetype. As an example, here's the current list of common cards used for "Control" piles in Modern:

  "CommonCards": [
    "Cryptic Command",
    "Archmage's Charm",
    "Drown in the Loch",
    "Mana Leak",
    "Force of Negation",
    "Creeping Tar Pit",
    "Celestial Colonnade",
    "Supreme Verdict",
    "Terminus",
    "Dead of Winter",
    "Teferi, Hero of Dominaria",
    "Teferi, Time Raveler",
    "Jace, the Mind Sculptor",
    "Ral, Izzet Viceroy",
    "Snapcaster Mage",
    "Shark Typhoon",
    "Jace, Vryn's Prodigy"
  ]

Whenever there' s a deck that it fails to identify using the Archetype rules, it'll compare this deck to all the fallbacks defined and see which fallback it shares the most cards with, and tag the deck using that fallback.

Notice there's a rule requiring at least 10% matching cards with a fallback for it to be accepted, so even with multiple fallbacks it's possible for a deck to fail all fallbacks.