WML for Beginners (Updated): Part 2

From The Battle for Wesnoth Wiki
Revision as of 05:31, 20 June 2020 by Volatus (talk | contribs)

In the second part of this series, we are going to talk a bit more about tags, now focusing on how they relate to each other, and learning new vocabulary on how to refer to these relations. Secondly, the "types of data" in WML will be mentioned and we are also going to touch the surface of the preprocessor and its properties. Last, but not least, we are going to see some conventions for organizing your code and a bit about the use of whitespace in WML code. As you can see, this part of the tutorial is quite big. Read and understand at your own pace, going back to here multiple times if needed. Use the navigation tab at the end of the page to go between pages and the index.


Tag Relations

As we have previously seen, tags can (and do) enclose attributes and their set values. What I haven't told you yet is that tags can also enclose (and be enclosed by) other tags! This way, one tag either contains or is contained within another tag. When a tag A is enclosed by tag B, we say tag A is a child of B. Thus, when a tag B encloses tag A, we say tag B is the parent of tag A. This can imply complex relationships, like the one below:

[A]
    [B]
        [D]
        [/D]
    [/B]

    [C]
    [/C]
[/A]

In the above case, many things can be stated. First, we can say tag A is the parent of both tags B and C, and the grandparent of the D tag, which by itself is a child of B and a grandchild of A. Furthermore, B and C can be called direct children of A while D (child of B) can be called an indirect child of A (the same way A is a direct parent of B and C but an indirect parent of D). Whew, that was a lot right here. Feel free to read this as many times as you want. Just make sure you have grasped the previous info before further reading.

With these terms in mind, the definition of a top-level tag becomes much simpler to both understand and imply. To the extent of our current terminological knowledge on this topic, the definition of top-level tag can be stated as:

  • top-level tag: a tag which isn't a direct nor indirect child of any other tag and may or may not enclose (be a direct or indirect parent of) another tag(s).


Attribute Values

Before entering the specific topic of Attribute Values, we might take a look at what a string is defined as. A string is basically a sequence of characters which, together, comprise one or more lines of text. Both "flying monkeys" and "553 flowers" are strings (note that in the latter the number "553" is also considered part of the sequence and while they are numerical characters, in this specific context, they are also considered text). There are times when we are going to join two strings together, uniting, for example, "flying " (note the single space at the end) and "monkeys." to form the string "flying monkeys". This process is called concatenation.

Now that you understand strings and what concatenation is, we can proceed. All attribute values (everything to the left of the assignment operator aka. equals sign) are, at the end of the day, considered strings by the parser (do not worry about this word yet; for now, you must remember this is what converts WML into information the game engine can actually understand and make use of). To represent a string as the value of an attribute, simply make it double-quoted. Take a look at the following example:

[unit]
    name = _ "William"
    type = "Orcish Grunt"
[/unit]

You might have noticed there's an underscore before the value of the first attribute (name) of the unit tag above. Do not worry. This was not a typo. This preceding underscore indicates this is a translatable string. That means it is "marked" as a string that might be translated into other languages. Text that is shown as the campaign's story or as the characters' "speech bubbles" are usually composed of translatable strings while the rest usually isn't.