Adding Tokens from New Sets

Where are tokens from new sets added?

Please open a pull request in the Cockatrice/Magic-Token repository to add tokens from new sets and include the three letter set code in your PR title. Please only add entire sets and do not add tokens piecemeal; if you want to add one token, you must add them all, even if most are reprints.

When are tokens from new sets ready to be added?

Scryfall is the primary source of spoilers for new sets and generally post their full preview of the set 2 weeks before release. You will be able to tell as their homepage will change to say "[Name of Set] Full Preview" as a new news post under the search bar. The tokens are usually the last thing to be updated and all of them may not be available for a day or two after the full preview of the rest of the cards goes up.

It is important to make sure that the set is fully up on Scyfall before adding it to the tokens file to avoid missing tokens (or cards that make them) and having to add them in later. Generally, you can do this by looking up the set on MTG wiki and checking how many tokens and cards are expected to be printed in the set. Remember that there is no rush to add new sets and it is better to put in a complete and error-free addition later than an incomplete addition earlier.

How are tokens from new sets added?

The process that I generally follow is as follows. Each step is elaborated on below.

1. Create the entry for each token
2. Add each new entry to the token list and add reprints as set tags
3. Go through the list of new entries and link tokens to the cards that make them
4. Perform quality control checks on the new list

I have a Python script that for the most part handles Steps 1 and 2 automatically; you can find the code and an explanation of how it works here. I will detail some recommendations for doing those steps manually as well.

Create the entry for each token

Get a copy of the most current tokens.xml file from the Cockatrice/Magic-Token repository.

Copy the italicized template at the top of tokens.xml for each new token entry and fill out the various tags using information from Scryfall. A full explanation of what all the tags mean can be found here. You can ignore the reverse-related and related tags for now; I will cover them in detail in Step 3. The manacost tag can safely be deleted for any token entry and you may not need all the tags depending on the complexity of the token. Please delete any empty tags to keep the entry neat.

When filling out the tags (especially name, type, and reverse-related), please copy and paste whenever possible. Typos in tags can break functionality or cause Cockatrice to behave in unexpected ways.

When filling out the name tag, please be aware of these two rules:

1. We follow WotC's rules for naming tokens. That is, any generic token (e.g. Goblin Token) needs to have 'Token' after its name and any specific token (e.g. Boo) does not. An emblem has 'Emblem' after its name.

2. All token names have to be unique across Cockatrice. For generic tokens, this means adding some number of spaces after the 'Token' to differentiate it from other same name generic tokens (e.g. 'Goblin Token', 'Goblin Token ', etc. for the plethora of different goblin tokens). For specific tokens that share a name with an existing card (e.g. tokens made with Embalm or Squad) this means that they need to have '(Token)' after their name to differentiate them from their card counterparts (e.g. Angel of Sanctions (Token))

When filling out the set tag, please prioritize using a Scryfall large image link (this should be the link you copy if you Copy Image Link from the card image on Scryfall) for the picURL attribute.

As you make entries for these tokens, you will find that some are reprints that already have an entry in the tokens file. For these, please just add a new set tag one line above the existing set tags with the appropriate set and picURL information. Please take special care to ensure that these are exact reprints and not merely very similar.

Add each new entry to the token list and add reprints as set tags

Add your new entries to your copy of the tokens.xml file in alphabetical order (regular tokens are listed first and then things like emblems, states, companions, etc are listed later). Add in set tags for reprints as described above. As mentioned above, take note of how many other tokens share a name with any new tokens you are adding and add spaces as necessary to make the names unique.

Go through the list of new entries and link tokens to the cards that make them

The reverse-related tag

The reverse-related tag links the token entry to the card that makes the token. This allows players to make the specific token they need in the specific quantity they need it in from the card they are playing.

Here are some examples:

<reverse-related>Haunted Angel</reverse-related>

<reverse-related count="5">Elspeth Resplendent</reverse-related>

<reverse-related count="x=3">Soul of Emancipation</reverse-related>

<reverse-related attach="attach">Valkyrie's Sword</reverse-related>

As you can see, the reverse-related tag is made up of several parts. The name in the middle, in between the tag start and end, specifies the card that makes the token. The words within the <reverse-related> tag start are called attributes and they change how the relations function.

The count attribute

The count attribute specifies how many tokens the card should make when the player tells it to make tokens. count=1 is assumed and does not needed to be stated, as in the first example, and count="5" will make exactly five tokens. count="x" will prompt the player to enter a number of tokens (defaulting to 1) and something like count="x=3" will also prompt the player, but will default to 3 instead of 1. This is useful when a card makes a variable number of tokens but is guaranteed to make at least a certain number.

The attach attribute

Some tokens need to be attached to the card that made them. Including the attach attribute and setting it to "attach" (as in example 4 above) allows this to happen automatically on token creation. This is mainly useful for equipment. Setting the attach attribute to "transform" allows the card to transform into the token instead of creating it (e.g. Incubator Token).

The exclude attribute

