The Battle for Wesnoth Wiki - User contributions [en]

WML for Beginners (Updated)

2020-11-09T01:35:39Z

Volatus:

Welcome to the WML tutorial for Beginners! This is an update on the old [[WML_for_Complete_Beginners | WML for Complete Beginners]] tutorial, which contains deprecated elements usage and unoptimized/unwritten parts. Having read the older version of the WML tutorial is not a requirement for reading and understanding this one, however.

Still, this tutorial series assumes you are using version 1.14.13 and have done the reading of the following pages:
* [[EditingWesnoth]] - explains the '''game data''' and '''user data''' directories' functionality within Wesnoth.
* [[AddonStructure]] - explains an addon's basic folder structure while giving a hint about '''_main.cfg''' (which will be discussed within this tutorial series with more detail).

== The Tutorial's Pages ==
* [[WML_for_Beginners_(Updated):_Part_1 | WML for Beginners (Updated): Part 1]]

WML for Beginners (Updated)

2020-11-09T01:35:23Z

Volatus: Blanked the page

WML for Beginners (Updated): Part 2

2020-09-03T18:49:15Z

Volatus: Removed Unnecessary Text stating obvious things.

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. 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:

<syntaxhighlight lang=wml>
[A]
[B]
[D]
[/D]
[/B]

[C]
[/C]
[/A]
</syntaxhighlight>

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 ==
Attributes can have their values be interpreted differently according to what characters they contain. Some specific attributes will also require specific kinds of values. Learn about these different kinds of values and what they are made of.

=== Strings and Concatenation ===
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'''.

