diff --git a/Contributing-to-the-Cockatrice-Tokens-File.md b/Contributing-to-the-Cockatrice-Tokens-File.md index fb67bcd..4c5112c 100644 --- a/Contributing-to-the-Cockatrice-Tokens-File.md +++ b/Contributing-to-the-Cockatrice-Tokens-File.md @@ -41,7 +41,9 @@ Make a copy of the tokens.xml file and add you entries to it in alphabetical ord ### Go through the list of new entries and link tokens to the cards that make them -The `reverse-related` tag links the token entry to the card that makes the token. This allows users to make the specific token they need in the specific quantity they need it in from the card they are playing. +#### The `reverse-related` tag + +The `reverse-related` tag links the token entry to the card that makes the token. This allows playerss 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: @@ -51,25 +53,55 @@ Here are some examples: `Soul of Emancipation` -`Finale of Glory` - `Valkyrie's Sword` 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 `count` attribute specifies how many tokens the card should make when the user 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 user to enter a number of tokens (defaulting to 1) and something like `count="x=3"` will also prompt the user, but will default to 3. This is useful when a card makes a variable number of tokens but is guaranteed to make at least a certain number. +#### `count` -Some tokens need to be attached to the card that made them. Including the `attach` attribute and setting it to "attach" (as in example 5 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 `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. -When making tokens from a card, there are two kinds of options available to the user. 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`). For example, *Finale of Glory* 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. Including the `exclude` attribute and setting it to "exclude" (as in the forth example) prevents a token from being made with `Create All Tokens`. This is useful when a card makes multiple kinds of tokens (or different quantities of the same token), but has different conditions for making them. +#### `attach` -`exclude` is also useful for cards that make tokens on enter the battlefield or leave the battlefield effects (e.g. Landfall) to allow the user to choose to make one at a time or to make some set number if they have a lot of triggers at once. For example, the Insect Token made by *Scute Swarm* has these two lines: +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). + +#### `exclude` + +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: + +`Finale of Glory` + +While its tag in the soldier token entry looks as expected: + +`Finale of Glory` + +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: + +`Bill Ferny, Bree Swindler` + +`Bill Ferny, Bree Swindler` + +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: `Scute Swarm` `Scute Swarm` -The first lets the user make one insect token and the second lets the user get prompted to enter an amount instead. The user would not want the default behavior to be 'make one token and also prompt me to make X' so the second is excluded. +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 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).