DotP 2014: Coding Cards

Coding cards is a really broad topic, but it does generally fall into several smaller categories.

Structure of a card Cards are made up of several parts. The structure of a very simple card is below.

That is the complete code for the card Field Creeper. It has no abilities, but it does have flavor text. All of the tags included, with the exception of <FLAVOURTEXT>, will appear on all creature cards. If it was not a creature, then it would be the same as the above, except it would not have the following tags.

<TYPE metaname="Creature" />
<POWER value="2" />
<TOUGHNESS value="1" />

So, at this point, I'll explain exactly what a tag is. A tag refers to an XML element between These symbols <>. Tags come in two forms.

<SOMETAG >...</SOMETAG>
and
<SOMETAG />

Every tag that begins somewhere must be closed somewhere. The first example is the normal tag setup, and I usually refer to it as a block. The second version works the same as the first, except it can't contain other tags, and I usually refer to it as a one-line tag (technically an empty element tag). In XML, you can have tag trees.

<CARD>
  <NAME />
  <TYPE />
 </CARD>

In the above example, the tag <CARD> contains the <NAME> and <TYPE> tags. <CARD> opens the CARD tag, while </CARD> closes it. the NAME and TYPE tags are closed automatically thanks to their ending "/>".

Tags can also have attributes. Everything in a tag, from the tag's name to each attribute, is separated by spaces. The name of a tag, the section before the first space (if any) is the name. It is written on its own. Attributes, however, have values. For instance, in the type tag, it has the attribute "metavalue". And "metavalue" is an attribute whose value is a string. In the Field Creeper example, you'll see

<TYPE metavalue="Artifact" />

This begins the "TYPE" tag, adds the attribute "metavalue" with a value of "Artifact", and then closes the tag. Many attributes don't take strings, but rathers number, such as in the "POWER" and "TOUGHNESS" tags.

Sometimes, however, it uses a 1 in place "true", like a boolean. It simply means "this attribute applies". Attributes MUST have values, otherwise these ones wouldn't even have a 1. For example, consider the following.

<RESOLUTION_TIME_ACTION repeating_action="1">
...
</RESOLUTION_TIME_ACTION>

In the above example, there's a resolution time action (which will be explained later). Normally, the ellipsis would be replaced with lua code which will run one time when the ability this is in resolves off the stack. However, because it has the repeating action attribute, it can run multiple times as needed. The "1" in this case is less of a number and more of a boolean value. It doesn't mean to repeat the code 1 time. It simply means to repeat the code. Even if the code needs to run twenty times, it will still only have a 1 there. (The number of repetitions is handled in the lua code.)

There are many tags cards can have. This is not an exhaustive list, but it is a list of most of the ones you'll see a lot. <![CDATA[Field Creeper]]>

For help with tags, you can have a look at this spreadsheet. It's not exhaustive, and it will require much editing over time as other possibilities are remembered or discovered, but it should prove to be a useful resource. Its best use is likely to be the list of possible attributes different tags accept.

In the spreadsheet linked above, you may notice a few tags have the child tag "CDATA". "CDATA" is not actually a tag, but rather a special instruction to treat everything inside the inner brackets as literal text (which the game engine will parse for italics and symbols such as mana and tap). CDATA stands for CharacterData, and it's always set up the same way.

<![CDATA[This is literal text, such as ability text to display on the card, or its name.]]>

CDATA sections are always nested inside of a subtag within the <CARD> tag. By that, I mean these are all possible:

<CARD>
 <TITLE>
  <LOCALISED_TEXT><![CDATA[The card's name]]></LOCALISED_TEXT>
 </TITLE>
</CARD>

and

<CARD>
 <FLAVOURTEXT>
  <LOCALISED_TEXT><![CDATA[The card's name]]></LOCALISED_TEXT>
 </FLAVOURTEXT>
</CARD>

and

<CARD>
 <AUTHOR><![CDATA[The card's name]]></AUTHOR>
</CARD>

However, the following will never occur:

<CARD>
 <![CDATA[The card's name]]>
</CARD>

A few tags need some more in-depth information. Specifically, TRIGGER and COST.

TRIGGER tags only exist inside TRIGGERED_ABILITY blocks. They specify under what conditions the triggered ability's actions should run. TRIGGER tags always have teh attribute "value", which can be any trigger found in the Decompilable LOL Contents page. The triggers there always start with "TRIGGER_". However, when used in the "value" attribute of a TRIGGER tag, that prefix is removed. Whenever the game fires the trigger associated with a TRIGGER tag, the tag's attributes are checked. If those attributes all evaluate to true, then the tag's lua code is run if there is any. If the code returns true, then the ability is put onto the stack.

Here's an example:

<TRIGGERED_ABILITY>
 <LOCALIZED_TEXT Language_Code="en_US"><![CDATA[Whenever you sacrifice a creature, draw a card.]]></LOCALIZED_TEXT>
 <TRIGGER value="SACRIFICE" simple_qualifier="controller">
  return TriggerObject():GetCardType():Test(CARD_TYPE_CREATURE)
 </TRIGGER>
 <RESOLUTION_TIME_ACTION>
  EffectController():DrawCards(1)
 </RESOLUTIONT_TIME_ACTION>
</TRIGGERED_ABILITY>

In the code above, the TRIGGER's "SACRIFICE" value means this trigger will only be checked when something is sacrificed. When anything is sacrificed, even if it was an opponent who sacrificed something or it was a land, the trigger is checked. If the "simple_qualifier" attribute is true (so the person who sacrificed something was you, the person who controls this card), then and only then will the code inside the TRIGGER block run. When it runs, it checks if the object that was sacrificed was a creature and returns that answer. If it returns true, then the actions in the ability run, meaning you draw a card.

Now that we've covered the basics of tags and attributes.