Leahnaya/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2026-04-24 23:36:01 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated Tips for Contributing to the Cockatrice Tokens File (markdown)

SlightlyCircuitous 2023-06-17 01:04:57 -04:00
parent fb2e349f4c
commit 71fa3091c3
1 changed files with 32 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
Tips-for-Contributing-to-the-Cockatrice-Tokens-File.md → Contributing-to-the-Cockatrice-Tokens-File.md

@ -1,20 +1,27 @@
# Adding Tokens from New Sets
## Where are tokens from new sets added?
Please open a pull request in the [Cockatrice/Magic-Token repository](https://github.com/Cockatrice/Magic-Token) 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 which tokens are expected to be printed with the set and how many 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. Cockatrice is provided as a free service and is maintained by volunteers; you do not owe anyone your time.
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. Cockatrice is provided as a free service and is maintained by volunteers; you do not owe anyone your time.
## How are tokens from new sets added?
The process that I generally follow is:
1) Create the entry for each token, excluding any reverse-related lines
2) Add each new entry to the token list and add reprints as set lines
3) Go through the list of entries and add reverse-related lines
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](https://github.com/SlightlyCircuitous/update-token-xml). I will detail some tips for doing those steps manually as well.
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](https://github.com/SlightlyCircuitous/update-token-xml). I will detail some recommendations for doing those steps manually as well.
### Create the entry for each token
Copy the 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](https://github.com/Cockatrice/Cockatrice/wiki/Custom-Cards-&-Sets#to-add-your-own-custom-cards-follow-these-steps). 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.
Get a copy of the most current tokens.xml file. This can be found either in the Cockatrice/Magic-Token repository or locally on a computer with Cockatrice at the path listed in `Settings -> General -> Token database`. If you use the local copy, make sure you run `Help -> Check for Card Updates...` first.
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](https://github.com/Cockatrice/Cockatrice/wiki/Custom-Cards-&-Sets#to-add-your-own-custom-cards-follow-these-steps). 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.
@ -22,19 +29,19 @@ 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 ', '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)')
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 lines
### Add each new entry to the token list and add reprints as `set` tags
Make a copy of the tokens.xml file (found either in the Cockatrice/Magic-Token repository or locally at the path listed in `Settings -> General -> Token database`) and add you entries to it 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.
Make a copy of the tokens.xml file and add you entries to it 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 entries and add reverse-related lines
### 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 to allow 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 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.
Here are some examples:
@ -48,19 +55,21 @@ Here are some examples:
`<reverse-related attach="attach">Valkyrie's Sword</reverse-related>`
As you can see, `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.
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 and something like `count="x=3"` will also prompt the user, but will automatically fill in 3. This is useful when a card makes a variable number of tokens but is guaranteed to make at least >1.
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.
When set to "attach", the `attach` attribute automatically attaches the card that makes the token to the token it made. This is mainly useful for equipment. Setting the `attach` attribute to "transform" instead allows the card that makes the token to transform into the token instead (e.g. state tokens like 'Day' and 'Night'), removing the creating card in the process.
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).
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 and the other is to make each individual kind of token. The `exclude` attribute prevents a token from being made with the first option when set to "exclude". 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 so you wouldn't want them all at once. It 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 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:
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.
`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:
`<reverse-related>Scute Swarm</reverse-related>`
`<reverse-related count="x" exclude="exclude">Scute Swarm</reverse-related>`
The first lets the user make one insect 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 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.
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).
@ -80,4 +89,9 @@ You may need to do more custom searches for keywords like Amass or Living Weapon
1) Check token file for parsing errors using xmllint (as explained here: https://github.com/Cockatrice/Cockatrice/wiki/Custom-Cards-&-Sets#diagnosing-problems-in-your-xml-file).
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.
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](https://github.com/Cockatrice/Magic-Token) 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.](https://github.com/Cockatrice/Magic-Token/issues/85)