=== Simple Text and Translatable Strings ===
Now that you understand strings and what ''concatenation'' is, we can proceed. All attribute values (everything to the right 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 text double-quoted. Take a look at the following example:

<syntaxhighlight lang=wml>
[unit]
name = _ "William"
type = "Orcish Grunt"
[/unit]
</syntaxhighlight>

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.

Another thing to pay attention to is the fact that strings can also be represented ''without'' double quotes, and are still passed as strings to the parser. In the following example, both attributes '''a''' and '''b''' have the same value.

<syntaxhighlight lang=wml>
[exampletag]
a = "This is recognizable text."
b = This is recognizable text.
c = "This is also " + "recognizable text." # These are concatenated strings. Use the + (plus sign) to concatenate strings. This will result in "This is also recognizable text."
[/exampletag]
</syntaxhighlight>

'''Best practice''': always keep your strings enclosed in double quotes to avoid confusion and have well-defined starting and ending points to them. There are a few exceptions to the rule, but those will be explained in another time.

=== Numerical Values ===
You are also able to represent numeric values, such as integers and decimals, using strings. These can then be used on mathematical operations such as adding, subtracting, multiplying, and dividing (worry not about how this is done, this is going to be covered further into the tutorial). For a string to be considered a numerical value, it might contain one or more digits from 0 to 9 and, additionally, may contain the following (only one of each):

* The negative sign ("-").
* The decimal indicator dot (".").

Any strings not following these rules won't be considered numerical values. See some examples below for a better understanding of acceptable and unacceptable numerical strings:

* "1056" - valid. It only contains digits.
* "305.26" - valid. It only contains digits and the decimal indicator dot.
* "-250.30" - valid. It only contains digits, the decimal indicator dot, and the negative sign.
* "-456" - valid. It only contains digits and the negative sign.

* "1056a" - invalid. It contains a letter.
* "305.2.6" - invalid. It contains two decimal indicator dots.
* "-250.3bananas" - invalid. It contains additional text.
* "-456-5" - invalid. It contains two negative signs.
* "potatoes" - invalid. It does not contain any digit.

'''Best practice''': do not enclose numerical values in double-quotes, unless they are used along with other text, such as in the middle of a string (e.g. they are not alone in their own string, and do not have the objective of strictly representing a numerical value). See the example below.

<syntaxhighlight lang=wml>
[exampletag]
a = "They have captured 6 of our soldiers!" # "6" is part of another string. Enclose in double-quotes.
b = 256 # "256" is alone and strictly represents a numerical value. Do not enclose in double-quotes.
[/exampletag]
</syntaxhighlight>

=== Lists of Values ===
Some specific attributes require the use of ''value lists''. These are simply values separated by a comma, be them numerical values, strings, and/or translatable strings. See below for an example of this.

<syntaxhighlight lang=wml>
[unit]
recruit = Orcish Grunt, Orcish Assassin # In this case, the strings are not enclosed in double-quotes because they are IDs, and while they CAN be enclosed in double quotes, this isn't recommended. We will talk about this further in the tutorial.
recruit = "Orcish Grunt", "Orcish Assassin" # Also valid.
[/unit]
</syntaxhighlight>

As you can see, Value Lists can be defined as simply as separating strings with a comma. You can also make lists of numbers (and as you may imagine, it is done by separating numbers with a comma).

== The Preprocessor ==
Whenever a WML file is read by Wesnoth, it goes through the '''Preprocessor''' before anything else. As the name suggests (with the ''pre-'' prefix, which means "before"), the Preprocessor goes over the file ''before'' processing.

The Preprocessor doesn't understand WML code, so tags, attributes, and values are none of its concern. The Preprocessor understands a much simpler language built with elements we know as Macros. In the Preprocessor arsenal we can also find '''Preprocessor Directives'''. Worry not about what all this stuff is; this section is designed to serve as an introduction to the Preprocessor and its capabilities, but the Preprocessor itself will be discussed in more depth at its own section.

=== The Inclusion Directives ===
One of the capabilities of the Preprocessor is including other files or directories into our file for ease of access. Using this in combination with the '''binary_path''' tag can help our game to find files it can use (such as map and scenario files). Here's how:

WML for Beginners (Updated): Part 2

2020-09-03T18:44:18Z

Volatus: Corrected an inconsistency

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. 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:

<syntaxhighlight lang=wml>
[A]
[B]
[D]
[/D]
[/B]

[C]
[/C]
[/A]
</syntaxhighlight>

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 ==
Attributes can have their values be interpreted differently according to what characters they contain. Some specific attributes will also require specific kinds of values. Learn about these different kinds of values and what they are made of.

=== Strings and Concatenation ===
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'''.

=== Simple Text and Translatable Strings ===
Now that you understand strings and what ''concatenation'' is, we can proceed. All attribute values (everything to the right 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 text double-quoted. Take a look at the following example:

<syntaxhighlight lang=wml>
[unit]
name = _ "William"
type = "Orcish Grunt"
[/unit]
</syntaxhighlight>

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.

Another thing to pay attention to is the fact that strings can also be represented ''without'' double quotes, and are still passed as strings to the parser. In the following example, both attributes '''a''' and '''b''' have the same value.

<syntaxhighlight lang=wml>
[exampletag]
a = "This is recognizable text."
b = This is recognizable text.
c = "This is also " + "recognizable text." # These are concatenated strings. Use the + (plus sign) to concatenate strings. This will result in "This is also recognizable text."
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''', '''b''' and '''c''' attributes.

'''Best practice''': always keep your strings enclosed in double quotes to avoid confusion and have well-defined starting and ending points to them. There are a few exceptions to the rule, but those will be explained in another time.

=== Numerical Values ===
You are also able to represent numeric values, such as integers and decimals, using strings. These can then be used on mathematical operations such as adding, subtracting, multiplying, and dividing (worry not about how this is done, this is going to be covered further into the tutorial). For a string to be considered a numerical value, it might contain one or more digits from 0 to 9 and, additionally, may contain the following (only one of each):

* The negative sign ("-").
* The decimal indicator dot (".").

Any strings not following these rules won't be considered numerical values. See some examples below for a better understanding of acceptable and unacceptable numerical strings:

* "1056" - valid. It only contains digits.
* "305.26" - valid. It only contains digits and the decimal indicator dot.
* "-250.30" - valid. It only contains digits, the decimal indicator dot, and the negative sign.
* "-456" - valid. It only contains digits and the negative sign.

* "1056a" - invalid. It contains a letter.
* "305.2.6" - invalid. It contains two decimal indicator dots.
* "-250.3bananas" - invalid. It contains additional text.
* "-456-5" - invalid. It contains two negative signs.
* "potatoes" - invalid. It does not contain any digit.

'''Best practice''': do not enclose numerical values in double-quotes, unless they are used along with other text, such as in the middle of a string (e.g. they are not alone in their own string, and do not have the objective of strictly representing a numerical value). See the example below.

<syntaxhighlight lang=wml>
[exampletag]
a = "They have captured 6 of our soldiers!" # "6" is part of another string. Enclose in double-quotes.
b = 256 # "256" is alone and strictly represents a numerical value. Do not enclose in double-quotes.
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''' and '''b''' attributes.

=== Lists of Values ===
Some specific attributes require the use of ''value lists''. These are simply values separated by a comma, be them numerical values, strings, and/or translatable strings. See below for an example of this.

<syntaxhighlight lang=wml>
[unit]
recruit = Orcish Grunt, Orcish Assassin # In this case, the strings are not enclosed in double-quotes because they are IDs, and while they CAN be enclosed in double quotes, this isn't recommended. We will talk about this further in the tutorial.
recruit = "Orcish Grunt", "Orcish Assassin" # Also valid.
[/unit]
</syntaxhighlight>

As you can see, Value Lists can be defined as simply as separating strings with a comma. You can also make lists of numbers (and as you may imagine, it is done by separating numbers with a comma).

== The Preprocessor ==
Whenever a WML file is read by Wesnoth, it goes through the '''Preprocessor''' before anything else. As the name suggests (with the ''pre-'' prefix, which means "before"), the Preprocessor goes over the file ''before'' processing.

The Preprocessor doesn't understand WML code, so tags, attributes, and values are none of its concern. The Preprocessor understands a much simpler language built with elements we know as Macros. In the Preprocessor arsenal we can also find '''Preprocessor Directives'''. Worry not about what all this stuff is; this section is designed to serve as an introduction to the Preprocessor and its capabilities, but the Preprocessor itself will be discussed in more depth at its own section.

=== The Inclusion Directives ===
One of the capabilities of the Preprocessor is including other files or directories into our file for ease of access. Using this in combination with the '''binary_path''' tag can help our game to find files it can use (such as map and scenario files). Here's how:

WML for Beginners (Updated): Part 2

2020-09-03T18:43:25Z

Volatus: Removed Excessive use of Bold Text

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. 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:

<syntaxhighlight lang=wml>
[A]
[B]
[D]
[/D]
[/B]

[C]
[/C]
[/A]
</syntaxhighlight>

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 ==
Attributes can have their values be interpreted differently according to what characters they contain. Some specific attributes will also require specific kinds of values. Learn about these different kinds of values and what they are made of.

=== Strings and Concatenation ===
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'''.

=== Simple Text and Translatable Strings ===
Now that you understand strings and what ''concatenation'' is, we can proceed. All attribute values (everything to the right 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 text double-quoted. Take a look at the following example:

<syntaxhighlight lang=wml>
[unit]
name = _ "William"
type = "Orcish Grunt"
[/unit]
</syntaxhighlight>

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.

Another thing to pay attention to is the fact that strings can also be represented ''without'' double quotes, and are still passed as strings to the parser. In the following example, both attributes '''a''' and '''b''' have the same value.

<syntaxhighlight lang=wml>
[exampletag]
a = "This is recognizable text."
b = This is recognizable text.
c = "This is also " + "recognizable text." # These are concatenated strings. Use the + (plus sign) to concatenate strings. This will result in "This is also recognizable text."
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''', '''b''' and '''c''' attributes.

'''Best practice''': always keep your strings enclosed in double quotes to avoid confusion and have well-defined starting and ending points to them. There are a few exceptions to the rule, but those will be explained in another time.

=== Numerical Values ===
You are also able to represent numeric values, such as integers and decimals, using strings. These can then be used on mathematical operations such as adding, subtracting, multiplying, and dividing (worry not about how this is done, this is going to be covered further into the tutorial). For a string to be considered a numerical value, it might contain one or more digits from 0 to 9 and, additionally, may contain the following (only one of each):

* The negative sign ("-").
* The decimal indicator dot (".").

Any strings not following these rules won't be considered numerical values. See some examples below for a better understanding of acceptable and unacceptable numerical strings:

* "1056" - valid. It only contains digits.
* "305.26" - valid. It only contains digits and the decimal indicator dot.
* "-250.30" - valid. It only contains digits, the decimal indicator dot, and the negative sign.
* "-456" - valid. It only contains digits and the negative sign.

* "1056a" - invalid. It contains a letter.
* "305.2.6" - invalid. It contains two decimal indicator dots.
* "-250.3bananas" - invalid. It contains additional text.
* "-456-5" - invalid. It contains two negative signs.
* "potatoes" - invalid. It does not contain any digit.

'''Best practice''': do not enclose numerical values in double-quotes, unless they are used along with other text, such as in the middle of a string (e.g. they are not alone in their own string, and do not have the objective of strictly representing a numerical value). See the example below.

<syntaxhighlight lang=wml>
[exampletag]
a = "They have captured 6 of our soldiers!" # "6" is part of another string. Enclose in double-quotes.
b = 256 # "256" is alone and strictly represents a numerical value. Do not enclose in double-quotes.
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''' and '''b''' attributes.

=== Lists of Values ===
Some specific attributes require the use of ''value lists''. These are simply values separated by a comma, be them numerical values, strings, and/or translatable strings. See below for an example of this.

<syntaxhighlight lang=wml>
[unit]
recruit = Orcish Grunt, Orcish Assassin # In this case, the strings are not enclosed in double-quotes because they are IDs, and while they CAN be enclosed in double quotes, this isn't recommended. We will talk about this further in the tutorial.
recruit = "Orcish Grunt", "Orcish Assassin" # Also valid.
[/unit]
</syntaxhighlight>

As you can see, Value Lists can be defined as simply as separating strings with a comma. You can also make lists of numbers (and as you may imagine, it is done by separating numbers with a comma).

== The Preprocessor ==
Whenever a WML file is read by Wesnoth, it goes through the '''Preprocessor''' before anything else. As the name suggests (with the ''pre-'' prefix, which means "before"), the Preprocessor goes over the file ''before'' processing.

The Preprocessor doesn't understand WML code, so tags, attributes, and values are none of its concern. The Preprocessor understands a much simpler language built with elements we know as Macros. In the Preprocessor arsenal we can also find '''Preprocessor Directives'''. Worry not about what all this stuff is; this section is designed to serve as an introduction to the Preprocessor and its capabilities, but the Preprocessor itself will be discussed in more depth at its own section.

=== The Inclusion Directives ===
One of the capabilities of the Preprocessor is including other files or directories into our file for ease of access. Using this in combination with the '''binary_path''' tag can help our game to find files it can use (such as map and scenario files). Here's how:

WML for Beginners (Updated): Part 1

2020-09-03T18:37:49Z

Volatus: Summary added to the Contents panel.

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use [[WML_for_Beginners_(Updated):_Part_1#NavTab|the navigation tab]] at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

''Best practice statements'': from time to time you will see these bold "best practice" statements. While they are not part of the actual WML syntax and aren't a requirement for WML code to work, they are recommendations designed to ease your life and of those who might read your code in the future (this includes yourself). Thus, while not extremely necessary, they are extremely recommended.

'''Best practice''': always put tags (whether opening or closing) on their own lines for improved readability of code.

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tags.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 1

2020-09-03T18:36:05Z

Volatus: Whitespace Formatting Correction

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use [[WML_for_Beginners_(Updated):_Part_1#NavTab|the navigation tab]] at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

''Best practice statements'': from time to time you will see these bold "best practice" statements. While they are not part of the actual WML syntax and aren't a requirement for WML code to work, they are recommendations designed to ease your life and of those who might read your code in the future (this includes yourself). Thus, while not extremely necessary, they are extremely recommended.

'''Best practice''': always put tags (whether opening or closing) on their own lines for improved readability of code.

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tags.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 1

2020-09-03T18:32:04Z

Volatus: Grammar Correction

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use [[WML_for_Beginners_(Updated):_Part_1#NavTab|the navigation tab]] at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

''Best practice statements'': from time to time you will see these bold "best practice" statements. While they are not part of the actual WML syntax and aren't a requirement for WML code to work, they are recommendations designed to ease your life and of those who might read your code in the future (this includes yourself). Thus, while not extremely necessary, they are extremely recommended.

'''Best practice''': always put tags (whether opening or closing) on their own lines for improved readability of code.

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tags.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 1

2020-09-03T18:32:04Z

Volatus: Grammar Correction

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use [[WML_for_Beginners_(Updated):_Part_1#NavTab|the navigation tab]] at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

''Best practice statements'': from time to time you will see these bold "best practice" statements. While they are not part of the actual WML syntax and aren't a requirement for WML code to work, they are recommendations designed to ease your life and of those who might read your code in the future (this includes yourself). Thus, while not extremely necessary, they are extremely recommended.

'''Best practice''': always put tags (whether opening or closing) on their own lines for improved readability of code.

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tags.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 2

2020-07-06T16:39:55Z

Volatus:

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. 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:

<syntaxhighlight lang=wml>
[A]
[B]
[D]
[/D]
[/B]

[C]
[/C]
[/A]
</syntaxhighlight>

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 ==
Attributes can have their values be interpreted differently according to what characters they contain. Some specific attributes will also require specific kinds of values. Learn about these different kinds of values and what they are made of.

=== Strings and Concatenation ===
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'''.

=== Simple Text and Translatable Strings ===
Now that you understand strings and what ''concatenation'' is, we can proceed. All attribute values (everything to the right 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 text double-quoted. Take a look at the following example:

<syntaxhighlight lang=wml>
[unit]
name = _ "William"
type = "Orcish Grunt"
[/unit]
</syntaxhighlight>

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.

Another thing to pay attention to is the fact that strings can also be represented ''without'' double quotes, and are still passed as strings to the parser. In the following example, both attributes '''a''' and '''b''' have the same value.

<syntaxhighlight lang=wml>
[exampletag]
a = "This is recognizable text."
b = This is recognizable text.
c = "This is also " + "recognizable text." # These are concatenated strings. Use the + (plus sign) to concatenate strings. This will result in "This is also recognizable text."
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''', '''b''' and '''c''' attributes.

'''Best practice''': always keep your strings enclosed in double quotes to avoid confusion and have well-defined starting and ending points to them. There are a few exceptions to the rule, but those will be explained in another time.

=== Numerical Values ===
You are also able to represent numeric values, such as integers and decimals, using strings. These can then be used on mathematical operations such as adding, subtracting, multiplying, and dividing (worry not about how this is done, this is going to be covered further into the tutorial). For a string to be considered a numerical value, it might contain one or more digits from 0 to 9 and, additionally, may contain the following (only one of each):

* The negative sign ("-").
* The decimal indicator dot (".").

Any strings not following these rules won't be considered numerical values. See some examples below for a better understanding of acceptable and unacceptable numerical strings:

* "1056" - valid. It only contains digits.
* "305.26" - valid. It only contains digits and the decimal indicator dot.
* "-250.30" - valid. It only contains digits, the decimal indicator dot, and the negative sign.
* "-456" - valid. It only contains digits and the negative sign.

* "1056a" - invalid. It contains a letter.
* "305.2.6" - invalid. It contains two decimal indicator dots.
* "-250.3bananas" - invalid. It contains additional text.
* "-456-5" - invalid. It contains two negative signs.
* "potatoes" - invalid. It does not contain any digit.

'''Best practice''': do not enclose numerical values in double-quotes, unless they are used along with other text, such as in the middle of a string (e.g. they are not alone in their own string, and do not have the objective of strictly representing a numerical value). See the example below.

<syntaxhighlight lang=wml>
[exampletag]
a = "They have captured 6 of our soldiers!" # "6" is part of another string. Enclose in double-quotes.
b = 256 # "256" is alone and strictly represents a numerical value. Do not enclose in double-quotes.
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''' and '''b''' attributes.

=== Lists of Values ===
Some specific attributes require the use of ''value lists''. These are simply values separated by a comma, be them numerical values, strings, and/or translatable strings. See below for an example of this.

<syntaxhighlight lang=wml>
[unit]
recruit = Orcish Grunt, Orcish Assassin # In this case, the strings are not enclosed in double-quotes because they are IDs, and while they CAN be enclosed in double quotes, this isn't recommended. We will talk about this further in the tutorial.
recruit = "Orcish Grunt", "Orcish Assassin" # Also valid.
[/unit]
</syntaxhighlight>

As you can see, Value Lists can be defined as simply as separating strings with a comma. You can also make lists of numbers (and as you may imagine, it is done by separating numbers with a comma).

== The Preprocessor ==
Whenever a WML file is read by Wesnoth, it goes through the '''Preprocessor''' before anything else. As the name suggests (with the ''pre-'' prefix, which means "before"), the Preprocessor goes over the file ''before'' processing.

The Preprocessor doesn't understand WML code, so tags, attributes, and values are none of its concern. The Preprocessor understands a much simpler language built with elements we know as Macros. In the Preprocessor arsenal we can also find '''Preprocessor Directives'''. Worry not about what all this stuff is; this section is designed to serve as an introduction to the Preprocessor and its capabilities, but the Preprocessor itself will be discussed in more depth at its own section.

=== The Inclusion Directives ===
One of the capabilities of the Preprocessor is including other files or directories into our file for ease of access. Using this in combination with the '''binary_path''' tag can help our game to find files it can use (such as map and scenario files). Here's how:

WML for Beginners (Updated): Part 2

2020-06-23T11:13:36Z

Volatus:

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. 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:

<syntaxhighlight lang=wml>
[A]
[B]
[D]
[/D]
[/B]

[C]
[/C]
[/A]
</syntaxhighlight>

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 ==
Attributes can have their values be interpreted differently according to what characters they contain. Some specific attributes will also require specific kinds of values. Learn about these different kinds of values and what they are made of.

=== Strings and Concatenation ===
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'''.

=== Simple Text and Translatable Strings ===
Now that you understand strings and what ''concatenation'' is, we can proceed. All attribute values (everything to the right 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 text double-quoted. Take a look at the following example:

<syntaxhighlight lang=wml>
[unit]
name = _ "William"
type = "Orcish Grunt"
[/unit]
</syntaxhighlight>

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.

Another thing to pay attention to is the fact that strings can also be represented ''without'' double quotes, and are still passed as strings to the parser. In the following example, both attributes '''a''' and '''b''' have the same value.

<syntaxhighlight lang=wml>
[exampletag]
a = "This is recognizable text."
b = This is recognizable text.
c = "This is also " + "recognizable text." # These are concatenated strings. Use the + (plus sign) to concatenate strings. This will result in "This is also recognizable text."
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''', '''b''' and '''c''' attributes.

'''Best practice''': always keep your strings enclosed in double quotes to avoid confusion and have well-defined starting and ending points to them. There are a few exceptions to the rule, but those will be explained in another time.

=== Numerical Values ===
You are also able to represent numeric values, such as integers and decimals, using strings. These can then be used on mathematical operations such as adding, subtracting, multiplying, and dividing (worry not about how this is done, this is going to be covered further into the tutorial). For a string to be considered a numerical value, it might contain one or more digits from 0 to 9 and, additionally, may contain the following (only one of each):

* The negative sign ("-").
* The decimal indicator dot (".").

Any strings not following these rules won't be considered numerical values. See some examples below for a better understanding of acceptable and unacceptable numerical strings:

* "1056" - valid. It only contains digits.
* "305.26" - valid. It only contains digits and the decimal indicator dot.
* "-250.30" - valid. It only contains digits, the decimal indicator dot, and the negative sign.
* "-456" - valid. It only contains digits and the negative sign.

* "1056a" - invalid. It contains a letter.
* "305.2.6" - invalid. It contains two decimal indicator dots.
* "-250.3bananas" - invalid. It contains additional text.
* "-456-5" - invalid. It contains two negative signs.
* "potatoes" - invalid. It does not contain any digit.

'''Best practice''': do not enclose numerical values in double-quotes, unless they are used along with other text, such as in the middle of a string (e.g. they are not alone in their own string, and do not have the objective of strictly representing a numerical value). See the example below.

<syntaxhighlight lang=wml>
[exampletag]
a = "They have captured 6 of our soldiers!" # "6" is part of another string. Enclose in double-quotes.
b = 256 # "256" is alone and strictly represents a numerical value. Do not enclose in double-quotes.
[/exampletag]
</syntaxhighlight>
'''Note''': The above example is not valid WML code and was used for demonstration purposes only. '''exampletag''' is not a valid tag and nor are the '''a''' and '''b''' attributes.

=== Lists of Values ===
Some specific attributes require the use of ''value lists''. These are simply values separated by a comma, be them numerical values, strings, and/or translatable strings. See below for an example of this.

<syntaxhighlight lang=wml>
[unit]
recruit = Orcish Grunt, Orcish Assassin # In this case, the strings are not enclosed in double-quotes because they are IDs. We will talk about this further in the tutorial.
[/unit]
</syntaxhighlight>

WML for Beginners (Updated): Part 2

2020-06-23T02:29:37Z

Volatus:

WML for Beginners (Updated): Part 1

2020-06-23T02:18:18Z

Volatus:

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use [[WML_for_Beginners_(Updated):_Part_1#NavTab|the navigation tab]] at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

''Best practice statements'': from time to time you will see these bold "best practice" statements. While they are not part of the actual WML syntax and aren't a requirement for WML code to work, they are recommendations designed to ease your life and of those who might read your code in the future (this includes yourself). Thus, while not extremely necessary, they are extremely recommended.

'''Best practice''': always put tags (whether opening or closing) on their own lines for improved readability of code.

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tag.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 2

2020-06-23T02:14:34Z

Volatus:

WML for Beginners (Updated): Part 2

2020-06-23T02:09:17Z

Volatus:

WML for Beginners (Updated): Part 2

2020-06-20T05:31:49Z

Volatus:

WML for Beginners (Updated): Part 2

2020-06-19T17:52:26Z

Volatus:

WML for Beginners (Updated): Part 2

2020-06-19T15:26:58Z

Volatus: Created page with "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 th..."

WML for Beginners (Updated): Part 1

2020-06-19T13:36:41Z

Volatus: Added positional marker for the Navigation Tab and linked it at the top of the page.

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use [[WML_for_Beginners_(Updated):_Part_1#NavTab|the navigation tab]] at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). It is a good practice to always put tags (whether opening or closing) on their own lines. Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tag.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 1

2020-06-19T03:48:56Z

Volatus: Quick edit on the introduction text

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use the navigation tab at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). It is a good practice to always put tags (whether opening or closing) on their own lines. Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tag.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

CampaignWML

2020-06-19T00:09:22Z

Volatus: /* The [campaign] Tag */

{{WML Tags}}



This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.

==The [campaign] Tag==

The following keys and tags are recognized in '''[campaign]''' tags:
* '''id''': the internal campaign identifier used to classify saved games
* '''icon''': the image displayed in the campaign selection menu
* '''name''': (translatable) name displayed in the campaign selection menu
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
* '''description_alignment''': {{DevFeature1.13|3}} The text alignment of the description. Choose between "left" (default), "center", or "right".
* '''type''': campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".
* '''define'''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''CAMPAIGN_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. Currently supported extra_defines are:
<ul>
;ENABLE_ARMAGEDDON_DRAKE
:allows the advancement ''Inferno Drake'' -> ''Armageddon Drake''
;ENABLE_DWARVISH_ARCANISTER
:allows the advancement ''Dwarvish Runemaster'' -> ''Dwarvish Arcanister''
;ENABLE_DWARVISH_RUNESMITH
:allows the advancement ''Dwarvish Fighter'' -> ''Dwarvish Runesmith''
;DISABLE_GRAND_MARSHAL
:disallows the advancement ''General'' -> ''Grand Marshal''
;ENABLE_ANCIENT_LICH
:allows the advancement ''Lich'' -> ''Ancient Lich''
;ENABLE_DEATH_KNIGHT
:allows the advancement ''Revenant'' -> ''Death Knight'
;ENABLE_TROLL_SHAMAN
:allows the advancement ''Troll Whelp'' -> ''Troll Shaman''
;ENABLE_WOLF_ADVANCEMENT
:allows the advancements ''Wolf'' -> ''Great Wolf'' -> ''Direwolf''
;ENABLE_NIGHTBLADE {{DevFeature1.13|0}}
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''
;ENABLE_PARAGON {{DevFeature1.15|1}}
:allows the advancement ''Dune Blademaster'' -> ''Dune Paragon''
;ENABLE_WOSE_SHAMAN {{DevFeature1.15|1}}
:allows the advancement ''Wose'' -> ''Wose Shaman''
</ul>
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg| Macro Reference]) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=.
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=
* '''[difficulty]''': {{DevFeature1.13|2}} specifies a single campaign difficulty. The following keys are accepted:
** '''define''': the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old ''difficulties'' list.
** '''image''': the image to display for this difficulty in the selection menu
** '''label''': a flavor label describing this difficulty. Displayed second after the image
** '''description''': a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.
** '''default''': whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.
** '''auto_markup''': {{DevFeature1.15|0}} By default, the description is shown in small, gray text within parentheses. Setting '''auto_markup=no''' disables these, so no markup will be applied implicitly. Any markup in '''description''' will be honored regardless of this setting.
* '''allow_difficulty_change''': Allows difficulty switching during an ongoing campaign. Default:yes
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]
* '''[options]''': {{DevFeature1.13|1}} Allows configuration options to be displayed to the user, see [[OptionWML]]
* '''rank''': a number that determines the order of campaigns in the campaign selection menu. Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.) {{DevFeature1.14|6}} a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.
* '''year''': shortcut for specifying both '''start_year''' and '''end_year''', for campaigns that happen inside a single calendar year. Ignored if '''start_year''' is given.
* '''[about]''': inserts your own credits into the game's list of credits. See below for syntax.
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500.
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.

The following keys are additionally recognized in multiplayer:
* '''min_players''': Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.
* '''max_players''': Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either '''min_players''' or 2, whichever is higher.
* '''allow_era_choice''': Whether to allow era selection (when set to ''yes'') or hide it and use a default one when creating a game (when set to ''no''). Defaults to ''yes''.
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.

== Campaign credits ==

The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of '''[about]''' tags inside a '''[campaign]''' tag. The '''[about]''' tag has the following keys:
* '''title''': (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
* '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names
* '''[entry]''': Contains information about a single contributor. Only the ''name'' key will be used in-game, the other three keys are for display on the [[Credits]] page ('''note:''' the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)
** '''name''': The name of the contributor
** '''comment''': Optional short note about what that person did
** '''email''': Optional email address
** '''wikiuser''': Optional, the user name on the wiki

== See Also ==

* [[PreprocessorRef]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[PblWML]]

[[Category: WML Reference]]

WML for Beginners (Updated)

2020-06-17T23:39:09Z

Volatus:

WML for Beginners (Updated): Part 1

2020-06-17T17:47:58Z

Volatus:

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use the index at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). It is a good practice to always put tags (whether opening or closing) on their own lines. Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example uses code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tag.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 1

2020-06-17T17:25:11Z

Volatus: Changed "code fraction" to "example" in Comments

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use the index at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). It is a good practice to always put tags (whether opening or closing) on their own lines. Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following example extracts code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tag.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated): Part 1

2020-06-17T16:50:30Z

Volatus: Created the first version of the page and its contents.

In the first part of this tutorial series, we are going to talk about the basics of how WML code works and learn fundamental aspects of the language. Use the index at the end of the page to go between pages and the index.

== What is WML? ==
In order to create add-ons, including campaigns, custom units, and even collections of maps with advanced scenario features (such as dialogues and custom functionality), you will need to, at least, know the fundamentals of WML. In case you are wondering, WML stands for ''Wesnoth Markup Language''. For more information on what Markup Languages are, please go to [https://en.wikipedia.org/wiki/Markup_language this link].

WML is then used inside Configuration Files (files with the ''.cfg'' extension) which is then read by Wesnoth in order to create the wonderful singleplayer campaigns available to you when you download the game or even the incredible single-map scenarios with custom functionality which you can play by yourself or with friends.

== Tags, Attributes and Values ==
Tags, attributes, and values define the base structure of WML and when used together compose elemental aspects of code files in Wesnoth Markup Language. The following sections describe each of these in more detail as well as their relation to each other (and more concepts).

=== Tags ===
Tags are used to define things in WML. They tell Wesnoth you are willing to work with specific areas of the game and also define them. They usually (probably around 253.6% of the time) appear around ''attributes'' and ''values'' (see below). There are two types of tags: ''opening tags'' and ''closing tags''. With very intuitive names, they describe, respectively, when you want to '' start'' working with some specific aspect and when you want to ''stop'' working with it. To indicate a tag, simply enclose a name (lower case only) in square brackets (<nowiki>"[" and "]"</nowiki>). Opening and closing tags are written the exact same way with the exception that closing tags always have a forward-slash ("/") immediately after the opening square bracket (<nowiki>"["</nowiki>). It is a good practice to always put tags (whether opening or closing) on their own lines. Here is an example of the '''unit''' tag:

<syntaxhighlight lang=wml>
[unit]
[/unit]
</syntaxhighlight>

=== Attributes and Values ===
Using tags you can tell the game ''which'' area of it you want to work with. Using attributes and values, you can tell the game ''how'' you want to do it. Suppose the following situation: a friend comes to you and says "Buy". You will be confused because you don't know ''what'' to buy, ''when'' or ''where''. Now, if he says "Could you buy me chocolate at that store right there?" you will know exactly what to buy and exactly where to do it. Note, however, he did not tell you ''when'' to buy it, but because of context, you can tell he wants it soon.

When you give Wesnoth ''empty tags'' such as our last example with the '''unit''' tag, it's the same as saying "Buy" to the code. In there, you tell the game you want to have a unit. You don't tell it, however, which unit you want, where it is, etc. He knows what you want it to do, but has no further information about it. Using attributes and values you can specify how it should be done and cease the game's confusion. Attributes and tags are always used together and have a very simple syntax:

attribute_name = value

Where ''attribute_name'' determines the name of the attribute and ''value'' which value you want to give it. This is very simple but may have sounded confusing. Let's take a look at our previous example with the unspecified '''unit''' tag and make it less confusing to the code:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, we now specify that the unit's ''type'' attribute has the value ''Orcish Grunt''. Attributes and values are always used together, and always come enclosed in tags as the previous example shows.

'''For advanced readers:''' keep in mind attributes are ''not'' the same as variables, forgetting this is a very common mistake. Variables are explained further in this tutorial.

== Comments ==
To be simple, comments are the part of the code which is ignored by the game. You may be wondering how ignored code can be of any use, right? Do not worry, I can explain. As the name suggests, comments are... well, comments! They help describe specific sections of the code or explain the reason behind certain implementations, not for the game, but for other people and yourself! They are also an elegant way to organize sections of your code. The following code fraction extracts code previously seen in this page but features comments:

<syntaxhighlight lang=wml>
# This tag is placing an Orcish Grunt in the scenario.
[unit]
type = Orcish Grunt
[/unit]
</syntaxhighlight>

As you can see, a comment's syntax is very simple. You only need to use a hashtag ("#") and from the starting hashtag to the end of the line, all will be considered a comment. Having that in mind, you can also insert comments in the middle of code, take a look at this example:

<syntaxhighlight lang=wml>
[unit]
type = Orcish Grunt # The name of this Grunt is Bob.
[/unit]
</syntaxhighlight>

== Summary ==
:- ''tags'' define specific areas for the game to work with.
:- ''attributes and values'' specify how to work with the area mentioned in their enclosing tag.
:- ''comments'' can be used to better describe regions of the code, embellish it or simply organize different sections demarking them with titles, for example.

== Navigation Tab ==
* [[WML_for_Beginners_(Updated) | The Tutorial's Index]]

WML for Beginners (Updated)

2020-06-17T15:10:33Z

Volatus: /* The Tutorial's Pages */ - Part 1 Link Correction

Welcome to the WML tutorial for Beginners! This is an update on the old [[WML_for_Complete_Beginners | WML for Complete Beginners]] tutorial, which contains deprecated elements usage and unoptimized/unwritten parts. Having read the older version of the WML tutorial is not a requirement for reading and understanding this one, however.

Still, this tutorial series assumes you have done the reading of the following pages:
* [[EditingWesnoth]] - explains the '''game data''' and '''user data''' directories' functionality within Wesnoth.
* [[AddonStructure]] - explains an addon's basic folder structure while giving a hint about '''_main.cfg''' (which will be discussed within this tutorial series with more detail).

== The Tutorial's Pages ==
* [[WML_for_Beginners_(Updated):_Part_1 | WML for Beginners (Updated): Part 1]]

WML for Beginners (Updated)

2020-06-17T15:09:55Z

Volatus: /* The Tutorial's Pages */ - Added Part 1 Mention

Welcome to the WML tutorial for Beginners! This is an update on the old [[WML_for_Complete_Beginners | WML for Complete Beginners]] tutorial, which contains deprecated elements usage and unoptimized/unwritten parts. Having read the older version of the WML tutorial is not a requirement for reading and understanding this one, however.

Still, this tutorial series assumes you have done the reading of the following pages:
* [[EditingWesnoth]] - explains the '''game data''' and '''user data''' directories' functionality within Wesnoth.
* [[AddonStructure]] - explains an addon's basic folder structure while giving a hint about '''_main.cfg''' (which will be discussed within this tutorial series with more detail).

== The Tutorial's Pages ==
* [[WML_for_Beginners_(Updated) | WML for Beginners (Updated): Part 1]]

WML for Beginners (Updated)

2020-06-17T15:00:07Z

Volatus: Created the first version of the page and prepared terrain for the rest of the tutorial series.

Welcome to the WML tutorial for Beginners! This is an update on the old [[WML_for_Complete_Beginners | WML for Complete Beginners]] tutorial, which contains deprecated elements usage and unoptimized/unwritten parts. Having read the older version of the WML tutorial is not a requirement for reading and understanding this one, however.

Still, this tutorial series assumes you have done the reading of the following pages:
* [[EditingWesnoth]] - explains the '''game data''' and '''user data''' directories' functionality within Wesnoth.
* [[AddonStructure]] - explains an addon's basic folder structure while giving a hint about '''_main.cfg''' (which will be discussed within this tutorial series with more detail).

== The Tutorial's Pages ==

WML for Complete Beginners: Chapter 3

2020-06-16T16:31:13Z

Volatus: /* The Preprocessor */

==Chapter 3: The _main.cfg==

Note: this page borrows heavily from the [[BuildingCampaignsTheCampaignFile]] page.

So we've created a campaign folder, but as of yet the game doesn't even know this new folder exists. In order for the game to find the folder, we have to create a special file called "_main.cfg" that tells the game where to find all of your campaign's data. Without this file, the game won't be able to find your campaign when it starts up, and consequently you won't be able to play your campaign.

So let's get started creating a "_main.cfg" file so that the game can find your campaign.

Navigate to your campaign folder, if you aren't already there. Now create a new text file and name it "_main.cfg" (just like that, including the underscore but without the quotes). Make sure you select a save-type of 'all files' and not 'text document (.txt)' for this file. If you selected 'text document (.txt)' you will actually save a file named "_main.cfg.txt" which will not be recognized by Wesnoth. Now you have created a file called "_main.cfg", but we're not done yet. Right now the file is empty, so the game still won't be able to locate your campaign yet. But fear not, all you have to do is write some specific WML inside the "_main.cfg" file and the game will be able to find your campaign just fine.

===The Text Domain===

Open the "_main.cfg" file in your text editor if you haven't already. and add the following tagset:

[textdomain]
[/textdomain]

This tagset which specifies where the game should look for translations to the strings in the campaign (at this stage you probably won't have any translations, but it's a common practice to add a text domain just in case you get translations later on). The textdomain tag specifies a name for the textdomain, which is what is used in the [campaign] tag, and is used in campaign scenarios to connect the strings with translations.

Inside the [textdomain] tag, include the attributes '''name''' and '''path''' (don't assign values to them just yet, we'll do that in a moment):

[textdomain]
name=
path=
[/textdomain]

*'''The "name" Attribute'''
The attribute '''name''' specifies the name of the text domain you are creating. The textdomain name should be unique, and start with 'wesnoth-', to ensure that it does not conflict with other textdomains that might be specified on a given system. Let's name our text domain "my_first_campaign". Don't forget to start it with "wesnoth-". Now the contents of your _main.cfg file should look exactly like this:

[textdomain]
name="wesnoth-my_first_campaign"
path=
[/textdomain]

*'''The "path" Attribute'''
The attribute '''path''' specifies a path to the directory where the compiled translation files will be stored. This should be a file inside the campaign directory. Right now our translations folder is empty, but if you ever get translations for your campaign, this is the folder in which they would go. Let's assign the "translations" folder directory path, which should be "data/add-ons/my_first_campaign/translations", to this attribute. Your _main.cfg should now look like this:

[textdomain]
name="wesnoth-my_first_campaign"
path="data/add-ons/my_first_campaign/translations"
[/textdomain]

===Defining the Campaign===

And now we're going to add the [campaign] tagset. Yes, it's our old friend, the [campaign] tagset, from Chapter 1.

[campaign]
[/campaign]

Next, inside the [campaign] tagset, include the following line:

#textdomain wesnoth-my_first_campaign

This tells the game that the text strings in this file belong to the text domain you just defined above

Next we need to give the attributes '''id''','''name''','''abbrev''','''icon''','''image''','''first_scenario''','''description''','''difficulties''', and '''difficulty_descriptions'''. Don't assign any values to these attributes yet, we'll do that in a moment. For now, just make sure that you have all of these attributes in between the campaign tags, like so (the exact order of the attributes doesn't matter, but it is recommended that you follow the order given below to make things easier for yourself when following this tutorial):

[campaign]
#textdomain wesnoth-my_first_campaign
id=
name=
abbrev=
define=
icon=
image=
first_scenario=
description=
difficulties=
difficulty_descriptions=
[/campaign]

Now let's go over the attributes one by one and give them their values. I'll give you a specific value to assign to each attribute, and then I'll explain why we use that particular value.

*'''The "id" Attribute'''
:The unique identifier of your campaign. The value of an "id" attribute can only contain lowercase alphanumeric characters and underscores. We are going to give this attribute the value "my_first_campaign", like so:
id=my_first_campaign

*'''The "name" Attribute'''
:The name of your campaign. This translatable string is the name that will show up in the in-game campaign menu, where you can select which campaign you want to play. Let's give it the value "My First Campaign". Since we want this string to be translatable, don't forget to include the translation mark (the underscore) in front of the first double quote.
name= _ "My First Campaign"

*'''The "abbrev" Attribute'''
:This attribute defines a campaign abbreviation that will be used as a prefix for the names of save files from that campaign. It should generally consist of the acronym of the campaign's name (i.e., the first letter of each of the words in the campaign's name, capitalized).

*'''The "define" Attribute'''
This attribute creates a key that lets the game know when a user has selected to play a scenario from your campaign.

*'''The "icon" Attribute'''
The image that will be displayed next to the name of your campaign in the in-game campaign selection menu. Since we need the game to locate a specific file, we [...]

*'''The "image" Attribute'''
This defines the image that will appear under your campaign's description when your campaign is selected in the in-game campaign selection menu.

*'''The "first_scenario" Attribute'''

*'''The "description" Attribute'''

*'''The "difficulties" Attribute'''

*'''The "difficulty_descriptions" Attribute'''

[campaign]
#textdomain wesnoth-my_first_campaign
id=my_first_campaign
name= _ "My First Campaign"
abbrev= _ "MFC"
define=CAMPAIGN_MY_FIRST_CAMPAIGN
icon=
image=
first_scenario=my_first_scenario
description= _ "This is my first campaign."
difficulties=EASY
difficulty_descriptions=
[/campaign]

===The Preprocessor===
Before any WML file is read by Wesnoth, it goes through the preprocessor. The preprocessor will prepare the file to be read by the game. It doesn't actually recognize WML. In fact, it ignores it. Instead, it reads the '''preprocessor directives''', used to create and use [https://www.wesnoth.org/macro-reference.xhtml macros]. Macros are used to reduce the repetition of information just like pronouns do with names and identifiers in the English language. Don't worry about macros now, we will talk about them later.

====Preprocessor Directives====
As mentioned above, the Preprocessor doesn't recognize WML code. It only recognizes '''preprocessor directives'''. While apparently similar to comments, they have a much greater impact on the code. Not only can they define and use macros, they can also be used to apply a condition for the reading of a part of the file by Wesnoth (making a part of the code be read only if you are in the Hard difficulty, for example). Using preprocessor directives can create many things, but don't worry about it yet. We will talk about it in the future.

====The Binary Path====
The binary path is used to tell the game to include a certain directory in the userdata folder whenever it searches for a file. For instance, if you had a custom image in your campaign called "my_face.png", whenever the game finds a reference to that file in a scenario (e.g., you want to display that image at one of the story screens in a scenario), it will first search the core gamedata directories, then it will search any folders included in the binary path. If it cannot find the file in either the gamedata directory or in any of the directories specified in the binary path, then it will give you an error.

You will only need to include a binary path if your campaign contains custom images, sounds or music that is not included in mainline Wesnoth. If you do not have any custom images, sounds or music, then you should not include a binary path. Since we will be including some custom images in our campaign, we are going to need to include a binary path.

To create a binary path, use the following syntax:
[binary_path]
path=data/add-ons/my_first_campaign
[/binary_path]
This tells the game to search the specified userdata directory whenever it cannot locate a certain file in the gamedata directory. Note that the value of the "path" key must always begin with "data/add-ons/" followed by the name of your campaign folder.

====Directory Inclusion====
(The final _main.cfg should end up looking something like this:)

[textdomain]
name="wesnoth-my_first_campaign"
path="data/add-ons/my_first_campaign/translations"
[/textdomain]

#textdomain wesnoth-my_first_campaign

[campaign]
#wesnoth-My_First_Campaign
id=my_first_campaign
name= _ "My First Campaign"
abbrev= _ "MFC"
define=CAMPAIGN_MY_FIRST_CAMPAIGN
#need icon and image (take from core files, don't include external files for sake of simplicity)
icon=
image=
first_scenario=my_first_scenario
description= _ "This is my first campaign."
difficulties=EASY
difficulty_descriptions={MENU_IMG_TXT2 units/undead/shadow-s-attack-4.png _"Easy" _""}
[/campaign]

#ifdef CAMPAIGN_MY_FIRST_CAMPAIGN

[binary_path]
path=data/add-ons/my_first_campaign
[/binary_path]

{~add-ons/my_first_campaign/macros}
{~add-ons/my_first_campaign/utils}

{~add-ons/my_first_campaign/scenarios}
#endif

(note: no units yet, save that for the adding custom units section)

Next Chapter:
[[WML for Complete Beginners: Chapter 4]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]