The Battle for Wesnoth Wiki - User contributions [en]

WML for Complete Beginners: Chapter 1

2015-03-28T18:05:50Z

Artisticdude: Formatting revisions

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a "[http://en.wikipedia.org/wiki/Markup_language markup language]." This means that the syntax of the entire language consists of two fundamental elements: '''tags''' and '''attributes'''.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here.

:Before we move on to the next section, let's review the points we've learned in this section about tags:
::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you just say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what to do generally (like telling your friend to "go"), but without attributes to specify ''exactly'' what to do (like telling your friend where and when to go, and what to do when he gets there), the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

Continue to [[WML for Complete Beginners: Chapter 2]]

[[Category:WML_for_Complete_Beginners]]

Armour Tutorial

2013-10-21T19:00:54Z

Artisticdude: /* Dark tones */

By [http://forums.wesnoth.org/memberlist.php?mode=viewprofile&u=110981 LordBob] ([http://forums.wesnoth.org/viewtopic.php?f=18&t=23783 original thread])

After receiving compliments on the loyalists' armour and hearing a few of you wish they could do the same, I decided I'd try and help. This tutorial will guide you through the basic shading of metalic armour.

First things first, it's best to state the obvious here a now: there's no magical trick, only a keen eye and lots of hard work. Not only must you think weight and shape, but also movement: the viewer must not feel that parts of your armour obstruct the character's moves. Reference pictures of actual armour ('''not''' pictures of typical fantasy computer-game armour, but rather pictures of physical armour that has actually been used at some point in human history) will help design believable sets of armour. If you have the opportunity, visit a place where you can sketch from real armour. Sketch in odd angles, with special attention to light and shapes. Reference, reference, reference!

Now, the shading. I'll develop the tutorial through 3 examples, each one a different metal.

==Dark tones==

*'''Step one, pick the base colour of your metal.''' Greys for steel and iron, browns for bronze or gold. The colour you chose should reflect the overall tone of your finished armour. One this is done, pick your light source and begin the thinking.

*'''Step two, the dark tones.''' I use a brush of fixed size and variable opacity, with low transparency if you're heavy-handed. With Photoshop, I use the "Multiply" fusion mode and pick the base colour of my metal. In midtones, giving several light strokes is better than a single strong stroke, since it will give texture and a gradient effect to your metal.

*'''Step three, darker tones.''' For this step, I use a similar brush of smaller size and give heavier strokes. This time, it's better to apply large patches. What you'll have to bear in mind when shading is that metal doesn't reflect light like cloth or leather. Contrasts on metal are high, whether it be light or shadows. In my example, step #2 is far from enough. Shadowed areas develop darker patches, caused by the obstruction of light by an arm, a shield, etc. Reflections of nearby objects will also manifest as darker patches. Step #3 is better as far as contrast goes, but we're not done yet.

*'''Step four, counter-reflection.''' This step is the key to metal shading. When shading, you must be aware that metal doesn't need a direct lightsource to reflect light. Reflections on a nearby wall, shield, and light diffused by the sky are enough to cause the counter-reflection. For this step, I keep the smaller brush and select the "Screen" fusion mode. You'll have to imagine where your plausible secondary lightsource would be located. Every surface can have counter-reflections, it gives them volume and their metallic aspect.

http://www.wesnoth.org/wiki-images/tutorial/lordbob-armor-tutorial/Armour-tutorial-1.png

Now your dark tones are done, it's time to give life to your metal by adding the light tones to the dark tones we've already done above.

==Light Tones==

*'''Step five - diffuse light:''' I pick a brush of fixed size and pressure-sensitive opacity, this time with the fusion mode Screen. The colour I pick in this step is the base colour of my metal. The aim is to obtain a diffused light in places not in shadow.

*'''Step six - strong light:''' more screening with the same bush and colour. On bent metal, light with be more intense as the surface comes closer to the light source. The key here is to have a good mental image of your armour, in order to identify those places where direct light is strongest.

*'''Step seven - pinpoint reflections:''' step six is already convincing enough, but not all the metal in a drawing receives the same intensity of light. In order to include this in your picture, spots on which you want to attract the viewer's eye will receive pin-size dots of white. I do this with a smaller brush, still in Screen mode, using this time a light grey tone so that the light tends toward white. This is important with tainted metals such as copper, brass, bronze... If you feel confortable enough, you can also use a basic brush and apply pure white in Normal mode. Note that not all mettalic spots ought to receive those white dots : your image would be too shiny. You have to use them as a track that guides the viewer to where you want his attention.

*'''Step eight - colour overlay:''' this step is what truly gives life to your metal and blends it in the whole picture. Reflections on metal are tinted by the nature of the light and the surfaces on which the light reflects. I use a fixed size, pressure-sensitive brush in Overlay mode with very low transparency (25-30%). The colour I apply depends on the nature of the light: bluish for the sky, orange for torchlight or a campfire, the colour of your character's clothes where they reflect light, brown next to leather or a wooden shield...Keep in mind that with reflections, the effect will only be strong close to the reflecting surface, whereas intense light sources such as the sky or fire will diffuse their tint everywhere. This step is up to your imagination, just don't overdo it. And keep that transparency low! Oversaturated reflections will only remove credibility from your painstakingly shaded metal.

http://www.wesnoth.org/wiki-images/tutorial/lordbob-armor-tutorial/Armour-tutorial-2.png

'''''To be continued...'''''

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

Create Art

2013-10-21T18:58:30Z

Artisticdude: /* General Art and Computer Graphics */

{| style="float:right; margin-left:1em;"
|__TOC__
|}

Graphic artists working on artwork intended for mainline Wesnoth usually meet on the [http://forums.wesnoth.org/viewforum.php?f=9 Art Contributions forum] or on the [http://forums.wesnoth.org/viewforum.php?f=18 restricted Art Development forum] ("restricted" meaning that only those users with special permissions - such as art contributors and developers - can post there). The former is a great place to post and discuss new and current mainline Wesnoth art and graphics, and the latter to see what the art development team is working on. Artists working on graphics for [[Glossary|UMC]] add-ons meet in the [http://forums.wesnoth.org/viewforum.php?f=23 Art Workshop forum].

Unit and terrain art is stored in the lossless ''Portable Network Graphics'' (PNG) format. Each frame of a unit animation, and each variation of a terrain is stored as a separate .png file in ''data/core/images'' under the [[EditingWesnoth#Where_is_my_game_data_directory.3F|main data directory]] of the game, and generally these files will be 72 x 72 pixels (the size of Wesnoth's basic hexagonal tile) with an alpha channel (a part of the file that indicates how transparent each pixel is). When creating your own images, you can test them without overwriting any game data by putting them in your [[EditingWesnoth#Where_is_my_user_data_directory.3F|user data directory]]. The game also supports JPEG images, although these are better suited for story art.

To edit these graphics, you'll need some program capable of creating PNG's - some of the programs in the following list are free, open-source software, and will do the job nicely: [[Art Programs]]

If you need some inspiration, we have a (no longer maintained) [[GraphicLibrary|Graphics Library]] which collects art posted on the forum. You can use this for ideas, and as a scrap heap for different parts of unit images (a technique described [[Give Your Hero A Personality|here]]).

== Art Tutorials ==

These are a work-in-progress, and describe both how to make art fit into Wesnoth's style, as well as giving some considerable tips on drawing in general. Especially useful is the [[External Tutorials]] page which lists a large number of art tutorials available on the web.

=== General Art and Computer Graphics ===
* [[Using the Levels Adjustment]] - How to make scanned pencil drawings ''not'' look washed out.
* [[Extending dynamic range]] - The Grooviest (so far) tutorial about extending the dynamic range of images and how this technique can be used to make better scans of pencil drawings.
* [[Scanning with camera]] - How to transfer real-life art to computer using a digital camera instead of a scanner.
* [[Art Supplies]] - What physical items you need to do larger cell-shaded art like that of Jetrel/Jormungadr/et al.
* [[Inking With Pencils|Computer Inking a Sketch]] - Info from Jason Lutes on his portrait workflow.
* [[Scaling Digital Images]] - How to properly resize an image on a computer.
* [[How to Shade]] - An attempt at tackling a very complicated topic.
* [[Cartography for Wesnoth|How to make Wesnoth-style Maps ]] - Kestenvarn's tricks of the trade.
* [[Designing weapons and armour]] - Advice from zookeeper on designing realistic weapons for your characters.
* [[Portrait Tutorial]] - A guide on how to draw unit/character portraits by Kitty.
* [[Armour Tutorial]] A tutorial on how to shade metallic armour by LordBob.
====Vector Art====
Sgt. Groovy's vector workshop - Tips and tricks for drawing with Inkscape.
:* [[Z-order tricks]] - A few methods for faking overlapping shapes.
:* [[Variable-width strokes]] - How to make the strokes vary in width, like being drawn with a flat-tipped pen — no tablet needed!
:* [[Shaped gradients with Gaussian blur]] - How to make gradients in other shapes than linear or radial.
:* [[Smooth shading in vector]] - The basic vector techniques for smooth shading, employing Gaussian blur and clipping/masking.
:* [[Vector Inking]] - Vector techniques, including mouse-only, for inking your sketches.
:* [[Making portrait art in vector]] - A complete tutorial for making Wesnoth unit portraits in vector graphics.

=== [[Terrain|Terrain Graphics]] ===

The following is information specific to drawing terrain for Wesnoth. Read Frame's "Tiles Tutorial" for a good overview of how terrain graphics work.

* [[Mesilliac's Essay on Terrain Perspective]] - The geometry behind the perspective used for terrain tiles in Wesnoth.
* [[Tiles Tutorial]] - Frame's tutorial describing the process of making terrain tiles in Wesnoth, and how they interact with adjacent tiles.
* [[How To Make Seamless Tiles]] - The tutorial is aimed at Photoshop users, but the technique is similar with GIMP.
* [[Seamless Tiles Using Inkscape]] - This tutorial teaches a method for making seamless hex tiles in vector craphics (to be rendered in raster).
* [[Turning Square Tiles into Hex]] - Nifty tricks for transforming square (or any rectangle) shaped seamless tiles into hexagon seamless tiles.
* [[CastleTutorial|Castle Tutorial]] - A description of how Wesnoth's castle tiles work (needs updating, but useful nonetheless).
* [[MultiHexTutorial|Multi-Hex Tiling Tutorial]] - A description of how multi-hex tiles work.
* [[Editing Castles]] - Instructions for how to make/edit castles (and other corner-based terrains) using yobbo's GIMP script.
* [[How to create textures]] - This tutorial proposes a process to create custom terrain textures from photo reference.

These describe the system used to specify how terrains behave in game:
* [[TerrainCodesWML]] - A list of the letters used to represent terrain types.
* [[TerrainGraphicsWML]] - If you really need to get technical, start here.
* [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml Ayin's Terrain Graphics document] - If you really, ''really'' need to get technical, this describes the terrain graphics WML system in depth.

=== Sprite Art ===
The following are different tutorials about sprite work compiled by various Wesnoth sprite artists. These will give you the most specific-to-Wesnoth information about making sprites, and are well worth a read.

* [[Creating Unit Art]] - A list of specifications you will need to match.
* [[Give Your Hero A Personality]] - Tricks for editing existing images, including some clip art.
* [[Team Color Shifting]] - How to create art that uses our new team color system.
* [[TeamColoring]] - How to automatically team-color sprites to see what they look like in various colors.
* [[Creating Shadows Under Units]] - How we create the shadows for the units in-game.
* [[How to Anti-Alias Sprite Art]] - A means of removing the jagged edges on pixel lines.
* [[Rotate Pixel Art Without Blurring]]
* [http://forums.wesnoth.org/download/file.php?id=56284 Zerovirus's Spriting Workflow] - Wesnoth artist Zerovirus explains step-by-step his methodology for creating Wesnoth sprites from scratch (.png file).
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
* [[FrankenPacks]] - A quick and dirty way to create sprites for [[Glossary|UMC]].
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
====Animation====
:* [[Basic Animation Tutorial]] - Or "How to Animate Sprites for Dummies," covering the basic theory, and all of the mistakes to avoid.
:* [[From Base Frame To Full Animation]] - A solid method of moving baseframes forward towards full animation.
:* [[How to create motion blurs]] - A simple explanation on how to create attack animation weapon blurs.
:* [[Making Bow Animations]] - The current standard for how we want bow animations to work.
:* [[Fire Animation]] - A great guide to creating fire FX by rhyging5.

=== External Tutorials ===
The following page contains dozens of links to tutorials covering all manner of artwork, including sprite art. These were not made by Wesnoth artists, but should prove very useful for general instruction.

* [[External Tutorials]]

== See Also ==
* [[Create]]
* [[EditingWesnoth]]
* [[GraphicLibrary]] - Old library of user contributed graphics (most should be GPL'ed)
* [[Project]]

[[Category:Art Tutorials]]

WML for Complete Beginners: Chapter 1

2013-04-04T18:45:35Z

Artisticdude: /* Attributes */

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

WML for Complete Beginners: Chapter 1

2013-04-04T18:39:35Z

Artisticdude: /* Attributes */

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

WML for Complete Beginners: Chapter 1

2013-04-04T18:35:58Z

Artisticdude: /* Tags */ Rewording, grammar nitpicks, clarifications

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

User:Artisticdude

2013-04-04T18:29:36Z

Artisticdude: /* Introduction */

'''WIP Links:'''
--------------------

*[http://wiki.wesnoth.org/WML_for_Complete_Beginners '''WIP template for future "WML for Complete Beginners" tutorial''']

--------------------

Template for future "Animating Running Cycles" tutorial

--------------------

=Animating Running Cycles=
by [http://forums.wesnoth.org/memberlist.php?mode=viewprofile&u=119614 artisticdude]

'''Note: This is a work in progress.'''

==Introduction==

I've heard some people say that running cycles are the hardest animation to create. Personally, I disagree with the idea that running animations are ''harder'' to create than any other kind of animation. It's true that creating running animations generally involves more ''work'' than creating most other animations (attack, death, defense, etc.), but usually running animations also follow a very strict set of rules. Once you understand these rules, creating running animations should be little more than investing enough time to see it through.

Note that I assume at least some level of competence in pixel art and animating throughout this tutorial. I also assume that the graphics program you are using supports layers and transparency (while those features aren't ''strictly'' necessary in order to create a running animation, they are huge time savers and will make your life a heck of a lot easier). If you haven't already, I suggest reading the [[Basic Animation Tutorial]] and [[From Base Frame To Full Animation]] before following this tutorial any further.

In this tutorial, I will demonstrate how to create a standard south-east/south-west facing run cycle by using the Goblin Impaler unit from mainline. Running animations for the other directions (north-east/north-west, south, & north) are drawn at different angles, but the concepts and theories discussed here apply to running cycles in all directions.

==Chapter 1: The Theory Behind Running Cycles==

===Poses===

Wesnoth running cycles are split into four distinct poses. Not frames, ''poses'', as in anatomical positions. These positions are:
* Contact
* Recoil
* Passing
* High Point

===Rotation===

As you may have noticed in the poses example above, there is a a certain amount of rotation happening over the course of the animation in the hips and shoulder areas. If you

===Bobbing===

===Movement Arcs===

==Chapter 2: Understanding Your Subject==
This is the most important part of the animation. You can come up with eight beautiful frames for your animation, but if those frames don't read as a realistic and fluid motion when played together as an animation, you might as well have just doodled random scribbles instead. Understanding your subject's anatomy, equipment, and weight will help you immensely in creating a realistic and fluid animation.

===Anatomy===

It is vital to any animation that you understand your subject's anatomy: where their joints are located, how far and in what direction those joints can bend and/or twist, whether there is a bone beneath the surface of a certain area or whether that area is composed of flexible membrane, etc. etc. This is especially important if your subject is not humanoid, but even for humanoids with non-human appendages or modified human appendages (tails, enormous ears, an extra set of arms, etc.). Before you even open your graphic editing program, study the baseframe of your subject and learn as much as you can about its anatomy. Find and study references, both still images and videos, if possible. Even creatures that don't have any real-world counterparts to study often have anatomical structures similar to those of real-world creatures.

===Equipment===

In addition to anatomy, it is paramount that you understand the equipment your subject is wearing/holding, since this will have a significant impact on how the character actually moves. I follow a list of simple steps to help me understand the equipment of the subject, in the form of a series of questions:

*'''What exactly is each piece of equipment?'''
Most of the time it will be fairly obvious what each piece of equipment on your subject is (it's really hard to mistake a properly-drawn sword for a toothbrush), but there will be occasions where you won't be able to decide what that blue dot at the side of the subject's waist is.
*'''What is the three-dimensional shape of each piece of equipment?'''
*'''What is each piece of equipment made of?'''
**'''How flexible/rigid is that material?''' Obviously a cloth tunic will have different dynamics than a solid metal breastplate.
*'''How much does weight is the subject carrying?'''
Weight is a huge factor in animations. How you convey that weight in your animation can either make your subject look light and etherial, or heavy and ponderous. If you're animating a fairy, chances are the subject's movements will be swift and graceful. Likewise, if you're animating a troll warrior, the subject's movements are likely to be clumsier and more ponderous. The movement of your subject will also be heavily influenced by the weight of their equipment; for instance, an elf in lightweight leather armor will be able to move much faster and easier compared to a human wearing a suit of heavy steel armor. In order to produce a convincing animation, you will need to make sure you know approximately how much weight your subject is dealing with.

Note that these questions are only to assist in drawing the motion of the object, not in drawing the object itself. To successfully draw and shade an object well, you must ask many additional questions which I won't go into here. If you do not know how to shade an object, I suggest you stop reading this page right now and do more reading up and practice on the subject before continuing.

==Chapter 3: Direction and Perspective==

===Direction===

So now that we understand how the character should move, it's time to start planning the direction of the movment. In this case, since we're doing a south-east running animation, we have to have the subject move from one hex to the neighboring south-east hex:

http://img51.imageshack.us/img51/6304/atob.png

So what now? Obviously we can't have the unit running at the wrong angle, otherwise it will look like he's sliding when the animation plays in-game. In order to help us avoid that potential pitfall, let's draw a three-dimensional graph to visualize the direction in which the unit will be running:

http://img18.imageshack.us/img18/5393/73920527.png

Viola! When in doubt, draw a graph. As you can see, we want our unit to run down the X axis (the red line) in order to reach the adjacent hex. If we were creating a north-east/north-west running animation, we would want the unit to run up the Y axis (the pink line). For now, however, let's stick with the south-east/south-west animation down the X axis.

So this is the path we want our unit to take during the animation:

http://img842.imageshack.us/img842/7556/howtogetthere.png

In terms of individual pixels, the line that shows the path our subject will take has a pixel angle of "two over, down one, over one, repeat", that is to say, over two pixels, down and over one pixel, then over two pixels again, down and over one pixel again, etc. To illustrate:

http://img94.imageshack.us/img94/1418/pixelangleinstance.png

It may be helpful for some to have the line be two pixels tall rather than only a single pixel tall, as I did in the first three images above. Note that the same angle still applies. Think of it as just placing another single-pixel-tall line on top of our existing single-pixel-tall line, like so:

http://img717.imageshack.us/img717/9810/thickerline.png

So, now we've established the direction in which our subject will be moving and the path the subject will be taking. We've even set up a helpful guideline to make sure the subject doesn't accidentally wander off that path at some point during the animation. Having gotten this step out of the way, let's talk about the perspective of your animation.

===Perspective===

==Chapter 4: Planning Your Animation==

==Chapter 5: Details, Details, Details==

==Chapter 6: Testing Your Animation==

User:Artisticdude

2013-04-04T18:22:03Z

Artisticdude: /* Direction */

'''WIP Links:'''
--------------------

*[http://wiki.wesnoth.org/WML_for_Complete_Beginners '''WIP template for future "WML for Complete Beginners" tutorial''']

--------------------

Template for future "Animating Running Cycles" tutorial

--------------------

=Animating Running Cycles=
by [http://forums.wesnoth.org/memberlist.php?mode=viewprofile&u=119614 artisticdude]

'''Note: This is a work in progress.'''

==Introduction==

I've heard some people say that running cycles are the hardest animation to make. Personally, I disagree with this notion. Running animations involve a lot of work, more so than most other animations (attack, death, defense, etc.), but generally running animations follow a very strict set of rules. Once you fully understand these rules, creating running animations should be little more than investing enough time to see it through.

Note that I assume at least some level of competence in pixel art and animating throughout this tutorial. I also assume that the graphics program you are using supports layers and transparency, although those features are not strictly necessary in order to create a running animation. If you haven't already, I suggest reading the [[Basic Animation Tutorial]] and [[From Base Frame To Full Animation]] before reading this page further.

In this tutorial, I will demonstrate how to create a standard south-east/south-west facing run cycle by using the Goblin Impaler unit from mainline. Running cycles for different directions (north-east/north-west, south, & north) are drawn at different angles, but the concepts and theories discussed here apply to running cycles in all directions.

==Chapter 1: The Theory Behind Running Cycles==

===Poses===

Wesnoth running cycles are split into four distinct poses. Not frames, ''poses'', as in anatomical positions. These positions are:
* Contact
* Recoil
* Passing
* High Point

===Rotation===

As you may have noticed in the poses example above, there is a a certain amount of rotation happening over the course of the animation in the hips and shoulder areas. If you

===Bobbing===

===Movement Arcs===

==Chapter 2: Understanding Your Subject==
This is the most important part of the animation. You can come up with eight beautiful frames for your animation, but if those frames don't read as a realistic and fluid motion when played together as an animation, you might as well have just doodled random scribbles instead. Understanding your subject's anatomy, equipment, and weight will help you immensely in creating a realistic and fluid animation.

===Anatomy===

It is vital to any animation that you understand your subject's anatomy: where their joints are located, how far and in what direction those joints can bend and/or twist, whether there is a bone beneath the surface of a certain area or whether that area is composed of flexible membrane, etc. etc. This is especially important if your subject is not humanoid, but even for humanoids with non-human appendages or modified human appendages (tails, enormous ears, an extra set of arms, etc.). Before you even open your graphic editing program, study the baseframe of your subject and learn as much as you can about its anatomy. Find and study references, both still images and videos, if possible. Even creatures that don't have any real-world counterparts to study often have anatomical structures similar to those of real-world creatures.

===Equipment===

In addition to anatomy, it is paramount that you understand the equipment your subject is wearing/holding, since this will have a significant impact on how the character actually moves. I follow a list of simple steps to help me understand the equipment of the subject, in the form of a series of questions:

*'''What exactly is each piece of equipment?'''
Most of the time it will be fairly obvious what each piece of equipment on your subject is (it's really hard to mistake a properly-drawn sword for a toothbrush), but there will be occasions where you won't be able to decide what that blue dot at the side of the subject's waist is.
*'''What is the three-dimensional shape of each piece of equipment?'''
*'''What is each piece of equipment made of?'''
**'''How flexible/rigid is that material?''' Obviously a cloth tunic will have different dynamics than a solid metal breastplate.
*'''How much does weight is the subject carrying?'''
Weight is a huge factor in animations. How you convey that weight in your animation can either make your subject look light and etherial, or heavy and ponderous. If you're animating a fairy, chances are the subject's movements will be swift and graceful. Likewise, if you're animating a troll warrior, the subject's movements are likely to be clumsier and more ponderous. The movement of your subject will also be heavily influenced by the weight of their equipment; for instance, an elf in lightweight leather armor will be able to move much faster and easier compared to a human wearing a suit of heavy steel armor. In order to produce a convincing animation, you will need to make sure you know approximately how much weight your subject is dealing with.

Note that these questions are only to assist in drawing the motion of the object, not in drawing the object itself. To successfully draw and shade an object well, you must ask many additional questions which I won't go into here. If you do not know how to shade an object, I suggest you stop reading this page right now and do more reading up and practice on the subject before continuing.

==Chapter 3: Direction and Perspective==

===Direction===

So now that we understand how the character should move, it's time to start planning the direction of the movment. In this case, since we're doing a south-east running animation, we have to have the subject move from one hex to the neighboring south-east hex:

http://img51.imageshack.us/img51/6304/atob.png

So what now? Obviously we can't have the unit running at the wrong angle, otherwise it will look like he's sliding when the animation plays in-game. In order to help us avoid that potential pitfall, let's draw a three-dimensional graph to visualize the direction in which the unit will be running:

http://img18.imageshack.us/img18/5393/73920527.png

Viola! When in doubt, draw a graph. As you can see, we want our unit to run down the X axis (the red line) in order to reach the adjacent hex. If we were creating a north-east/north-west running animation, we would want the unit to run up the Y axis (the pink line). For now, however, let's stick with the south-east/south-west animation down the X axis.

So this is the path we want our unit to take during the animation:

http://img842.imageshack.us/img842/7556/howtogetthere.png

In terms of individual pixels, the line that shows the path our subject will take has a pixel angle of "two over, down one, over one, repeat", that is to say, over two pixels, down and over one pixel, then over two pixels again, down and over one pixel again, etc. To illustrate:

http://img94.imageshack.us/img94/1418/pixelangleinstance.png

It may be helpful for some to have the line be two pixels tall rather than only a single pixel tall, as I did in the first three images above. Note that the same angle still applies. Think of it as just placing another single-pixel-tall line on top of our existing single-pixel-tall line, like so:

http://img717.imageshack.us/img717/9810/thickerline.png

So, now we've established the direction in which our subject will be moving and the path the subject will be taking. We've even set up a helpful guideline to make sure the subject doesn't accidentally wander off that path at some point during the animation. Having gotten this step out of the way, let's talk about the perspective of your animation.

===Perspective===

==Chapter 4: Planning Your Animation==

==Chapter 5: Details, Details, Details==

==Chapter 6: Testing Your Animation==

User:Artisticdude

2013-04-04T18:10:43Z

Artisticdude: /* Chapter 2: Understanding Your Subject */

'''WIP Links:'''
--------------------

*[http://wiki.wesnoth.org/WML_for_Complete_Beginners '''WIP template for future "WML for Complete Beginners" tutorial''']

--------------------

Template for future "Animating Running Cycles" tutorial

--------------------

=Animating Running Cycles=
by [http://forums.wesnoth.org/memberlist.php?mode=viewprofile&u=119614 artisticdude]

'''Note: This is a work in progress.'''

==Introduction==

I've heard some people say that running cycles are the hardest animation to make. Personally, I disagree with this notion. Running animations involve a lot of work, more so than most other animations (attack, death, defense, etc.), but generally running animations follow a very strict set of rules. Once you fully understand these rules, creating running animations should be little more than investing enough time to see it through.

Note that I assume at least some level of competence in pixel art and animating throughout this tutorial. I also assume that the graphics program you are using supports layers and transparency, although those features are not strictly necessary in order to create a running animation. If you haven't already, I suggest reading the [[Basic Animation Tutorial]] and [[From Base Frame To Full Animation]] before reading this page further.

In this tutorial, I will demonstrate how to create a standard south-east/south-west facing run cycle by using the Goblin Impaler unit from mainline. Running cycles for different directions (north-east/north-west, south, & north) are drawn at different angles, but the concepts and theories discussed here apply to running cycles in all directions.

==Chapter 1: The Theory Behind Running Cycles==

===Poses===

Wesnoth running cycles are split into four distinct poses. Not frames, ''poses'', as in anatomical positions. These positions are:
* Contact
* Recoil
* Passing
* High Point

===Rotation===

As you may have noticed in the poses example above, there is a a certain amount of rotation happening over the course of the animation in the hips and shoulder areas. If you

===Bobbing===

===Movement Arcs===

==Chapter 2: Understanding Your Subject==
This is the most important part of the animation. You can come up with eight beautiful frames for your animation, but if those frames don't read as a realistic and fluid motion when played together as an animation, you might as well have just doodled random scribbles instead. Understanding your subject's anatomy, equipment, and weight will help you immensely in creating a realistic and fluid animation.

===Anatomy===

It is vital to any animation that you understand your subject's anatomy: where their joints are located, how far and in what direction those joints can bend and/or twist, whether there is a bone beneath the surface of a certain area or whether that area is composed of flexible membrane, etc. etc. This is especially important if your subject is not humanoid, but even for humanoids with non-human appendages or modified human appendages (tails, enormous ears, an extra set of arms, etc.). Before you even open your graphic editing program, study the baseframe of your subject and learn as much as you can about its anatomy. Find and study references, both still images and videos, if possible. Even creatures that don't have any real-world counterparts to study often have anatomical structures similar to those of real-world creatures.

===Equipment===

In addition to anatomy, it is paramount that you understand the equipment your subject is wearing/holding, since this will have a significant impact on how the character actually moves. I follow a list of simple steps to help me understand the equipment of the subject, in the form of a series of questions:

*'''What exactly is each piece of equipment?'''
Most of the time it will be fairly obvious what each piece of equipment on your subject is (it's really hard to mistake a properly-drawn sword for a toothbrush), but there will be occasions where you won't be able to decide what that blue dot at the side of the subject's waist is.
*'''What is the three-dimensional shape of each piece of equipment?'''
*'''What is each piece of equipment made of?'''
**'''How flexible/rigid is that material?''' Obviously a cloth tunic will have different dynamics than a solid metal breastplate.
*'''How much does weight is the subject carrying?'''
Weight is a huge factor in animations. How you convey that weight in your animation can either make your subject look light and etherial, or heavy and ponderous. If you're animating a fairy, chances are the subject's movements will be swift and graceful. Likewise, if you're animating a troll warrior, the subject's movements are likely to be clumsier and more ponderous. The movement of your subject will also be heavily influenced by the weight of their equipment; for instance, an elf in lightweight leather armor will be able to move much faster and easier compared to a human wearing a suit of heavy steel armor. In order to produce a convincing animation, you will need to make sure you know approximately how much weight your subject is dealing with.

Note that these questions are only to assist in drawing the motion of the object, not in drawing the object itself. To successfully draw and shade an object well, you must ask many additional questions which I won't go into here. If you do not know how to shade an object, I suggest you stop reading this page right now and do more reading up and practice on the subject before continuing.

==Chapter 3: Direction and Perspective==

===Direction===

So now that we understand how the character should move, it's time to start planning the direction of the movment. In this case, we have to have the subject move from one hex to the neighboring south-east hex, from point A to point B.

http://img51.imageshack.us/img51/6304/atob.png

So what now? Obviously we can't have the unit running at the wrong angle, otherwise it will look like he's sliding when the animation plays in-game. So let's draw a three-dimensional graph to visualize the direction in which the unit will be running:

http://img18.imageshack.us/img18/5393/73920527.png

As you can see, we want our unit to run down the X axis (the red line) in order to reach the adjacent hex. If we were creating a north-east/north-west running animation, we would want the unit to run up the Y axis (the pink line). For now, however, let's stick with the south-east/south-west animation down the X axis.

So this is the path we want our unit to take during the animation:

http://img842.imageshack.us/img842/7556/howtogetthere.png

In terms of individual pixels, the line we used has a pixel angle of "two over, down one, over one, repeat", that is to say, over two pixels, down and over one pixel, then over two pixels, down and over one pixel, etc. To illustrate:

http://img94.imageshack.us/img94/1418/pixelangleinstance.png

It may be helpful for some to have the line be two pixels tall rather than only a single pixel tall, as I did in the first three images above. The same angle still applies, however. Think of it as just placing another single-pixel-tall line on top of another single-pixel-tall line, like so:

http://img717.imageshack.us/img717/9810/thickerline.png

You have now established the direction in which your unit will be moving and facing. You have even set up a helpful guideline to make sure you don't accidentally stray from that direction at some point during the animation process. So now that you have determined the direction, let's talk about the perspective of your animation.

===Perspective===

==Chapter 4: Planning Your Animation==

==Chapter 5: Details, Details, Details==

==Chapter 6: Testing Your Animation==

WML for Complete Beginners

2013-04-02T17:43:18Z

Artisticdude:

WML for Complete Beginners: Introduction

2013-04-02T17:40:40Z

Artisticdude: Created page with '==Introduction== Hey there! Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this…'

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder about the purpose of this tutorial. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
The specific demographic for which this tutorial is intended is users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder paths and locate specific directories. In this tutorial you will learn the fundamentals of WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming in WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML (in fact, it is recommended that you ''avoid'' using those fancy word processors); a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without being required to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

WML for Complete Beginners: Conclusion

2013-04-02T17:40:11Z

Artisticdude: Created page with '==Conclusion: Where to Go From Here== As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the h…'

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

WML for Complete Beginners: Chapter 11

2013-04-02T17:39:33Z

Artisticdude: Created page with '==Chapter 11: More Logic: Cases and Loops== ===Cases=== Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to …'

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

I was a very messy child, much to the distress of my mother, who was the epitome of cleanliness and couldn't for the life of her understand how she could have raised such an untidy child as me. Occasionally she'd work up enough courage to venture into the land of chaos that was my room, and then she'd tell me not leave my room until it was picked up.

Okay, intimate family analogies aside, pay attention to how my mother told me to clean up my room: I was not to leave my room until it was clean. Whether or not the room was clean was the condition on which my permission to leave my room depended. So each time I put something away (which, more often then not, I did by stuffing the item under the bed), I would have to check to see that condition was met. If the room wasn't clean, then my mother's condition wasn't met and I had to keep cleaning. If the room was clean, then my mother's condition was met and I was free to leave my room.

Talk about basic parts of loops, variations of loops (do/while, etc.)

WML for Complete Beginners: Chapter 10

2013-04-02T17:39:08Z

Artisticdude: Created page with '==Chapter 10: Introduction to Logic== ===If This, Then That=== Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk tow…'

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

WML for Complete Beginners: Chapter 9

2013-04-02T17:38:37Z

Artisticdude: Created page with '==Chapter 9: Macros== Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customer…'

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

WML for Complete Beginners: Chapter 8

2013-04-02T17:38:18Z

Artisticdude: Created page with '==Chapter 8: Array, and Container Variables== So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, t…'

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

WML for Complete Beginners: Chapter 7

2013-04-02T17:37:55Z

Artisticdude: Created page with '==Chapter 7: Introduction to Variables== Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new hom…'

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

WML for Complete Beginners: Chapter 6

2013-04-02T17:37:30Z

Artisticdude: Created page with '==Chapter 6: Building and Including a Custom Unit== Sometimes campaign authors only use mainline units in their campaigns. Other times, however, they may want to include a custo…'

==Chapter 6: Building and Including a Custom Unit==

Sometimes campaign authors only use mainline units in their campaigns. Other times, however, they may want to include a custom unit that isn't found in default Wesnoth. Thankfully, including a custom unit is quite easy.

===Creating Your Custom Unit's .cfg File===

===Including the Custom Unit In Your Campaign===

WML for Complete Beginners: Chapter 5

2013-04-02T17:37:06Z

Artisticdude: Created page with '==Chapter 5: Events== Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When…'

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

WML for Complete Beginners: Chapter 4

2013-04-02T17:36:38Z

Artisticdude: Created page with '==Chapter 4: Creating Your First Scenario== Now that you have your _main.cfg file, it's time to create your first scenario. ===Creating the Scenario Map=== All scenarios requi…'

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

WML for Complete Beginners: Chapter 3

2013-04-02T17:35:56Z

Artisticdude: Created page with '==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 does…'

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

WML for Complete Beginners: Chapter 2

2013-04-02T17:35:12Z

Artisticdude: Created page with '==Chapter 2: The Userdata Directory and the Campaign Folder== So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so…'

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_first_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

WML for Complete Beginners: Chapter 1

2013-04-02T17:34:44Z

Artisticdude: Created page with '==Chapter 1: Syntax== First things first; let's go over the ''syntax'' of WML. For those of you who might not know what the "syntax" of a language is, think of it as a set of r…'

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

User:Nesuworjoni420

2013-04-02T04:14:15Z

Artisticdude: Blanked the page

User:UFJAbby

2013-04-02T04:13:39Z

Artisticdude: Blanked the page

User:ValerieLu

2013-04-02T04:13:15Z

Artisticdude: Blanked the page

Create

2013-04-02T03:57:41Z

Artisticdude: /* What can I create, and how? */ "campaign server" -> "add-on server"

{{Create/Translations}}
{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have a UTF-8 text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

== Read this first! ==
Before you modify or add anything, it is important to understand how the game stores and organizes its data. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== What can I create, and how? ==



<div class="thumb tright"><div>
[http://img837.imageshack.us/img837/865/screenshot20120205at529.png http://img26.imageshack.us/img26/8613/thumbhav.png]
<div class="thumbcaption">Battle for Wesnoth 1.10 map editor</div></div>
</div>

* [[BuildingMaps|Maps]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]]

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth
* [[Practical Guide to Modifying AI Behavior|Artificial Intelligence]] - how to create and modify AI behaviour

* [[Distributing content]] - all about the add-on server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns



== What have others done? ==

There is a multitude of multiplayer factions and eras, multiplayer maps and discussion of campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[Timeline of Wesnoth|The timeline of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* ADDON SERVER [http://addons.wesnoth.org web interface] - An alternate way to download user made content

[[Category:Create|*]]

Create

2013-04-02T03:54:17Z

Artisticdude: On second thought, just remove any mention of the to-do art, since we don't have a current list of to-do projects

{{Create/Translations}}
{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have a UTF-8 text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

== Read this first! ==
Before you modify or add anything, it is important to understand how the game stores and organizes its data. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== What can I create, and how? ==



<div class="thumb tright"><div>
[http://img837.imageshack.us/img837/865/screenshot20120205at529.png http://img26.imageshack.us/img26/8613/thumbhav.png]
<div class="thumbcaption">Battle for Wesnoth 1.10 map editor</div></div>
</div>

* [[BuildingMaps|Maps]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]]

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth
* [[Practical Guide to Modifying AI Behavior|Artificial Intelligence]] - how to create and modify AI behaviour

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns



== What have others done? ==

There is a multitude of multiplayer factions and eras, multiplayer maps and discussion of campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[Timeline of Wesnoth|The timeline of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* ADDON SERVER [http://addons.wesnoth.org web interface] - An alternate way to download user made content

[[Category:Create|*]]

Create

2013-04-02T03:53:00Z

Artisticdude: Removed reference to a (severely) obsolete list of to-do art projects

{{Create/Translations}}
{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have a UTF-8 text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

It should also be noted that '''we need a lot of help creating artwork for the core of the game.''' We'll happily help you out, if you take a swing at them.

== Read this first! ==
Before you modify or add anything, it is important to understand how the game stores and organizes its data. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== What can I create, and how? ==



<div class="thumb tright"><div>
[http://img837.imageshack.us/img837/865/screenshot20120205at529.png http://img26.imageshack.us/img26/8613/thumbhav.png]
<div class="thumbcaption">Battle for Wesnoth 1.10 map editor</div></div>
</div>

* [[BuildingMaps|Maps]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]]

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth
* [[Practical Guide to Modifying AI Behavior|Artificial Intelligence]] - how to create and modify AI behaviour

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns



== What have others done? ==

There is a multitude of multiplayer factions and eras, multiplayer maps and discussion of campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[Timeline of Wesnoth|The timeline of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* ADDON SERVER [http://addons.wesnoth.org web interface] - An alternate way to download user made content

[[Category:Create|*]]

LuaWML

2013-04-02T03:32:00Z

Artisticdude: /* Interface to the engine and helper functions */ Minor rephrasing

{{WML Tags}}

== The '''[lua]''' tag ==

This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.2] language.

The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.

[lua]
code = << wesnoth.message "Hello World!" >>
[/lua]

The Lua kernel can also be accessed from the [[CommandMode|command mode]]:

:lua local u = wesnoth.get_units({ id = "Konrad" })[1]; u.moves = 5

The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable "'''...'''".

[lua]
code = << local t = ...; wesnoth.message(tostring(t.text)) >>
[args]
text = _ "Hello world!"
[/args]
[/lua]

== Global environment ==

All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.

[event]
name = preload
first_time_only = no
[lua]
code = <<
function narrator(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
>>
[/lua]
[/event]

[event]
name = turn 1
[lua]
code = << narrator(...) >>
[args]
sentence = _ "Hello world!"
[/args]
[/lua]
[lua]
code = << narrator(...) >>
[args]
sentence = _ "How are you today?"
[/args]
[/lua]
[/event]

In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.

[event]
name = preload
first_time_only = no
[lua]
code = <<
-- The function is now local, since its name does not have to be
-- visible outside this Lua scripts.
local function handler(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
-- Create a new tag named [narrator].
wesnoth.register_wml_action("narrator", handler)
>>
[/lua]
[/event]

[event]
name = turn 1
[narrator]
sentence = _ "Hello world!"
[/narrator]
[narrator]
sentence = _ "How are you today?"
[/narrator]
[/event]

The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.

The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. Additionally, the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library (keep in mind that they aren't multiplayer- and replay-safe), as well as traceback from the [http://www.lua.org/manual/5.1/manual.html#5.9 debug] library are also available.

At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.

== Examples ==

The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.

# General catch for them moving to the wrong place.
[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[if]
[variable]
name=target_hex.is_set
equals=yes
[/variable]
[then]
[if]
[variable]
name=x1
equals=$target_hex.x
[/variable]
[variable]
name=y1
equals=$target_hex.y
[/variable]
[then]
[/then]
[else]
[redraw][/redraw]
[message]
speaker=narrator
message=_ "*Oops!
You moved to the wrong place! After this message, you can press 'u' to undo, then try again." +
_ "
*Left click or press spacebar to continue..."
[/message]
[/else]
[/if]
[/then]
[/if]
[/event]

A Lua script that performs the same action is presented below.

[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[lua]
code = <<
local event_data = wesnoth.current.event_context
if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)
then
W.redraw()
narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")
end
>>
[/lua]
[/event]

Here is a more detailed explanation of the Lua code. Its first line

local event_data = wesnoth.current.event_context

puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.

The next two lines then test

if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)

whether the variable ''target_hex'' matches the event parameters. Since ''target_hex'' is not a local variable, it is taken from the global environment (a table implicitly named ''_G'', so it is actually ''_G.target_hex''). The global environment is not persistent, so it cannot be used to store data. In order to make it useful, it was mapped to the storage of WML variables by the following ''preload'' event.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
-- skipping some other initializations
-- ...
H.set_wml_var_metatable(_G)
>>
[/lua]
[/event]

Without a prelude redirecting ''_G'', the conditional would have been written

if wesnoth.get_variable("target_hex.is_set") and
(event_data.x1 ~= wesnoth.get_variable("target_hex.x") or event_data.y1 ~= wesnoth.get_variable("target_hex.y")

The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.

W.redraw()

Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.

W = H.set_wml_action_metatable {}

Without this shortcut, the first statement would have been written

wesnoth.fire("redraw")

Finally the script displays a message by

narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")

The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is

function narrator_says(m)
W.message { speaker="narrator",
message = m .. _ "\n*Left click or press spacebar to continue..." }
end

The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:

_ = wesnoth.textdomain "wesnoth-tutorial"

A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].

== Interface to the engine and helper functions ==

Functionalities of the game engine are available through the functions contained in the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked "read-only" are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.

Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].

helper = wesnoth.require "lua/helper.lua"

=== WML variables ===

* [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]
* [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]
* [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]
* [[LuaWML:Variables#helper.get_child|helper.get_child]]
* [[LuaWML:Variables#helper.child_range|helper.child_range]]
* [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]
* [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]
* [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]

=== Events and WML actions ===

* [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]
* [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]]
* [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]]
* [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]
* [[LuaWML:Events#helper.literal|helper.literal]]
* [[LuaWML:Events#helper.parsed|helper.parsed]]
* [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]]
* [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]]
* [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]]
* [[LuaWML:Display#wesnoth.lock_view|wesnoth.lock_view]]
* [[LuaWML:Display#wesnoth.view_locked|wesnoth.view_locked]]
* [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]]
* [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]]
* [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]]
* [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]]
* [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]]
* [[LuaWML:Display#wesnoth.set_dialog_active|wesnoth.set_dialog_active]]
* [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]]
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]]
* [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]]
* [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]]
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]
* [[LuaWML:Display#wesnoth.get_time_of_day|wesnoth.get_time_of_day]]

=== Map and terrains ===

* [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]
* [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]
* [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]
* [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]
* [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]
* [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]]
* {{DevFeature1.11}}[[LuaWML:Tiles#wesnoth.get_villages|wesnoth.get_villages]]
* [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]]
* [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]]
* [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]]
* [[LuaWML:Tiles#items.place_image|items.place_image]]
* [[LuaWML:Tiles#items.place_halo|items.place_halo]]
* [[LuaWML:Tiles#items.remove|items.remove]]

=== Units ===

* [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]
* [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]]
* [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]]
* [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]
* [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]]
* [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]]
* [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]
* [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]
* [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]]
* [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]]
* [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]
* [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]
* [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]
* [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]]
* [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]
* [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]
* [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]]
* [[LuaWML:Units#wesnoth.races|wesnoth.races]]
* [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]]
* [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]
* [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]]
* [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]]
* [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]
* [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]
* [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]]
* [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]]
* [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]]
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]

=== Pathfinder ===

* [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]
* [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]
* [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]
* [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]
* [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]]

=== Lua files ===

* [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]
* [[LuaWML:Files#wesnoth.require|wesnoth.require]]

=== Location sets ===

* [[LuaWML:Location_set#location_set.create|location_set.create]]
* [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]]
* [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]]
* [[LuaWML:Location_set#location_set:empty|location_set:empty]]
* [[LuaWML:Location_set#location_set:size|location_set:size]]
* [[LuaWML:Location_set#location_set:clear|location_set:clear]]
* [[LuaWML:Location_set#location_set:get|location_set:get]]
* [[LuaWML:Location_set#location_set:insert|location_set:insert]]
* [[LuaWML:Location_set#location_set:remove|location_set:remove]]
* [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]]
* [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]]
* [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]]
* [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]]
* [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]]
* [[LuaWML:Location_set#location_set:union|location_set:union]]
* [[LuaWML:Location_set#location_set:inter|location_set:inter]]
* [[LuaWML:Location_set#location_set:iter|location_set:iter]]
* [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]]
* [[LuaWML:Location_set#location_set:filter|location_set:filter]]
* [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]]
* [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]]

=== Miscellaneous ===

* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]
* [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]]
* [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]]
* [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]]
* [[LuaWML:Misc#wesnoth.have_file|wesnoth.have_file]] {{DevFeature1.11}}
* [[LuaWML:Misc#wesnoth.debug|wesnoth.debug]]
* [[LuaWML:Misc#wesnoth.get_time_stamp|wesnoth.get_time_stamp]] {{DevFeature1.11}}
* [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]
* [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]
* [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]
* [[LuaWML:Misc#helper.rand|helper.rand]]
* [[LuaWML:Misc#helper.round|helper.round]] {{DevFeature1.11}}
* [[LuaWML:Misc#helper.shuffle|helper.shuffle]] {{DevFeature1.11}}

== Encoding WML objects into Lua tables ==

Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.

Scalar fields are transformed into WML attributes. For instance, the following Lua table

{
a_bool = true,
an_int = 42,
a_float = 1.25,
a_string = "scout",
a_translation = _ "Hello World!"
}

is equivalent to the content of the following WML object

[dummy]
a_bool = "yes"
an_int = "42"
a_float = "1.25"
a_string = "scout"
a_translation = _ "Hello World!"
[/dummy]

WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form {[1] = "tag_name", [2] = {}} which is equivalent to {"tag_name", {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { z = 5, { "barfoo", {} } } }
}

is equivalent to the content of the following WML object

[dummy]
foo = 42
[bar]
v = 1
w = 2
[/bar]
[foo]
x = no
[/foo]
[bar]
y = foo
[bar]
[foobar]
z = 5
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:
{
foo = 42,
[1] = { [1] = "bar", [2] = { v = 1, w = 2 } },
[2] = { [1] = "foo", [2] = { x = false } },
[3] = { [1] = "bar", [2] = { y = "foo" } },
[4] = { [1] = "foobar", [2] = { z = 5, [1] = { [1] = "barfoo", [2] = {} } } }
}

So assuming ''cfg'' contains the above WML object, the following accesses are possible:

a_int = cfg.foo -- "dummy.foo", 42
a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"
a_table = cfg[4][2] -- "dummy.foobar", { z = 5, { "barfoo", {} } }

Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.

Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.

For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.

local old_event_handler
old_event_handler = register_wml_action("event",
function(cfg)
-- Get the plain text from the user.
local new_cfg = cfg.__literal
-- The expression below is equivalent to cfg.__parsed.first_time_only,
-- only faster. It is needed, since the first_time_only attribute may
-- reference variables.
local first = cfg.first_time_only
-- Modify the default behavior of first_time_only.
if first == nil then first = false end
new_cfg.first_time_only = first
-- Call the engine handler.
old_event_handler(new_cfg)
end
)

Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:

function get_child(cfg, name)
for i = 1, #cfg do
local v = cfg[i]
if v[1] == name then return v[2] end
end
end

Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:

if getmetatable(cfg) == "wml object" then cfg = cfg.__parsed end

The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal'''. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.

== Skeleton of a preload event ==

The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It also sets up the global environment so that any access to an undefined global variable is redirected to the persistent WML storage.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
W = H.set_wml_action_metatable {}
_ = wesnoth.textdomain "my-campaign"

-- Define your global constants here.
-- ...

H.set_wml_var_metatable(_G)

-- Define your global functions here.
-- ...
>>
[/lua]
[/event]

It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:

[event]
name=preload
first_time_only=no
[lua]
code = << wesnoth.dofile "~add-ons/Whatever/file.lua" >>
[/lua]
[/event]

== Remarks ==

The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.

function random(min, max)
if not max then min, max = 1, min end
wesnoth.fire("set_variable", { name = "LUA_random", rand = string.format("%d..%d", min, max) })
local res = wesnoth.get_variable "LUA_random"
wesnoth.set_variable "LUA_random"
return res
end

[[Category: Lua Reference|*]]
[[Category: WML Reference]]

LuaWML

2013-04-02T03:21:01Z

Artisticdude: /* Global environment */ Misc. minor editing (typos, grammar corrections)

{{WML Tags}}

== The '''[lua]''' tag ==

This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.2] language.