One other attribute that can be included in reverse-related tags in exclude. Rather than relating directly to a rule of MTG, the exclude attribute relates to the technical implementation of creating tokens in Cockatrice. When making tokens from a card, there are two kinds of options available to the player. One is to make every token that the card can make (Create All Tokens) and the other is to make each individual kind of token (e.g. Create 3/3 Beast Token). When a card makes multiple kinds of tokens or different numbers of tokens at different times, we can use exclude to change the behavior of Create All Tokens to be in line with how the card works. I will give three cases to explain this in detail.

Case 1 - Finale of Glory

Finale of Glory is an example of a card that can make different types of tokens under different conditions. It can create X soldier tokens or X angel tokens depending on the value of X. Without any attributes Create All Tokens would create both kinds of tokens, which is not what the card does. Instead, its reverse-related tag in the angel token entry looks like this:

<reverse-related count="x" exclude="exclude">Finale of Glory</reverse-related>

While its tag in the soldier token entry looks as expected:

<reverse-related count="x">Finale of Glory</reverse-related>

Including the exclude attribute and setting it to "exclude" in the angel token entry prevents Create All Tokens from creating angel tokens, allowing it to merely create X soldier tokens, which is the more likely option to occur when the card is played.

Case 2 - Bill Ferny, Bree Swindler

Bill Ferny is an example of a card that can make one token or more than one token under different circumstances. Specifically, it can make one treasure token or three treasure tokens depending on what the player chooses. The two reverse-related tags for it in the Treasure Token entry are as follows:

<reverse-related>Bill Ferny, Bree Swindler</reverse-related>

<reverse-related count="3" exclude="exclude">Bill Ferny, Bree Swindler</reverse-related>

As above, the less likely option is excluded, allowing Create All Tokens to make a single treasure token when used.

Case 3 - Scute Swarm

Scute Swarm is an example of using exclude when a card has an enters the battlefield or leaves that battlefield trigger (in this case, Landfall). The most common case is that only one card will enter or leave the battlefield at a time, meaning that a player will only want to create one token at a time. However, it is not unlikely that a player will have multiple such effects in a turn and maybe need to create several tokens at once. To facilitate this, the Insect Token made by Scute Swarm has these two lines:

<reverse-related>Scute Swarm</reverse-related>

<reverse-related count="x" exclude="exclude">Scute Swarm</reverse-related>

The first tag gives the player the option to make exactly one insect token and the second tag gives the player the option to get prompted to enter an amount and make multiple instead. Since the count="x" option is excluded, Create All Tokens will make a single insect token and will not prompt the player to enter an amount, again mimicking the most likely to be used option. Note that you should not apply this same logic to cards that makes tokens when spells are cast since each token should be made as each spell resolves.

The related tag

One other tag to note here is related. This tag lets you specify a token that is created by the token entry instead of creating it. This is useful for the occasional tokens that make other tokens (usually when they die) like the Boar token that makes a Food token when it dies. related can also have attributes like count. related and reverse-related are redundant with each other; you do not need to add both to set up a relationship (and, in fact, this will make a mess of the token UI).

Suggested workflow for adding reverse-related tags

Adding in reverse-related tags has to be done manually as there is a lot of nuance to it that is not easily automated. Here is the process that I follow to ensure I do it systematically.

1. Do an oracle search for token name within the set to find all the cards that make it. Make sure to also search for the commander set if applicable as cards in commander often make tokens in the base set and vice versa. I like to use this format: (set:[set three letter code] or set:[commander three letter code) o:"[token type]" to make sure I cast a wide net. For example, (set:mom or set:moc) o:"incubator token" finds all the cards in March of the Machines and the commander set that make incubators. You may need to specify color or power an toughness if you have similar tokens to look for. Also, be aware that o:"" searches for exact text so make sure it is formatted exactly as it is on the cards that make the token.

2. Copy enough lines of reverse-related for every entry that is needed. For reprinted tokens, you may not need to add all the cards in the search as they may be reprinted cards that already are related.

3. Copy the card name directly into the tag. Be careful of spacing and indentation

4. Fill out the exclude and count attributes if needed. Refer to Reverse-related rules above. If the token creates a card/token, make a related entry.

5. Repeat 1-4 for each token

6. Do an oracle search for token creation within the set to double check there are no tokens with missing entries and make entries as necessary (e.g. (set:mom or set:moc) o:"token" o:"create" should pull up every card that makes a token)

You may need to do more custom searches for keywords like Amass or Living Weapon as those don't always have reminder text so they won't show up in a search for 'army creature token' or 'germ creature token'. Don't forget to do emblems and other odd ones like Monarch.

Perform quality control checks on the new list

1. Check token file for parsing errors using xmllint (as explained here).

2. Load the file in cockatrice by replacing the tokens.xml file in your Tokens database path with your new file (renaming it tokens.xml) and open Cockatrice. Search for tokens in the new set(s) and check image links/name space collisions and make sure all the needed card info is there.

Fixing Issues with the Tokens File

As above, please open a pull request in the Cockatrice/Magic-Token repository to fix issues with the token file. Please open one PR per issue or group of related issues; try not to lump together several unrelated changes even if they are small.

If you would like to help out with an ongoing issue of some tokens missing art in Cockatrice because they were never physically printed, please see this issue.