WML for Complete Beginners: Chapter 7

From The Battle for Wesnoth Wiki

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

You may have a counter variable to count the number of times an event happens. This variable will start at zero and go up by one every time the event happens. So how would you perform that basic math? It would look like this:

 [set_variable]
     name=counter
     add=1
 [/set_variable]

Contrary to expectations, arithmetic in WML is not done by the + ; - ; * ; / signs. Instead we use the keys "add" ; "sub" ; "multiply" ; "divide" respectively. So to multiply the existing ( i.e. previously set) variable named "treasure" by 17, you would write:

 [set_variable]
     name=treasure
     multiply=17
 [/set_variable]

Evaluating variables

You may have to look at a variable, and then do this or do that depending on the actual value of the variable. In other words: you evaluate a variable in an "if" statement. For instance, you want to check the value of the "has_picked_flower" variable, and then do something depending on it. This is done like this (the conditional statements shall be covered in a later section, now just concentrate on the variable tag):

 [if]
     [variable]  
         name=has_picked_flower  
         equals=yes  
     [/variable]
     [then]
         # do something
     [/then]
 [/if]

Here the evaluation most commonly used operator keys may be: "equals" ; "not_equals" ; "less_than" ; "greater_than" ; "greater_than_equal_to" ; "less_than_equal_to". Actually there is more but these shall do for now. For reference visit the Conditional Actions WML page.

Next Chapter: WML for Complete Beginners: Chapter 8

Previous Chapter: WML for Complete Beginners: Chapter 6

Return to Main Index: WML for Complete Beginners

This page was last edited on 9 June 2018, at 21:45.