The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.

[lua]
code = << wesnoth.message "Hello World!" >>
[/lua]

The Lua kernel can also be accessed from the [[CommandMode|command mode]]:

:lua local u = wesnoth.get_units({ id = "Konrad" })[1]; u.moves = 5

The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable "'''...'''".

[lua]
code = << local t = ...; wesnoth.message(tostring(t.text)) >>
[args]
text = _ "Hello world!"
[/args]
[/lua]

== Global environment ==

All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.

[event]
name = preload
first_time_only = no
[lua]
code = <<
function narrator(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
>>
[/lua]
[/event]

[event]
name = turn 1
[lua]
code = << narrator(...) >>
[args]
sentence = _ "Hello world!"
[/args]
[/lua]
[lua]
code = << narrator(...) >>
[args]
sentence = _ "How are you today?"
[/args]
[/lua]
[/event]

In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.

[event]
name = preload
first_time_only = no
[lua]
code = <<
-- The function is now local, since its name does not have to be
-- visible outside this Lua scripts.
local function handler(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
-- Create a new tag named [narrator].
wesnoth.register_wml_action("narrator", handler)
>>
[/lua]
[/event]

[event]
name = turn 1
[narrator]
sentence = _ "Hello world!"
[/narrator]
[narrator]
sentence = _ "How are you today?"
[/narrator]
[/event]

The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.

The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. Additionally, the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library (keep in mind that they aren't multiplayer- and replay-safe), as well as traceback from the [http://www.lua.org/manual/5.1/manual.html#5.9 debug] library are also available.

At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.

== Examples ==

The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.

# General catch for them moving to the wrong place.
[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[if]
[variable]
name=target_hex.is_set
equals=yes
[/variable]
[then]
[if]
[variable]
name=x1
equals=$target_hex.x
[/variable]
[variable]
name=y1
equals=$target_hex.y
[/variable]
[then]
[/then]
[else]
[redraw][/redraw]
[message]
speaker=narrator
message=_ "*Oops!
You moved to the wrong place! After this message, you can press 'u' to undo, then try again." +
_ "
*Left click or press spacebar to continue..."
[/message]
[/else]
[/if]
[/then]
[/if]
[/event]

A Lua script that performs the same action is presented below.

[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[lua]
code = <<
local event_data = wesnoth.current.event_context
if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)
then
W.redraw()
narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")
end
>>
[/lua]
[/event]

Here is a more detailed explanation of the Lua code. Its first line

local event_data = wesnoth.current.event_context

puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.

The next two lines then test

if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)

whether the variable ''target_hex'' matches the event parameters. Since ''target_hex'' is not a local variable, it is taken from the global environment (a table implicitly named ''_G'', so it is actually ''_G.target_hex''). The global environment is not persistent, so it cannot be used to store data. In order to make it useful, it was mapped to the storage of WML variables by the following ''preload'' event.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
-- skipping some other initializations
-- ...
H.set_wml_var_metatable(_G)
>>
[/lua]
[/event]

Without a prelude redirecting ''_G'', the conditional would have been written

if wesnoth.get_variable("target_hex.is_set") and
(event_data.x1 ~= wesnoth.get_variable("target_hex.x") or event_data.y1 ~= wesnoth.get_variable("target_hex.y")

The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.

W.redraw()

Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.

W = H.set_wml_action_metatable {}

Without this shortcut, the first statement would have been written

wesnoth.fire("redraw")

Finally the script displays a message by

narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")

The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is

function narrator_says(m)
W.message { speaker="narrator",
message = m .. _ "\n*Left click or press spacebar to continue..." }
end

The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:

_ = wesnoth.textdomain "wesnoth-tutorial"

A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].

== Interface to the engine and helper functions ==

Functionalities of the game engine are available through the functions of the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked "read-only" are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.

Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].

helper = wesnoth.require "lua/helper.lua"

=== WML variables ===

* [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]
* [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]
* [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]
* [[LuaWML:Variables#helper.get_child|helper.get_child]]
* [[LuaWML:Variables#helper.child_range|helper.child_range]]
* [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]
* [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]
* [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]

=== Events and WML actions ===

* [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]
* [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]]
* [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]]
* [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]
* [[LuaWML:Events#helper.literal|helper.literal]]
* [[LuaWML:Events#helper.parsed|helper.parsed]]
* [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]]
* [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]]
* [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]]
* [[LuaWML:Display#wesnoth.lock_view|wesnoth.lock_view]]
* [[LuaWML:Display#wesnoth.view_locked|wesnoth.view_locked]]
* [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]]
* [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]]
* [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]]
* [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]]
* [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]]
* [[LuaWML:Display#wesnoth.set_dialog_active|wesnoth.set_dialog_active]]
* [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]]
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]]
* [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]]
* [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]]
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]
* [[LuaWML:Display#wesnoth.get_time_of_day|wesnoth.get_time_of_day]]

=== Map and terrains ===

* [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]
* [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]
* [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]
* [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]
* [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]
* [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]]
* {{DevFeature1.11}}[[LuaWML:Tiles#wesnoth.get_villages|wesnoth.get_villages]]
* [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]]
* [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]]
* [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]]
* [[LuaWML:Tiles#items.place_image|items.place_image]]
* [[LuaWML:Tiles#items.place_halo|items.place_halo]]
* [[LuaWML:Tiles#items.remove|items.remove]]

=== Units ===

* [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]
* [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]]
* [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]]
* [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]
* [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]]
* [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]]
* [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]
* [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]
* [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]]
* [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]]
* [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]
* [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]
* [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]
* [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]]
* [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]
* [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]
* [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]]
* [[LuaWML:Units#wesnoth.races|wesnoth.races]]
* [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]]
* [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]
* [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]]
* [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]]
* [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]
* [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]
* [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]]
* [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]]
* [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]]
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]

=== Pathfinder ===

* [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]
* [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]
* [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]
* [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]
* [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]]

=== Lua files ===

* [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]
* [[LuaWML:Files#wesnoth.require|wesnoth.require]]

=== Location sets ===

* [[LuaWML:Location_set#location_set.create|location_set.create]]
* [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]]
* [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]]
* [[LuaWML:Location_set#location_set:empty|location_set:empty]]
* [[LuaWML:Location_set#location_set:size|location_set:size]]
* [[LuaWML:Location_set#location_set:clear|location_set:clear]]
* [[LuaWML:Location_set#location_set:get|location_set:get]]
* [[LuaWML:Location_set#location_set:insert|location_set:insert]]
* [[LuaWML:Location_set#location_set:remove|location_set:remove]]
* [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]]
* [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]]
* [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]]
* [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]]
* [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]]
* [[LuaWML:Location_set#location_set:union|location_set:union]]
* [[LuaWML:Location_set#location_set:inter|location_set:inter]]
* [[LuaWML:Location_set#location_set:iter|location_set:iter]]
* [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]]
* [[LuaWML:Location_set#location_set:filter|location_set:filter]]
* [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]]
* [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]]

=== Miscellaneous ===

* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]
* [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]]
* [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]]
* [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]]
* [[LuaWML:Misc#wesnoth.have_file|wesnoth.have_file]] {{DevFeature1.11}}
* [[LuaWML:Misc#wesnoth.debug|wesnoth.debug]]
* [[LuaWML:Misc#wesnoth.get_time_stamp|wesnoth.get_time_stamp]] {{DevFeature1.11}}
* [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]
* [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]
* [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]
* [[LuaWML:Misc#helper.rand|helper.rand]]
* [[LuaWML:Misc#helper.round|helper.round]] {{DevFeature1.11}}
* [[LuaWML:Misc#helper.shuffle|helper.shuffle]] {{DevFeature1.11}}

== Encoding WML objects into Lua tables ==

Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.

Scalar fields are transformed into WML attributes. For instance, the following Lua table

{
a_bool = true,
an_int = 42,
a_float = 1.25,
a_string = "scout",
a_translation = _ "Hello World!"
}

is equivalent to the content of the following WML object

[dummy]
a_bool = "yes"
an_int = "42"
a_float = "1.25"
a_string = "scout"
a_translation = _ "Hello World!"
[/dummy]

WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form {[1] = "tag_name", [2] = {}} which is equivalent to {"tag_name", {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { z = 5, { "barfoo", {} } } }
}

is equivalent to the content of the following WML object

[dummy]
foo = 42
[bar]
v = 1
w = 2
[/bar]
[foo]
x = no
[/foo]
[bar]
y = foo
[bar]
[foobar]
z = 5
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:
{
foo = 42,
[1] = { [1] = "bar", [2] = { v = 1, w = 2 } },
[2] = { [1] = "foo", [2] = { x = false } },
[3] = { [1] = "bar", [2] = { y = "foo" } },
[4] = { [1] = "foobar", [2] = { z = 5, [1] = { [1] = "barfoo", [2] = {} } } }
}

So assuming ''cfg'' contains the above WML object, the following accesses are possible:

a_int = cfg.foo -- "dummy.foo", 42
a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"
a_table = cfg[4][2] -- "dummy.foobar", { z = 5, { "barfoo", {} } }

Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.

Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.

For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.

local old_event_handler
old_event_handler = register_wml_action("event",
function(cfg)
-- Get the plain text from the user.
local new_cfg = cfg.__literal
-- The expression below is equivalent to cfg.__parsed.first_time_only,
-- only faster. It is needed, since the first_time_only attribute may
-- reference variables.
local first = cfg.first_time_only
-- Modify the default behavior of first_time_only.
if first == nil then first = false end
new_cfg.first_time_only = first
-- Call the engine handler.
old_event_handler(new_cfg)
end
)

Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:

function get_child(cfg, name)
for i = 1, #cfg do
local v = cfg[i]
if v[1] == name then return v[2] end
end
end

Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:

if getmetatable(cfg) == "wml object" then cfg = cfg.__parsed end

The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal'''. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.

== Skeleton of a preload event ==

The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It also sets up the global environment so that any access to an undefined global variable is redirected to the persistent WML storage.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
W = H.set_wml_action_metatable {}
_ = wesnoth.textdomain "my-campaign"

-- Define your global constants here.
-- ...

H.set_wml_var_metatable(_G)

-- Define your global functions here.
-- ...
>>
[/lua]
[/event]

It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:

[event]
name=preload
first_time_only=no
[lua]
code = << wesnoth.dofile "~add-ons/Whatever/file.lua" >>
[/lua]
[/event]

== Remarks ==

The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.

function random(min, max)
if not max then min, max = 1, min end
wesnoth.fire("set_variable", { name = "LUA_random", rand = string.format("%d..%d", min, max) })
local res = wesnoth.get_variable "LUA_random"
wesnoth.set_variable "LUA_random"
return res
end

[[Category: Lua Reference|*]]
[[Category: WML Reference]]

WML for Complete Beginners

2012-11-30T14:59:29Z

Artisticdude: Started on the section about loops

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder about the purpose of this tutorial. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
The specific demographic for which this tutorial is intended is users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder paths and locate specific directories. In this tutorial you will learn the fundamentals of WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming in WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML (in fact, it is recommended that you ''avoid'' using those fancy word processors); a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without being required to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_first_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

Sometimes campaign authors only use mainline units in their campaigns. Other times, however, they may want to include a custom unit that isn't found in default Wesnoth. Thankfully, including a custom unit is quite easy.

===Creating Your Custom Unit's .cfg File===

===Including the Custom Unit In Your Campaign===

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

I was a very messy child, much to the distress of my mother, who was the epitome of cleanliness and couldn't for the life of her understand how she could have raised such an untidy child as me. Occasionally she'd work up enough courage to venture into the land of chaos that was my room, and then she'd tell me not leave my room until it was picked up.

Okay, intimate family analogies aside, pay attention to how my mother told me to clean up my room: I was not to leave my room until it was clean. Whether or not the room was clean was the condition on which my permission to leave my room depended. So each time I put something away (which, more often then not, I did by stuffing the item under the bed), I would have to check to see that condition was met. If the room wasn't clean, then my mother's condition wasn't met and I had to keep cleaning. If the room was clean, then my mother's condition was met and I was free to leave my room.

Talk about basic parts of loops, variations of loops (do/while, etc.)

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

LuaWML/Display

2012-06-20T22:30:23Z

Artisticdude: /* wesnoth.play_sound */ Minor rewording/clarifications

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "<span color='#ff0000'>Ouch</span>")

==== wesnoth.get_time_of_day ====

Returns schedule information. First parameter (optional) is the turn number for which to return the information, if unspecified: the current turn ($turn_number). Second argument is an optional table. If present, first and second fields must be valid on-map coordinates and all current time_areas in the scenario are taken into account (if a time area happens to contain the passed hex). If the table isn't present, the scenario main schedule is returned. The table has an optional third parameter (boolean). If true (default: false), time of day modifying units (such as MoL) are taken into account (if the passed hex happens to be affected). The units placement being considered is always the current one.

wesnoth.get_time_of_day(2, { 37, 3, true })

The function returns a table with these named fields:
* '''id''': string (as in [time])
* '''lawful_bonus''': integer (as in [time])
* '''bonus_modified''': integer (bonus change by units)
* '''image''': string (tod image in sidebar)
* '''name''': translatable string
* '''red, green, blue''': integers (color adjustment for this time)

==== wesnoth.select_hex ====

Selects the given location in the game map as if the player would have clicked onto it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false)

wesnoth.select_hex(14,6, true, true)

==== wesnoth.scroll_to_tile ====

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter {{DevFeature1.11}}, the view instantly warps to the location regardless of the scroll speed setting in Preferences.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.lock_view ====

{{DevFeature1.11}} Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_tile still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

wesnoth.lock_view(true)
wesnoth.scroll_to_tile(12, 14, false, true)

==== wesnoth.view_locked ====

{{DevFeature1.11}} Returns a boolean indicating whether gamemap view scrolling is currently locked.

==== wesnoth.play_sound ====

Plays the given sound file once, optionally repeating it one or more more times if an integer value is provided as a second argument (note that the sound is ''repeated'' the number of times specified in the second argument, i.e. a second argument of 4 will cause the sound to be played once and then repeated four more times for a total of 5 plays. See the example below).

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

==== wesnoth.show_dialog ====

Displays a dialog box described by a WML table and returns:
* if the dialog was dismissed by a button click, the integer value associated to the button via the "return_value" keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the resolution section of a GUI window as described in [[GUIToolkitWML#Window_definition|GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))

==== wesnoth.set_dialog_value ====

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_active ====

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_canvas ====

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

==== wesnoth.get_displayed_unit ====

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.theme_items ====

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end

==== helper.get_user_choice ====

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

LuaWML/Display

2012-06-19T01:25:15Z

Artisticdude: /* wesnoth.play_sound */ Clarified the way the repetition argument is used in the function

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "<span color='#ff0000'>Ouch</span>")

==== wesnoth.get_time_of_day ====

Returns schedule information. First parameter (optional) is the turn number for which to return the information, if unspecified: the current turn ($turn_number). Second argument is an optional table. If present, first and second fields must be valid on-map coordinates and all current time_areas in the scenario are taken into account (if a time area happens to contain the passed hex). If the table isn't present, the scenario main schedule is returned. The table has an optional third parameter (boolean). If true (default: false), time of day modifying units (such as MoL) are taken into account (if the passed hex happens to be affected). The units placement being considered is always the current one.

wesnoth.get_time_of_day(2, { 37, 3, true })

The function returns a table with these named fields:
* '''id''': string (as in [time])
* '''lawful_bonus''': integer (as in [time])
* '''bonus_modified''': integer (bonus change by units)
* '''image''': string (tod image in sidebar)
* '''name''': translatable string
* '''red, green, blue''': integers (color adjustment for this time)

==== wesnoth.select_hex ====

Selects the given location in the game map as if the player would have clicked onto it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false)

wesnoth.select_hex(14,6, true, true)

==== wesnoth.scroll_to_tile ====

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter {{DevFeature1.11}}, the view instantly warps to the location regardless of the scroll speed setting in Preferences.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.lock_view ====

{{DevFeature1.11}} Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_tile still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

wesnoth.lock_view(true)
wesnoth.scroll_to_tile(12, 14, false, true)

==== wesnoth.view_locked ====

{{DevFeature1.11}} Returns a boolean indicating whether gamemap view scrolling is currently locked.

==== wesnoth.play_sound ====

Plays the given sound file once, optionally repeating it one or more more times if a integer is provided as a second argument (note that the sound is ''repeated'' the number of times specified in the second argument, i.e. a second argument of 4 will cause the sound to be played once and then repeated four more times. See the example below).

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

==== wesnoth.show_dialog ====

Displays a dialog box described by a WML table and returns:
* if the dialog was dismissed by a button click, the integer value associated to the button via the "return_value" keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the resolution section of a GUI window as described in [[GUIToolkitWML#Window_definition|GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))

==== wesnoth.set_dialog_value ====

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_active ====

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_canvas ====

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

==== wesnoth.get_displayed_unit ====

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.theme_items ====

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end

==== helper.get_user_choice ====

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

Creating Unit Art

2012-05-31T13:25:04Z

Artisticdude: Changed spellings of "colour" to "color", clarified some information

Here's the information needed to start doing units art for Wesnoth. Please update the wiki with links to examples and other tips and tricks realted to unit art. This page started from [http://www.wesnoth.org/forum/viewtopic.php?p=104809#104809 this forum thread].

''' The Medium '''

The medium used to create unit art is known as 'pixel art'. If you do not understand what pixel art is, or if you have only a general understanding of what it is, I suggest reading [http://www.pixeljoint.com/forum/forum_posts.asp?TID=11299 The Pixel Art Tutorial] by Cure. It is a tutorial comprised of a series of sequential forum posts on the www.pixeljoint.com forum and gives an in-depth overview of pixel art, explaining in detail what pixel art is and what it is not. Using other mediums (such as brush art) to create unit art is fine if you are creating unit art for [[WesnothAcronyms|UMC]] add-ons (although it is still strongly recommended that you use pixel art for the sake of consistency with mainline units), but only units drawn in pure pixel art will be accepted into mainline.

''' Basic unit image specifications '''

Wesnoth can only use two kinds of graphic files: PNGs, or JPEGs. JPEGs aren't suitable for unit images, because they can't store transparency data (and are lossy). Because of this, we always use PNGs for unit images.
*Final format: transparent PNG
** Color depth should be 24-bit (8 bits per RGB channel). This may be listed as "PNG-24" or "8-bit RGBA".
** Be aware that "Indexed color", "color map", or "PNG-8" is a different format. Although it might work in a buggy way, we strongly recommend you not use these.
* Canvas size is 72 x 72 pixels (it can actually be slightly wider, and can fit in the area of a hex and its immediately surrounding tiles, but try not to do this if at all possible, because it has performance and graphical glitch issues).
*All but exceptionally large units should be contained in the hex if possible (the white in the attached template)
*Compare the size of your unit to the size of similar existing core units
*Light comes from the artist's (''not'' the unit's!) upper right (for shading and highlights)
*Unit must look in the lower right (again, the artist's lower right, not the unit's) direction
*Units are centered horizontally
*Unit's feet are positioned around 55 pixel down from the top edge of the canvas, lower for taller units if necessary
*Shadows at 60 opacity, using a specific dark blue color (see [[Creating_Shadows_Under_Units|Creating Shadows Under Units]]).
*Outlines should be used, made with a darker, but similar color to what they're surrounding, this makes the unit feel bigger then the amount of pixels you'd use for the same with a black outline. Note that pure black (RGB #000000) should ''never'' be used to outline a sprite.
*Use consistent names for your files, beginning with the unit name, so that they are kept together when browsing the files. Try to imitate the naming scheme used for mainline units.

''' Unit animation specifications '''

You can have as many frames for animations as you like, and in fact, for any given cue, you can have more than one animation, which will be randomly chosen by the game. Images and animations must be done for:
*base frame (1 frame)
*attack for each type (at least 4 frames, about 6 frames is optimal depending on the type of attack and the weapon(s) involved)
*directional attacks (generally are desired for any attack that's a straight motion, rather than a slash. I.e. spears and thundersticks)
*defense (usually 2 frames long not including the base frame, separate animations may be drawn for ranged and melee defense animations)

''' Additional Notes '''

*Test early with different backgrounds. Go to your game terrain files, pick, say, 3 terrains, preferably with different colors, and have a look what they look like against the background, because that way if you have used alpha channels, it may look better in game than as the average standard sprite.

*Test your unit early in the game. Replacing an existing unit graphic with yours is the fastest way (be sure to make a copy of the originals so you don't lose them.)

*Test your unit next to mainline units in-game. This will help you ensure that your unit matches the style and proportions of the mainline units as closely as possible.

== See Also ==
* [[BuildingUnits]]
* [[Create]]
* [[Create Art and Music]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

AnimationWML

2012-04-27T16:22:44Z

Artisticdude: /* Field Description */ Clarified that directional_x and directional_y offsets are measured in pixels

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=<red, green, blue>
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255); this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_color=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_color=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit description block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelout ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

==== levelin ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:600" blend_color=255,255,255''

==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

WML for Complete Beginners

2012-04-14T21:09:34Z

Artisticdude: /* So What Exactly is WML? */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder about the purpose of this tutorial. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
The specific demographic for which this tutorial is intended is users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder paths and locate specific directories. In this tutorial you will learn the fundamentals of WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming in WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML (in fact, it is recommended that you ''avoid'' using those fancy word processors); a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without being required to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_first_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

Sometimes campaign authors only use mainline units in their campaigns. Other times, however, they may want to include a custom unit that isn't found in default Wesnoth. Thankfully, including a custom unit is quite easy.

===Creating Your Custom Unit's .cfg File===

===Including the Custom Unit In Your Campaign===

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

WML for Complete Beginners

2012-04-14T21:08:43Z

Artisticdude: /* Introduction */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder about the purpose of this tutorial. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
The specific demographic for which this tutorial is intended is users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder paths and locate specific directories. In this tutorial you will learn the fundamentals of WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming in WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML (in fact, it is recommended that you ''avoid'' using those fancy word processors); a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_first_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

Sometimes campaign authors only use mainline units in their campaigns. Other times, however, they may want to include a custom unit that isn't found in default Wesnoth. Thankfully, including a custom unit is quite easy.

===Creating Your Custom Unit's .cfg File===

===Including the Custom Unit In Your Campaign===

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

WML for Complete Beginners

2012-04-14T21:03:30Z

Artisticdude: /* Chapter 6: Building and Including a Custom Unit */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder what the purpose of this tutorial is. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
This tutorial is aimed at users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder directories. In this tutorial you will learn WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML; a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_first_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

Sometimes campaign authors only use mainline units in their campaigns. Other times, however, they may want to include a custom unit that isn't found in default Wesnoth. Thankfully, including a custom unit is quite easy.

===Creating Your Custom Unit's .cfg File===

===Including the Custom Unit In Your Campaign===

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

WML for Complete Beginners

2012-04-14T20:52:23Z

Artisticdude: /* The Campaign Folder */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder what the purpose of this tutorial is. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
This tutorial is aimed at users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder directories. In this tutorial you will learn WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML; a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_first_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

Create Art

2012-04-11T14:10:47Z

Artisticdude: /* Sprite Art */

{| style="float:right; margin-left:1em;"
|__TOC__
|}

Graphic artists working on artwork intended for mainline Wesnoth usually meet on the [http://forums.wesnoth.org/viewforum.php?f=9 Art Contributions forum] or on the [http://forums.wesnoth.org/viewforum.php?f=18 restricted Art Development forum] ("restricted" meaning that only those users with special permissions - such as art contributors and developers - can post there). The former is a great place to post and discuss new and current mainline Wesnoth art and graphics, and the latter to see what the art development team is working on. Artists working on graphics for [[WesnothAcronyms|UMC]] add-ons meet in the [http://forums.wesnoth.org/viewforum.php?f=23 Art Workshop forum].

Unit and terrain art is stored in the lossless ''Portable Network Graphics'' (PNG) format. Each frame of a unit animation, and each variation of a terrain is stored as a separate .png file in ''data/core/images'' under the [[EditingWesnoth#Where_is_my_game_data_directory.3F|main data directory]] of the game, and generally these files will be 72 x 72 pixels (the size of Wesnoth's basic hexagonal tile) with an alpha channel (a part of the file that indicates how transparent each pixel is). When creating your own images, you can test them without overwriting any game data by putting them in your [[EditingWesnoth#Where_is_my_user_data_directory.3F|user data directory]]. The game also supports JPEG images, although these are better suited for story art.

To edit these graphics, you'll need some program capable of creating PNG's - some of the programs in the following list are free, open-source software, and will do the job nicely: [[Art Programs]]

If you need some inspiration, we have a (no longer maintained) [[GraphicLibrary|Graphics Library]] which collects art posted on the forum. You can use this for ideas, and as a scrap heap for different parts of unit images (a technique described [[Give Your Hero A Personality|here]]).

== Art Tutorials ==

These are a work-in-progress, and describe both how to make art fit into Wesnoth's style, as well as giving some considerable tips on drawing in general. Especially useful is the [[External Tutorials]] page which lists a large number of art tutorials available on the web.

=== General Art and Computer Graphics ===
* [[Using the Levels Adjustment]] - How to make scanned pencil drawings ''not'' look washed out.
* [[Extending dynamic range]] - The Grooviest (so far) tutorial about extending the dynamic range of images and how this technique can be used to make better scans of pencil drawings.
* [[Scanning with camera]] - How to transfer real-life art to computer using a digital camera instead of a scanner.
* [[Art Supplies]] - What physical items you need to do larger cell-shaded art like that of Jetrel/Jormungadr/et al.
* [[Inking With Pencils|Computer Inking a Sketch]] - Info from Jason Lutes on his portrait workflow.
* [[Scaling Digital Images]] - How to properly resize an image on a computer.
* [[How to Shade]] - An attempt at tackling a very complicated topic.
* [[Cartography for Wesnoth|How to make Wesnoth-style Maps ]] - Kestenvarn's tricks of the trade.
* [[Designing weapons and armour]] - Advice from zookeeper on designing realistic weapons for your characters.
* [[Portrait Tutorial]] - A guide on how to draw unit/character portraits by Kitty.
* [[Armour_Tutorial]] A tutorial on how to shade metallic armour by LordBob.
====Vector Art====
Sgt. Groovy's vector workshop - Tips and tricks for drawing with Inkscape.
:* [[Z-order tricks]] - A few methods for faking overlapping shapes.
:* [[Variable-width strokes]] - How to make the strokes vary in width, like being drawn with a flat-tipped pen — no tablet needed!
:* [[Shaped gradients with Gaussian blur]] - How to make gradients in other shapes than linear or radial.
:* [[Smooth shading in vector]] - The basic vector techniques for smooth shading, employing Gaussian blur and clipping/masking.
:* [[Vector Inking]] - Vector techniques, including mouse-only, for inking your sketches.
:* [[Making portrait art in vector]] - A complete tutorial for making Wesnoth unit portraits in vector graphics.

=== [[Terrain|Terrain Graphics]] ===

The following is information specific to drawing terrain for Wesnoth. Read Frame's "Tiles Tutorial" for a good overview of how terrain graphics work.

* [[Mesilliac's Essay on Terrain Perspective]] - The geometry behind the perspective used for terrain tiles in Wesnoth.
* [[Tiles Tutorial]] - Frame's tutorial describing the process of making terrain tiles in Wesnoth, and how they interact with adjacent tiles.
* [[How To Make Seamless Tiles]] - The tutorial is aimed at Photoshop users, but the technique is similar with GIMP.
* [[Seamless Tiles Using Inkscape]] - This tutorial teaches a method for making seamless hex tiles in vector craphics (to be rendered in raster).
* [[Turning Square Tiles into Hex]] - Nifty tricks for transforming square (or any rectangle) shaped seamless tiles into hexagon seamless tiles.
* [[CastleTutorial|Castle Tutorial]] - A description of how Wesnoth's castle tiles work (needs updating, but useful nonetheless).
* [[MultiHexTutorial|Multi-Hex Tiling Tutorial]] - A description of how multi-hex tiles work.
* [[Editing Castles]] - Instructions for how to make/edit castles (and other corner-based terrains) using yobbo's GIMP script.

These describe the system used to specify how terrains behave in game:
* [[TerrainCodesWML]] - A list of the letters used to represent terrain types.
* [[TerrainGraphicsWML]] - If you really need to get technical, start here.
* [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml Ayin's Terrain Graphics document] - If you really, ''really'' need to get technical, this describes the terrain graphics WML system in depth.

=== Sprite Art ===
The following are different tutorials about sprite work compiled by various Wesnoth sprite artists. These will give you the most specific-to-Wesnoth information about making sprites, and are well worth a read.

* [[Creating Unit Art]] - A list of specifications you will need to match.
* [[Give Your Hero A Personality]] - Tricks for editing existing images, including some clip art.
* [[Team Color Shifting]] - How to create art that uses our new team color system.
* [[TeamColoring]] - How to automatically team-color sprites to see what they look like in various colors.
* [[Creating Shadows Under Units]] - How we create the shadows for the units in-game.
* [[How to Anti-Alias Sprite Art]] - A means of removing the jagged edges on pixel lines.
* [[Rotate Pixel Art Without Blurring]]
* [http://forums.wesnoth.org/download/file.php?id=56284 Zerovirus's Spriting Workflow] - Wesnoth artist Zerovirus explains step-by-step his methodology for creating Wesnoth sprites from scratch (.png file).
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
* [[FrankenPacks]] - A quick and dirty way to create sprites for [[WesnothAcronyms|UMC]].
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
====Animation====
:* [[Basic Animation Tutorial]] - Or "How to Animate Sprites for Dummies," covering the basic theory, and all of the mistakes to avoid.
:* [[From Base Frame To Full Animation]] - A solid method of moving baseframes forward towards full animation.
:* [[How to create motion blurs]] - A simple explanation on how to create attack animation weapon blurs.
:* [[Making Bow Animations]] - The current standard for how we want bow animations to work.
:* [[Fire Animation]] - A great guide to creating fire FX by rhyging5.

=== External Tutorials ===
The following page contains dozens of links to tutorials covering all manner of artwork, including sprite art. These were not made by Wesnoth artists, but should prove very useful for general instruction.

* [[External Tutorials]]

== See Also ==
* [[Create]]
* [[EditingWesnoth]]
* [[GraphicLibrary]] - Lots of usercontributed graphics (most should be GPL'ed)
* [[Project]]
* [http://wesnoth.dbzer0.com/blog/wpg2 External Graphic Library] - A project to better organize the art of Wesnoth.

[[Category:Art Tutorials]]

Create Art

2012-04-11T14:10:08Z

Artisticdude:

{| style="float:right; margin-left:1em;"
|__TOC__
|}

Graphic artists working on artwork intended for mainline Wesnoth usually meet on the [http://forums.wesnoth.org/viewforum.php?f=9 Art Contributions forum] or on the [http://forums.wesnoth.org/viewforum.php?f=18 restricted Art Development forum] ("restricted" meaning that only those users with special permissions - such as art contributors and developers - can post there). The former is a great place to post and discuss new and current mainline Wesnoth art and graphics, and the latter to see what the art development team is working on. Artists working on graphics for [[WesnothAcronyms|UMC]] add-ons meet in the [http://forums.wesnoth.org/viewforum.php?f=23 Art Workshop forum].

Unit and terrain art is stored in the lossless ''Portable Network Graphics'' (PNG) format. Each frame of a unit animation, and each variation of a terrain is stored as a separate .png file in ''data/core/images'' under the [[EditingWesnoth#Where_is_my_game_data_directory.3F|main data directory]] of the game, and generally these files will be 72 x 72 pixels (the size of Wesnoth's basic hexagonal tile) with an alpha channel (a part of the file that indicates how transparent each pixel is). When creating your own images, you can test them without overwriting any game data by putting them in your [[EditingWesnoth#Where_is_my_user_data_directory.3F|user data directory]]. The game also supports JPEG images, although these are better suited for story art.

To edit these graphics, you'll need some program capable of creating PNG's - some of the programs in the following list are free, open-source software, and will do the job nicely: [[Art Programs]]

If you need some inspiration, we have a (no longer maintained) [[GraphicLibrary|Graphics Library]] which collects art posted on the forum. You can use this for ideas, and as a scrap heap for different parts of unit images (a technique described [[Give Your Hero A Personality|here]]).

== Art Tutorials ==

These are a work-in-progress, and describe both how to make art fit into Wesnoth's style, as well as giving some considerable tips on drawing in general. Especially useful is the [[External Tutorials]] page which lists a large number of art tutorials available on the web.

=== General Art and Computer Graphics ===
* [[Using the Levels Adjustment]] - How to make scanned pencil drawings ''not'' look washed out.
* [[Extending dynamic range]] - The Grooviest (so far) tutorial about extending the dynamic range of images and how this technique can be used to make better scans of pencil drawings.
* [[Scanning with camera]] - How to transfer real-life art to computer using a digital camera instead of a scanner.
* [[Art Supplies]] - What physical items you need to do larger cell-shaded art like that of Jetrel/Jormungadr/et al.
* [[Inking With Pencils|Computer Inking a Sketch]] - Info from Jason Lutes on his portrait workflow.
* [[Scaling Digital Images]] - How to properly resize an image on a computer.
* [[How to Shade]] - An attempt at tackling a very complicated topic.
* [[Cartography for Wesnoth|How to make Wesnoth-style Maps ]] - Kestenvarn's tricks of the trade.
* [[Designing weapons and armour]] - Advice from zookeeper on designing realistic weapons for your characters.
* [[Portrait Tutorial]] - A guide on how to draw unit/character portraits by Kitty.
* [[Armour_Tutorial]] A tutorial on how to shade metallic armour by LordBob.
====Vector Art====
Sgt. Groovy's vector workshop - Tips and tricks for drawing with Inkscape.
:* [[Z-order tricks]] - A few methods for faking overlapping shapes.
:* [[Variable-width strokes]] - How to make the strokes vary in width, like being drawn with a flat-tipped pen — no tablet needed!
:* [[Shaped gradients with Gaussian blur]] - How to make gradients in other shapes than linear or radial.
:* [[Smooth shading in vector]] - The basic vector techniques for smooth shading, employing Gaussian blur and clipping/masking.
:* [[Vector Inking]] - Vector techniques, including mouse-only, for inking your sketches.
:* [[Making portrait art in vector]] - A complete tutorial for making Wesnoth unit portraits in vector graphics.

=== [[Terrain|Terrain Graphics]] ===

The following is information specific to drawing terrain for Wesnoth. Read Frame's "Tiles Tutorial" for a good overview of how terrain graphics work.

* [[Mesilliac's Essay on Terrain Perspective]] - The geometry behind the perspective used for terrain tiles in Wesnoth.
* [[Tiles Tutorial]] - Frame's tutorial describing the process of making terrain tiles in Wesnoth, and how they interact with adjacent tiles.
* [[How To Make Seamless Tiles]] - The tutorial is aimed at Photoshop users, but the technique is similar with GIMP.
* [[Seamless Tiles Using Inkscape]] - This tutorial teaches a method for making seamless hex tiles in vector craphics (to be rendered in raster).
* [[Turning Square Tiles into Hex]] - Nifty tricks for transforming square (or any rectangle) shaped seamless tiles into hexagon seamless tiles.
* [[CastleTutorial|Castle Tutorial]] - A description of how Wesnoth's castle tiles work (needs updating, but useful nonetheless).
* [[MultiHexTutorial|Multi-Hex Tiling Tutorial]] - A description of how multi-hex tiles work.
* [[Editing Castles]] - Instructions for how to make/edit castles (and other corner-based terrains) using yobbo's GIMP script.

These describe the system used to specify how terrains behave in game:
* [[TerrainCodesWML]] - A list of the letters used to represent terrain types.
* [[TerrainGraphicsWML]] - If you really need to get technical, start here.
* [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml Ayin's Terrain Graphics document] - If you really, ''really'' need to get technical, this describes the terrain graphics WML system in depth.

=== Sprite Art ===
The following are different tutorials about sprite work compiled by various Wesnoth sprite artists. These will give you the most specific-to-Wesnoth information about making sprites, and are well worth a read.

* [[Creating Unit Art]] - A list of specifications you will need to match.
* [[Give Your Hero A Personality]] - Tricks for editing existing images, including some clip art.
* [[Team Color Shifting]] - How to create art that uses our new team color system.
* [[TeamColoring]] - How to automatically team-color sprites to see what they look like in various colors.
* [[Creating Shadows Under Units]] - How we create the shadows for the units in-game.
* [[How to Anti-Alias Sprite Art]] - A means of removing the jagged edges on pixel lines.
* [[Rotate Pixel Art Without Blurring]]
* [http://forums.wesnoth.org/download/file.php?id=56284 Zerovirus's Spriting Workflow] - Wesnoth artist Zerovirus explains step-by-step his methodology for creating Wesnoth sprites (.png file)
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
* [[FrankenPacks]] - A quick and dirty way to create sprites for [[WesnothAcronyms|UMC]].
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
====Animation====
:* [[Basic Animation Tutorial]] - Or "How to Animate Sprites for Dummies," covering the basic theory, and all of the mistakes to avoid.
:* [[From Base Frame To Full Animation]] - A solid method of moving baseframes forward towards full animation.
:* [[How to create motion blurs]] - A simple explanation on how to create attack animation weapon blurs.
:* [[Making Bow Animations]] - The current standard for how we want bow animations to work.
:* [[Fire Animation]] - A great guide to creating fire FX by rhyging5.

=== External Tutorials ===
The following page contains dozens of links to tutorials covering all manner of artwork, including sprite art. These were not made by Wesnoth artists, but should prove very useful for general instruction.

* [[External Tutorials]]

== See Also ==
* [[Create]]
* [[EditingWesnoth]]
* [[GraphicLibrary]] - Lots of usercontributed graphics (most should be GPL'ed)
* [[Project]]
* [http://wesnoth.dbzer0.com/blog/wpg2 External Graphic Library] - A project to better organize the art of Wesnoth.

[[Category:Art Tutorials]]

Art Programs

2012-04-09T17:16:41Z

Artisticdude:

{| style="float:right; margin-left:1em;"
|__TOC__
|}
'''Big Note:''' It is mostly-possible to make wesnoth graphics with nothing more than MSPaint or Appleworks. However, there are two major and '''vital''' things lacking in those programs - first, these programs cannot make images with transparent pixels, and second, they may not be able to save in the PNG format used by Wesnoth. A program capable of those will have to be applied to images made with MSPaint when they are finished.

=== Free Image Editors ===
The following are free image editing programs which can be used to create graphics for wesnoth. These programs are Open-Source Software, like wesnoth, meaning they are free to use, and that you are free to look at the sourcecode.

[http://www.gimp.org '''The GIMP'''] (Windows, Linux & Mac OS X); the "Gnu Image Manipulation Program" is recommended.

[http://seashore.sourceforge.net/ '''Seashore'''] (Mac OS X) this port of the the GIMP to a cocoa-based gui is recommended. Seashore provides the basic features of GIMP.

[http://www.opensword.org/ '''Pixen'''] (Mac OS X) is the OpenSword Group's tool for traditional SNES style sprite art - unlike most other editors, it has been designed for that specific task, and users may find it much less daunting than the Gimp or Photoshop. This program was written in cocoa, and has a very good interface - version 3 will even include built-in support for making animations.

[http://jdraw.sourceforge.net/index.php?page=6'''JDraw'''] (for anything that can run Java - mac and windows included) is an image editor which has a subset of the features of Pixen, and a superset of the features of MSPaint. It is a simple, straightforward pixel editing program. If you use a mac, Pixen is probably a better idea.

[http://www.eecs.wsu.edu/paint.net/ '''Paint.net'''] (Windows) is generally regarded as inferior to the Gimp or Photoshop, but is easier to look at for those with shorter attention spans, so some might find it of interest.

[http://ase.sourceforge.net/ '''Allegro Sprite Editor'''] (Windows and Linux) is a sprite editing program. Free/OSS, note that it is NOT capable of saving PNGs.

[http://paintbrush.sourceforge.net/ '''Paintbrush'''] (Mac OS X) is a program intended to be a slightly modernized clone of the old MacPaint/MSPaint. Free/OSS, but note that though it is capable of saving PNGs, it is not capable of handling transparency.

=== Free Image Post-Processors ===

[http://www.amake.us/software/pngcrusher/ '''PNGCrusher'''] (Mac OS X) is a handy lightweight tool that will compress your PNGs much more efficiently than Photoshop. It is best used in tandem with saving the files from GraphicConverter, with the PNG filtering options on. The tool it is based on, OptiPNG, is open source, and runs on both linux and windows.

[http://imageoptim.pornel.net/ '''ImageOptim'''] (Mac OS X) optimizes images so they take up less disk space and load faster. It provides GUI for various optimisation tools: AdvPNG from AdvanceCOMP, OptiPNG, Pngcrush, JpegOptim, jpegtran from libjpeg, Gifsicle and optionally PNGOUT.

=== Proprietary Image Editors ===

==== Shareware ====
[http://www.lemkesoft.de/ '''GraphicConverter'''] (Mac OS X) by Lemkesoft is an excellent program for preparing and compressing png images for the game, and may also be useful for the creation of images. The shareware fee is $30, although large parts of the program are fully functional for free.

[http://www.kanzelsberger.com/pixel/ '''Pixel Image Editor'''] (Mac OS X, Windows, Linux, BeOS, and others) is a very full-featured program, intended to fulfill the same function that photoshop does. It currently has a shareware fee of $32, though the final price once the product reaches v2.0, will be $79.

[http://www.ultimatepaint.com/ '''JTL Ultimate Paint'''] (Windows) is a basic painting program, following the tradition of the earlier "DeluxePaint". Geared at painting, it can use photoshop plugins. It currently costs $34 for a basic version. I do not know if this program can export PNG images, so ''caveat emptor''.

[http://www.cosmigo.com/promotion/ '''Pro Motion'''] (Windows) is a commercial pixel editing program. It has many features tailored for animation and seamless square-tile creation, as well as features designed to ease the creation of images that would run in a game on the Game Boy Advance or a Mobile Phone platform. The price of the normal version is $78.

[http://www.humanbalance.net/gale/us/index.html '''GraphicsGale'''] (Windows) is a pixel editing program designed for animation. It has both a freeware version, and a 1995¥ (roughly $20) shareware version. Be warned that it can '''not''' save files in the PNG format.

==== Non-shareware ====
[http://www.adobe.com/ '''Photoshop or Photoshop Elements'''] (Windows and Mac OS X), these industry standard Adobe applications are available for approximately USD $100 and $700, respectively, depending on what version of the software you purchase and where you purchase it. You may be able acquire the use of these programs through a business or academic situation. Adobe Photoshop is extremely powerful, and is more than capable of some very advanced sprite techniques which elude simple bitmap programs - the price, however, can be a barrier to entry for some contributors. More advanced (and therefore more expensive) version of Photoshop should have little advantage over Elements (the entry-level version, usually available for approximately USD $100) for creating unit and terrain art. Photoshop (and presumably Elements) does not compactly save PNG files. For space savings, Adobe users are recommended to resave final PNGs through Adobe's companion application ImageReady, or another application such as GraphicConverter or PNGCrusher. Note - the ImageReady compression can also be used by saving the files through the "Save for Web..." menu command within Photoshop, if ImageReady is installed.

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

WML for Complete Beginners

2012-04-05T14:18:57Z

Artisticdude: /* Cases */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder what the purpose of this tutorial is. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
This tutorial is aimed at users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder directories. In this tutorial you will learn WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML; a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

WML for Complete Beginners

2012-04-05T14:11:07Z

Artisticdude: /* The Toplevel Tagset and Attributes */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder what the purpose of this tutorial is. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
This tutorial is aimed at users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder directories. In this tutorial you will learn WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML; a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario (including underscores, capitalization, spelling, etc.), otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without. Instead of using multiple [if] codeblocks, you could simply use the switch/case codeblock to evaluate the value of a variable and determine the action performed as a result of the evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

WML for Complete Beginners

2012-04-05T14:07:45Z

Artisticdude: /* The Text Domain */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder what the purpose of this tutorial is. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
This tutorial is aimed at users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder directories. In this tutorial you will learn WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML; a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario, otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without. Instead of using multiple [if] codeblocks, you could simply use the switch/case codeblock to evaluate the value of a variable and determine the action performed as a result of the evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

Create Art

2012-03-28T19:27:57Z

Artisticdude:

{| style="float:right; margin-left:1em;"
|__TOC__
|}

Graphic artists working on artwork intended for mainline Wesnoth usually meet on the [http://forums.wesnoth.org/viewforum.php?f=9 Art Contributions forum] or on the [http://forums.wesnoth.org/viewforum.php?f=18 restricted Art Development forum] ("restricted" meaning that only those users with special permissions - such as art contributors and developers - can post there). The former is a great place to post and discuss new and current mainline Wesnoth art and graphics, and the latter to see what the art development team is working on. Artists working on graphics for [[WesnothAcronyms|UMC]] add-ons meet in the [http://forums.wesnoth.org/viewforum.php?f=23 Art Workshop forum].

Unit and terrain art is stored in the lossless ''Portable Network Graphics'' (PNG) format. Each frame of a unit animation, and each variation of a terrain is stored as a separate .png file in ''data/core/images'' under the [[EditingWesnoth#Where_is_my_game_data_directory.3F|main data directory]] of the game, and generally these files will be 72 x 72 pixels (the size of Wesnoth's basic hexagonal tile) with an alpha channel (a part of the file that indicates how transparent each pixel is). When creating your own images, you can test them without overwriting any game data by putting them in your [[EditingWesnoth#Where_is_my_user_data_directory.3F|user data directory]]. The game also supports JPEG images, although these are better suited for story art.

To edit these graphics, you'll need some program capable of creating PNG's - some of the programs in the following list are free, open-source software, and will do the job nicely: [[Art Programs]]

If you need some inspiration, we have a (no longer maintained) [[GraphicLibrary|Graphics Library]] which collects art posted on the forum. You can use this for ideas, and as a scrap heap for different parts of unit images (a technique described [[Give Your Hero A Personality|here]]).

== Art Tutorials ==

These are a work-in-progress, and describe both how to make art fit into Wesnoth's style, as well as giving some considerable tips on drawing in general. Especially useful is the [[External Tutorials]] page which lists a large number of art tutorials available on the web.

=== General Art and Computer Graphics ===
* [[Using the Levels Adjustment]] - How to make scanned pencil drawings ''not'' look washed out.
* [[Extending dynamic range]] - The Grooviest (so far) tutorial about extending the dynamic range of images and how this technique can be used to make better scans of pencil drawings.
* [[Scanning with camera]] - How to transfer real-life art to computer using a digital camera instead of a scanner.
* [[Art Supplies]] - What physical items you need to do larger cell-shaded art like that of Jetrel/Jormungadr/et al.
* [[Inking With Pencils|Computer Inking a Sketch]] - Info from Jason Lutes on his portrait workflow.
* [[Scaling Digital Images]] - How to properly resize an image on a computer.
* [[How to Shade]] - An attempt at tackling a very complicated topic.
* [[Cartography for Wesnoth|How to make Wesnoth-style Maps ]] - Kestenvarn's tricks of the trade.
* [[Designing weapons and armour]] - Advice from zookeeper on designing realistic weapons for your characters.
* [[Portrait Tutorial]] - A guide on how to draw unit/character portraits by Kitty.
* [[Armour_Tutorial]] A tutorial on how to shade metallic armour by LordBob.
====Vector Art====
Sgt. Groovy's vector workshop - Tips and tricks for drawing with Inkscape.
:* [[Z-order tricks]] - A few methods for faking overlapping shapes.
:* [[Variable-width strokes]] - How to make the strokes vary in width, like being drawn with a flat-tipped pen — no tablet needed!
:* [[Shaped gradients with Gaussian blur]] - How to make gradients in other shapes than linear or radial.
:* [[Smooth shading in vector]] - The basic vector techniques for smooth shading, employing Gaussian blur and clipping/masking.
:* [[Vector Inking]] - Vector techniques, including mouse-only, for inking your sketches.
:* [[Making portrait art in vector]] - A complete tutorial for making Wesnoth unit portraits in vector graphics.

=== [[Terrain|Terrain Graphics]] ===

The following is information specific to drawing terrain for Wesnoth. Read Frame's "Tiles Tutorial" for a good overview of how terrain graphics work.

* [[Mesilliac's Essay on Terrain Perspective]] - The geometry behind the perspective used for terrain tiles in Wesnoth.
* [[Tiles Tutorial]] - Frame's tutorial describing the process of making terrain tiles in Wesnoth, and how they interact with adjacent tiles.
* [[How To Make Seamless Tiles]] - The tutorial is aimed at Photoshop users, but the technique is similar with GIMP.
* [[Seamless Tiles Using Inkscape]] - This tutorial teaches a method for making seamless hex tiles in vector craphics (to be rendered in raster).
* [[Turning Square Tiles into Hex]] - Nifty tricks for transforming square (or any rectangle) shaped seamless tiles into hexagon seamless tiles.
* [[CastleTutorial|Castle Tutorial]] - A description of how Wesnoth's castle tiles work (needs updating, but useful nonetheless).
* [[MultiHexTutorial|Multi-Hex Tiling Tutorial]] - A description of how multi-hex tiles work.
* [[Editing Castles]] - Instructions for how to make/edit castles (and other corner-based terrains) using yobbo's GIMP script.

These describe the system used to specify how terrains behave in game:
* [[TerrainCodesWML]] - A list of the letters used to represent terrain types.
* [[TerrainGraphicsWML]] - If you really need to get technical, start here.
* [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml Ayin's Terrain Graphics document] - If you really, ''really'' need to get technical, this describes the terrain graphics WML system in depth.

=== Sprite Art ===
The following are different tutorials about sprite work compiled by various Wesnoth sprite artists. These will give you the most specific-to-Wesnoth information about making sprites, and are well worth a read.

* [[Creating Unit Art]] - A list of specifications you will need to match.
* [[Give Your Hero A Personality]] - Tricks for editing existing images, including some clip art.
* [[Team Color Shifting]] - How to create art that uses our new team color system.
* [[TeamColoring]] - How to automatically team-color sprites to see what they look like in various colors.
* [[Creating Shadows Under Units]] - How we create the shadows for the units in-game.
* [[How to Anti-Alias Sprite Art]] - A means of removing the jagged edges on pixel lines.
* [[Rotate Pixel Art Without Blurring]]
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
* [[FrankenPacks]] - A quick and dirty way to create sprites for [[WesnothAcronyms|UMC]].
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
====Animation====
:* [[Basic Animation Tutorial]] - Or "How to Animate Sprites for Dummies," covering the basic theory, and all of the mistakes to avoid.
:* [[From Base Frame To Full Animation]] - A solid method of moving baseframes forward towards full animation.
:* [[How to create motion blurs]] - A simple explanation on how to create attack animation weapon blurs.
:* [[Making Bow Animations]] - The current standard for how we want bow animations to work.
:* [[Fire Animation]] - A great guide to creating fire FX by rhyging5.

=== External Tutorials ===
The following page contains dozens of links to tutorials covering all manner of artwork, including sprite art. These were not made by Wesnoth artists, but should prove very useful for general instruction.

* [[External Tutorials]]

== See Also ==
* [[Create]]
* [[EditingWesnoth]]
* [[GraphicLibrary]] - Lots of usercontributed graphics (most should be GPL'ed)
* [[Project]]
* [http://wesnoth.dbzer0.com/blog/wpg2 External Graphic Library] - A project to better organize the art of Wesnoth.

[[Category:Art Tutorials]]

External Tutorials

2012-03-26T14:11:26Z

Artisticdude: /* Sprite Art */ Added link to Neoriceisgood's mini-tutorial (a .png file hosted on deviantart) on his sprite workflow

{| style="float:right; margin-left:1em;"
|__TOC__
|}

On this page, there are links to several tutorials covering all manner of artwork, including sprite art. No guarantees on how long the links will last, but then, the beauty of using a wiki is that anyone can submit corrections to them. Hopefully, this should provide a very good base of knowledge to work from. None of these can substitute for practice, rather these exist to guide your practice, and help it to improve your skill rapidly, rather than having you flog away at simple cartoon forms for years and not learn anything.

As stated in some of Jetrel's other tutorials here, ''do not'' jump into the sprite tutorials and ignore the works on general or figure drawing. If you intend to draw sprites well, the ability to draw and visualize the subject in a general sense is an absolute prerequisite. Without exception, the best sprite artists are such because they have good basic art skills; understanding of shading, light, proportion, edging, foreshortening, etc.

You can't fake those - even if you never practice anything but spritework, the tutorials for "higher art" are very applicable, and will improve your spriting skill considerably.

== General Art Instruction ==

Andrew Loomis is a master of his field. ''READ HIS BOOKS.'' They are classics, and are of pristine educational calibre, but unfortunately have been out of print for a long time now and will not enter the public domain any time soon. If you have any interest in drawing human beings though, they will help you more than the rest of the tutorials on this page, combined.

Copies are highly priced and hard to find in most cases, however due to demand pirated copies are widely available online. While we don't endorse piracy, his books are a great resource and should not be missed.

I personally recommend starting with "Fun with a Pencil" and "Figure Drawing for all it's Worth".

http://acid.noobgrinder.com/Loomis/

For anatomy George B. Bridgman actually taught Andrew Loomis and is was well regarded for his contributions to art education, his books are still in print and pretty cheap, if you can pick up the smaller individual books I highly recommend doing so, "Bridgman's Complete Guide to Drawing from Life" is a large collection comprising of most of the same drawings and text but due to the changed order and layout is not nearly as good as the originals, luckily some of them have recently entered the public domain and are available from the Internet Archive.

"Constructive Anatomy" seems a good place to start, "The Human Machine" is much more useful as a reference.

http://www.archive.org/details/constructiveanat00briduoft

http://www.archive.org/details/humanmachinethea009564mbp

Condensed human figure tutorial by DeviantArt member coelasquid.

http://coelasquid.deviantart.com/art/How-to-draw-all-sorts-of-crap-104342407

The Kodak company made the following, very comprehensive introduction to composition. These rules apply to pictures as well, and will help you when laying out the subjects in a picture.

http://asp.photo.free.fr/Composition/photoProgramCompMainClass.shtml

The following site has a very high-level and overbearing tutorial on color theory. It's quite useful to experts, but will probably confuse a beginner.

http://handprint.com/HP/WCL/wcolor.html

Itchy Animation has, amongst other things, a tutorial on the rarely-covered subject of the behaviour of light and its effects on color (rarely covered from an artists' perspective, that is).

http://www.itchy-animation.co.uk/

http://www.itchy-animation.co.uk/tutorials/light01.htm

GFXartist.com has several tutorials from different artists, including the painter Craig Mullins, who has, for nearly a decade, been the favorite artist of wesnoth's art slave "Jetrel," and has a good chance of keeping that position for the rest of either fellow's time on this earth. (J- I can't say enough good things about that guy; I would honestly rank him among the greats, like Rembrandt, or Picasso - he's *that* good. The tutorials posted on that site do him little justice - for a better sample, his personal site is http://www.goodbrush.com/ , which has over a thousand of his works.)

http://www.gfxartist.com/features/tutorials

The excellent pencil artist Mike Sibley has a series of tutorials on techniques he uses on his site. Though some are a bit specific to drawing with graphite, his discussion of negative drawing is very useful to any artist.

http://www.sibleyfineart.com/index.htm?tipsndx.htm

The following website, titled "portrait-artist.org", offers quite a few good tutorials on portrait drawing. Though it might not live up to the 'tall order' implied by its name, it's fairly comprehensive:

http://www.portrait-artist.org/

An excellent skin tutorial by DeviantArt member acidlullaby.

http://acidlullaby.deviantart.com/art/Skin-Tutorial-90966884

This website already features a couple of great painting tutorials and has potential to grow.

http://www.outofpaint.com

== Tutorials on using Computer Graphics Software ==

Good-tutorials.com has over 8000 various tutorials covering different aspects of the popular program, "Adobe® Photoshop®."

http://www.good-tutorials.com/

The official collection of GIMP tutorials on www.gimp.org. Includes tutorials for users of all skill levels, from beginner through expert.

http://www.gimp.org/tutorials/

== Sprite Art ==

The medium used to create sprite art is known as 'pixel art'. If you do not understand what pixel art is, or if you have only a general understanding of what it is, I suggest reading [http://www.pixeljoint.com/forum/forum_posts.asp?TID=11299 The Pixel Art Tutorial] by Cure. It is comprised of a series of sequential forum posts on the www.pixeljoint.com forum and gives an in-depth overview of pixel art, explaining in detail what pixel art is and what it is not. Although aimed primarily at those who are new to pixel art, the tutorial can also be helpful to more advanced pixel artists.

An excellent pixel art tutorial that covers a lot of fundamental spriting and pixel art concepts, from sketching and selout to palettes and antialiasing. HIGHLY recommended for pixel artists of all skill levels.

http://purloux.com/artwork/tutorials/rundown/

A very worthwhile mini-tutorial by veteran spriter and pixel artist (and Wesnoth contributor) Neoriceisgood, in which he explains his spriting workflow step-by-step, from the initial sketch to the finished product. (Note: the tutorial is in the form of a 1208x1660 .png file.)

[http://fc01.deviantart.net/fs15/f/2007/063/e/a/How_to_make_sprite_by_Neoriceisgood.png How_to_make_sprite_by_Neoriceisgood.png]

Zoggles has a wealth of tutorials made by many different people, some good, some bad.

http://www.zoggles.co.uk/asp/tutorials.asp?show=index

A Russian site featuring several tutorials - you may need to click on the "English" link to view the site in a language you can understand, unless you have the privilege of knowing Russian.

http://www.gas13.ru/tutorials/

A fellow named mark posted several tutorials at the following site. Most of them are fairly decent:

http://www.natomic.com/hosted/marks/mpat/

The following is a forum post on some spriting forum containing a list of links to different pixel tutorials. Some are of banal quality, your mileage may vary.

http://pixeljoint.com/forum/forum_posts.asp?TID=706&PN=1

== Animation ==

Carin Perron has posted an excellent tutorial on the basic principles of animation.

http://www.writer2001.com/animprin.htm

A very worthwhile tutorial on creating walking animations, covers essential details such as rotation, movement arcs, etc.

http://www.angryanimator.com/word/2010/11/26/tutorial-2-walk-cycle/

Another walking animation tutorial:

http://www.dungeoncraftgame.com/blog/?p=39#more-39

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

WML for Complete Beginners

2012-03-14T23:38:50Z

Artisticdude: /* Chapter 5: Events */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder what the purpose of this tutorial is. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
This tutorial is aimed at users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder directories. In this tutorial you will learn WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML; a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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 attributes 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario, otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

(list these events: prestart, start, moveto, time over, die, last breath)

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without. Instead of using multiple [if] codeblocks, you could simply use the switch/case codeblock to evaluate the value of a variable and determine the action performed as a result of the evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!

WML for Complete Beginners

2012-03-14T23:28:14Z

Artisticdude: /* Attributes */

'''Template for future "WML for Complete Beginners" tutorial'''

'''Note: this is a work in progress.'''
-------------

TODO:

1. Move the "objectives" section and make it a subsection of the "events" section, since objectives are defined within a prestart event.
2. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question)

-------------

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding before you read this tutorial.

Some people may wonder what the purpose of this tutorial is. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
This tutorial is aimed at users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder directories. In this tutorial you will learn WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML; a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML.

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without having to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a [http://en.wikipedia.org/wiki/Markup_language markup language]. This means that the syntax of the entire language consists of two fundamental elements: tags and attributes.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try and use capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a "tagset". A tagset always contains exactly two tags: the opening tag and the closing tag. So the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here. Before we move on to the next section, let's review the points we've learned in this section about tags:

::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag except for the forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called the tagset.
::*A tagset consists of exactly two tags: the opening tag and the closing tag.

:So now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what kind of task to do, but without attributes to specify ''exactly'' what to do, the WML engine won't be able to do anything because you haven't given it enough specific information. This is just like if you told your friend to "Go": he'd understand that you want him to go somewhere, but he'd be unable to perform the task because he doesn't know where to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-transatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, you simply put an underscore in front of the string, before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is considered good syntax to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::although the game considers both to be equivalent, and will therefore recognize both as translatable strings.

::'''2. Numerical Strings'''

::Numerical strings, obviously, are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter X). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 12 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 16 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

==Chapter 2: The Userdata Directory and the Campaign Folder==

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

===The Userdata Directory===

There are two main directories that Wesnoth creates on your computer. The '''installation directory''' contains all the files for the core game. The '''userdata directory''' stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:

{| border="1"
!Windows XP
|~/My Documents/My Games/Wesnoth 1.10/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.10/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.10/
|-
!Linux
|~/.local/share/wesnoth/1.10/
|}

Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

====The data folder====

:The data folder is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

====The editor folder====

:The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

===The Campaign Folder===

Like I told you earlier, all add-ons are installed in the data folder inside the userdata directory. That means that your campaign will also be located inside the data folder. If you're not already there, enter the data folder now.

Next, create a new folder inside the data folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

==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). 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 attributes 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===
(discuss preprocessor directives, binary path, directory inclusion, etc.)

====Preprocessor Directives====

====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)

==Chapter 4: Creating Your First Scenario==

Now that you have your _main.cfg file, it's time to create your first scenario.

===Creating the Scenario Map===

All scenarios require a map in order to work. Open the Battle for Wesnoth application. On the mainmenu, you should see an option labeled "Map Editor". Click this option and wait for the editor to load.

By default, Wesnoth creates a blank map with the dimensions 44 x 33 (43 wide and 33 tall). These dimensions will work fine for our purposes, so we won't change them. Hover your cursor over the map and look at the center of the upper edge of the Battle for Wesnoth application window. You should see two numbers separated by a comma.

(screenshot)

These numbers are the X and Y coordinates of the hex over which your cursor is currently hovering. If you move your cursor to another hex, the coordinates will change to show the new location of your cursor. This is a fast and convenient way to locate coordinates on the map.

So we have a map, but let's face it: it's rather dull and uninteresting. Time to add some new terrain. Locate the terrain palette (the area at the far right of your Battle for Wesnoth window that displays the terrains you can use in the editor).

(screenshot)

Towards the top of this window, you should see the terrain category selection buttons. From here you can change what category of terrain is displayed in the terrain palette.

(screenshot)

First, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" terrain category button.

(screenshot of the castle terrain category button)

===Creating the Scenario .cfg File===

Create a new text file in the "scenarios" folder inside your campaign folder. Name this new text file "my_first_scenario.cfg". Open the "my_first_scenario.cfg" file in your text editor, if you haven't already. Since it is a new file, it should be completely empty right now. It won't be when we're done with it, however!

====The Toplevel Tagset and Attributes====

First, on the very first line of the file, tell the game what text domain this file belongs to. In case you forgot, the text domain for this campaign is " wesnoth-my_first_campaign". So you would write:

#textdomain wesnoth-my_first_campaign

Now let's add the [scenario] tagset:

[scenario]
[/scenario]

The [scenario] tagset is a toplevel tagset (i.e., it is not the child of any other tagset) and tells the game where the scenario begins and where it ends. All the information for your scenario goes within this tagset.

Next, inside the [scenario] tagset, include the following keys (don't forget to indent 4 spaces before each key):
id=
next_scenario=
name=
map_data=
turns=

Now the contents of the "my_first_scenario.cfg" file should look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=
next_scenario=
name=
map_data=
turns=
[/scenario]

We have provided keys for these attributes, so now it's time to assign them their values.

*'''The "id" Key'''

:Assign the value "my_first_scenario" to the "id" key, like so:
id=my_first_scenario
:Do you remember the value we assigned to the "first_scenario" key in the "_main.cfg" file? If you followed the instructions given in this tutorial, the value of that key should be "my_first_scenario". It is absolutely imperative that the value of the "first_scenario" key and the "id" key of the first scenario are exactly the same. If you misspelled either of them, introduced an incorrect capitalization into either of them, or made a typo of any kind in either of them, the game will return an error message when it tries to load the scenario. This is because the value of the "first_scenario" key refers to the id of your first scenario. If there is no scenario with an "id" key whose value exactly matches the value of the "first_scenario" key in the "_main.cfg", the game won't be able to find the first scenario and will tell you so by giving you an error message when you try to play your campaign.

*'''The "next_scenario" Key'''

:We are going to assign the value "null" to the "next_scenario" key. Example:
next_scenario=null
:The "next_scenario" key is a close cousin of the "first_scenario" key found in the "_main.cfg" file. Just as the "first_scenario" tells the game to look for a scenario with an id key whose value matches the value of the the "first_scenario" key, the "next_scenario" key tells the game which scenario to load after the player completes the current scenario. Just like with the "first_scenario" key, make sure the value of the "next_scenario" key exactly matches the id of the next scenario, otherwise you'll get an error message. If there is no next scenario, you would assign the value "null" to the "next_scenario" key, as we did here. This means that when the player completes the current scenario, the game knows that there is no next scenario to go to, and the campaign will end.

*'''The "name" Key'''

:For this attribute, we are going to give it this translatable string:
_ "My First Scenario."
As you should recall from our previous discussion about translatable strings, the value we give should be enclosed in double quotes and should have a whitespace, an underscore, and then another whitespace immediately before the first double quote. So now your "name" attribute should look like this:
name= _ "My First Scenario"
:Technically, the name of the scenario doesn't have to resemble the scenario's id at all. But it's a good idea to have the scenario id and the scenario name be as similar as possible to avoid any confusion later on.

*'''The "map_data" Key

:For this key, we are going to assign the value "{~add-ons/my_first_campaign/maps/my_first_map.map}". Map filepaths must always be within surrounded by double quotes, otherwise error messages will occur. Now it should look like this:
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"

*'''The "turns" Key'''

:We are going to assign the number "30" to this key:

turns=30

:This attribute specifies how many turns the player will have to complete the scenario. If the player does not complete the scenario objective before the turns run out, then the player will lose the scenario. Since we have assigned the value "30" to this key, that means that if the player hasn't won the scenario by the end of thirty turns, he or she will lose.

Now that we have assigned values to all our keys, the entire contents of the "my_first_scenario.cfg" file should now look like this:
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[/scenario]

====Defining Sides====

In any scenario, you will always need at least one side (the player's), and usually at least one other side as well. For this scenario, we need to define two sides: the player's side and the enemy's side.

Let's start with the player's side. In order to define a side, we need to include the [side] tagset as a child of the [scenario] tagset.

(...)

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

The syntax for writing an event goes like this:
[event]
name=name_of_the_event
#do something
[event]

There are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event.

====Objectives====

==Chapter 6: Building and Including a Custom Unit==

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

===Clearing Variables===
Whenever you know for sure that you won't need a variable any more, it's considered good programming practice to delete that variable, or ''clear'' it. This effectively tells the game that the variable in question isn't needed any more, so the game deletes that variable. If you don't clear variables once you no longer need them, they can accumulate over time and slow down the performance of both the game and the player's computer.

In order to clear a variable, use the following syntax:

#whatever the syntax is goes here, NOT THE MACRO, we want the user to be able to clear variables without relying on the macro (maybe mention the macro as a side note anyway?)

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
(condition)
[then]
(do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

==Chapter 11: More Logic: Cases and Loops==

===Cases===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without. Instead of using multiple [if] codeblocks, you could simply use the switch/case codeblock to evaluate the value of a variable and determine the action performed as a result of the evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
name=variable_name
[case]
value=first_value
#do something
[/case]
[case]
value=second_value
#do something
[/case]
[case]
value=third_value
#do something
[/case]
[else]
#do something
[/else]
[/switch]

===Loops===

==Conclusion: Where to Go From Here==

As long and involved as this tutorial was, it barely scratches the surface of WML. You can't call yourself a WML expert just yet, but the hardest part for you — finding a starting point — is now over. You now know how to create a simple campaign, and you know many of the features WML has to offer.

One of the best ways to learn more WML (and one of the only ways before this tutorial ;) ) is to study the WML code of other add-ons. You can also research any tags you're not familiar with on the [http://wiki.wesnoth.org/ReferenceWML WML Reference], which is a complete reference to pretty much every element of WML.

If you run into any problems that you can't solve by looking at other people's code or by studying the wiki, post a message in the [http://forums.wesnoth.org/viewforum.php?f=21 WML Workshop forum]. The resident WML gurus will be happy to help you out if you ask politely.

You've been given the tools and the materials. Now go out and build something amazing!