The Battle for Wesnoth Wiki - User contributions [en]

WML for Complete Beginners: Chapter 4

2018-06-18T21:10:19Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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 some terrain, for example, hills. Click on the "rough" category button. You should see all available rough terrain types, namely hills, mountains, impassable high mountains and the like. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, so you always have 2 types of terrain ready. Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your terrain is now painted, using the chosen type from the palette. If you accidentally clicked a hex where you don’t want your chosen terrain to expand to, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over. You can add grassland, waters, roads, deserts the same way. If you already have a certain terrain type applied on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Now let's add some forest to our newly placed hills. Choose the "forest" category button, and then for example "Summer Deciduous Forest". Now click on the hex you want to put your hillside forest to. The forest is inserted, but the hillside is gone! Now the forest stands on grassland. This brings us to one important aspect: the layers of the map.

In the Wesnoth maps there are two layers. The "base" layer and the "overlay" layer. Base is the terrain that is below, and the overlay is the plants, buildings, bridges, etc. on it. To help you to understand better: the same forest can stand on grassland, hills, dry hills, mountains, even sand. And the same hillside can foster deciduous forests, mixed forests, summer forests, even desert forests. Something similar goes for buildings: the same bridge can span over shallow water, tropical water, swamp, even grassland, should the river be dried up.

How to draw that on the map? Easy: with the Shift key. Choose a forest, building, etc., and put it down while holding the Shift key. As you shall see, the stuff you have chosen shall be put on top of the existing base terrain, leaving it unchanged. Or try the other way around: choose a terrain, and put it under an existing bridge, forest, etc., with the Shift key pressed and held down. Experiment a little, you shall get the hang if it pretty quick.

When you judge your environment be finished, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" category button. Then paint your castle the same way you paint any other terrain.

(screenshot of the castle terrain category button)

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

As for villages: You can place villages the same way as any other type of terrain. Assigning the villages to sides in another matter, we shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

Finally, save your new map. You may save it to the Editor default location (data folder/editor/maps) and copy it over later to the data folder. Instead let us save it directly where our scenario needs it, i.e. the scenario’s map location (add-ons/my_first_campaign/maps/my_first_map.map).

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

Haven't we just done it on the map? Yes, but we shall need to define those sides in detail here in the scenario's configuration file too. Player 1 and 2 on the map shall be called Side 1 and 2 here respectively.

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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

Now we are just one final step away from finishing it, and finally playing it at last. The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-06-18T21:07:47Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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 some terrain, for example, hills. Click on the "rough" category button. You should see all available rough terrain types, namely hills, mountains, impassable high mountains and the like. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, so you always have 2 types of terrain ready. Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your terrain is now painted, using the chosen type from the palette. If you accidentally clicked a hex where you don’t want your chosen terrain to expand to, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over. You can add grassland, waters, roads, deserts the same way. If you already have a certain terrain type applied on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Now let's add some forest to our newly placed hills. Choose the "forest" category button, and then for example "Summer Deciduous Forest". Now click on the hex you want to put your hillside forest to. The forest is inserted, but the hillside is gone! Now the forest stands on grassland. This brings us to one important aspect: the layers of the map.

In the Wesnoth maps there are two layers. The "base" layer and the "overlay" layer. Base is the terrain that is below, and the overlay is the plants, buildings, bridges, etc. on it. To help you to understand better: the same forest can stand on grassland, hills, dry hills, mountains, even sand. And the same hillside can foster deciduous forests, mixed forests, summer forests, even desert forests. Something similar goes for buildings: the same bridge can span over shallow water, tropical water, swamp, even grassland, should the river be dried up.

How to draw that on the map? Easy: with the Shift key. Choose a forest, building, etc., and put it down while holding the Shift key. As you shall see, the stuff you have chosen shall be put on top of the existing base terrain, leaving it unchanged. Or try the other way around: Choose a terrain, and put it under an existing bridge, forest, etc., with the Shift key pressed and held down. Experiment a little, you shall get the hang if it pretty quick.

When you judge your environment be finished, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" category button. Then paint your castle the same way you paint any other terrain.

(screenshot of the castle terrain category button)

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

As for villages: You can place villages the same way as any other type of terrain. Assigning the villages to sides in another matter, we shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

Finally, save your new map. You may save it to the Editor default location (data folder/editor/maps) and copy it over later to the data folder. Instead let us save it directly where our scenario needs it, i.e. the scenario’s map location (add-ons/my_first_campaign/maps/my_first_map.map).

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

Haven't we just done it on the map? Yes, but we shall need to define those sides in detail here in the scenario's configuration file too. Player 1 and 2 on the map shall be called Side 1 and 2 here respectively.

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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

Now we are just one final step away from finishing it, and finally playing it at last. The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-06-18T20:50:37Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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 some terrain, for example, hills. Click on the "rough" category button. You should see all available rough terrain types, namely hills, mountains, impassable high mountains and the like. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, so you always have 2 types of terrain ready. Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette. If you accidentally clicked a hex where you don’t want your chosen terrain to expand to, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over. You can add grassland, waters, roads, deserts the same way. If you already have a certain terrain type applied on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Now let's add some forest to our newly placed hills. Choose the "forest" category button, and then for example "Summer Deciduous Forest". Now click on the hex you want to put your hillside forest to. The forest is inserted, but the hillside is gone! Now the forest stands on grassland. This brings us to one important aspect: the layers of the map.

In the Wesnoth maps there are two layers. The "base" layer and the "overlay" layer. Base is the terrain that is below, and the overlay is the plants, buildings, bridges, etc. on it. To help you to understand better: the same forest can stand on grassland, hills, dry hills, mountains, even sand. And the same hillside can foster deciduous forests, mixed forests, summer forests, even desert forests. Something similar goes for buildings: the same bridge can span over shallow water, tropical water, swamp, even grassland, should the river be dried up.

How to draw that on the map? Easy: with the Shift key. Choose a forest, building, etc., and put it down while holding the Shift key. As you shall see, the stuff you have chosen shall be put on top of the existing base terrain, leaving it unchanged. Or try the other way around: Choose a terrain, and put it under an existing bridge, forest, etc., with the Shift key pressed and held down. Experiment a little, you shall get the hang if it pretty quick.

When you judge your environment be finished, let's add a castle for the leader of the player's side to recruit from in the first scenario. Click on the "castle" category button. Then paint your castle the same way you paint any other terrain.

(screenshot of the castle terrain category button)

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

As for villages: You can place villages the same way as any other type of terrain. Assigning the villages to sides in another matter, we shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

Finally, save your new map. You may save it to the Editor default location (data folder/editor/maps) and copy it over later to the data folder. Instead let us save it directly where our scenario needs it, i.e. the scenario’s map location (add-ons/my_first_campaign/maps/my_first_map.map).

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

Haven't we just done it on the map? Yes, but we shall need to define those sides in detail here in the scenario's configuration file too. Player 1 and 2 on the map shall be called Side 1 and 2 here respectively.

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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

Now we are just one final step away from finishing it, and finally playing it at last. The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:45:56Z

Greeneyelink: /* Evaluating variables */

==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 [https://wiki.wesnoth.org/ConditionalActionsWML 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]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:45:38Z

Greeneyelink: /* Evaluating variables */

==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 [https://wiki.wesnoth.org/ConditionalActionsWML 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]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:40:46Z

Greeneyelink: /* Evaluating variables */

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

[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 [https://wiki.wesnoth.org/ConditionalActionsWML 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]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:35:10Z

Greeneyelink: /* Evaluating variables */

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

[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 [https://wiki.wesnoth.org/ConditionalActionsWML 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]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:33:40Z

Greeneyelink: /* Manipulating Variables */

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

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

Here the evaluation operator keys may be: "equals" ; "not_equals" ; "less_than" ; "greater_than" ; "greater_than_equal_to" ; "less_than_equal_to". For reference visit the [https://wiki.wesnoth.org/ConditionalActionsWML 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]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:30:19Z

Greeneyelink: /* Evaluating variables */

==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 "treasure" variable's value 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:

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

Here the evaluation operator keys may be: "equals" ; "not_equals" ; "less_than" ; "greater_than" ; "greater_than_equal_to" ; "less_than_equal_to". For reference visit the [https://wiki.wesnoth.org/ConditionalActionsWML 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]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:28:46Z

Greeneyelink: /* Evaluating variables */

==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 "treasure" variable's value 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:

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

Here the evaluation operator keys may be: "equals" ; "not_equals" ; "less_than" ; "greater_than" ; "greater_than_equal_to" ; "less_than_equal_to". For reference visit the [https://wiki.wesnoth.org/ConditionalActionsWML] 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]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:16:24Z

Greeneyelink: /* Manipulating Variables */

==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 "treasure" variable's value 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:

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

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

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

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:13:23Z

Greeneyelink: /* Evaluating variables */

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

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

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

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

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

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:07:24Z

Greeneyelink:

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

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

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

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

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2018-06-09T21:03:16Z

Greeneyelink: /* Manipulating Variables */

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

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

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

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners

2018-05-21T14:49:20Z

Greeneyelink: /* Main Index */

{{Translations}}

Welcome to the WML Guide for Complete Beginners! From here, you can get started directly by heading to the [[WML for Complete Beginners: Introduction|Introduction]] or you can continue from the chapter you left off.

==Important Notes:==
This is a work in progress.
Minor edits will not cause the edit to be shown immediately on a page to viewers.
-------------

TODO:
1. 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).

2. Finish chapters 6-11 (Partially Complete)

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

==Main Index==

[[WML_for_Complete_Beginners:_Introduction]]

[[WML_for_Complete_Beginners:_Chapter_1]] Syntax

[[WML_for_Complete_Beginners:_Chapter_2]] The Userdata Directory and the Campaign Folder

[[WML_for_Complete_Beginners:_Chapter_3]] The _main.cfg

[[WML_for_Complete_Beginners:_Chapter_4]] Creating Your First Scenario

[[WML_for_Complete_Beginners:_Chapter_5]] Events

[[WML_for_Complete_Beginners:_Chapter_6]]

[[WML_for_Complete_Beginners:_Chapter_7]]

[[WML_for_Complete_Beginners:_Chapter_8]]

[[WML_for_Complete_Beginners:_Chapter_9]]

[[WML_for_Complete_Beginners:_Chapter_10]]

[[WML_for_Complete_Beginners:_Chapter_11]]

[[WML_for_Complete_Beginners:_Conclusion]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:48:42Z

Greeneyelink: /* Nested Events */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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. In our example here we shall also mention the ''last breath'' event, the ''die'' event, and the ''time over'' 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[objective]
description= _ "Turns run out"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! Go, give it a try! Play it! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:47:29Z

Greeneyelink: /* Nested Events */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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. In our example here we shall also mention the ''last breath'' event, the ''die'' event, and the ''time over'' 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[objective]
description= _ "Turns run out"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:46:16Z

Greeneyelink: /* Nested Events */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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. In our example here we shall also mention the ''last breath'' event, the ''die'' event, and the ''time over'' 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[objective]
description= _ "Turns run out"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:38:24Z

Greeneyelink: /* The "time over" Event */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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. In our example here we shall also mention the ''last breath'' event, the ''die'' event, and the ''time over'' 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:23:42Z

Greeneyelink: /* Chapter 5: Events */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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. In our example here we shall also mention the ''last breath'' event, the ''die'' event, and the ''time over'' 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endelevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:20:37Z

Greeneyelink: /* The "time over" Event */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endelevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:09:54Z

Greeneyelink: /* "last breath" and "die" Events */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endelevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:03:01Z

Greeneyelink: /* The "start" Event */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endelevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed (can be specified by [filter_second], known as 'second_unit'), however there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T14:02:28Z

Greeneyelink: /* The "start" Event */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written in to other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endelevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed (can be specified by [filter_second], known as 'second_unit'), however there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T13:52:11Z

Greeneyelink: /* Chapter 5: Events */

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

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J)for the scenario. This is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endelevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed (can be specified by [filter_second], known as 'second_unit'), however there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 5

2018-05-21T13:51:47Z

Greeneyelink: /* Chapter 5: Events */

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

To give you examples of the real thing, i.e. playing Wesnoth : When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

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

As mentioned before, 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.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
[event]
name=prestart
#do stuff here
[/event]
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
name=start

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J)for the scenario. This is done using two tags: [objectives] and [objective] like this:
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
speaker=
message= _ ""
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
speaker=MyLeader
The message key represents what the speaker is actually going to say. This should be marked translatable:
message= _ "I see the orcs!"

I'm going to put this (and another) message into our example start event:
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]

[/event]
[/scenario]

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
[filter]
side=1
x,y=1,1
[/filter]
Simple, huh? Other common keys for a filter tag include:
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
A rather typical time over event would look like this:
[event]
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endelevel]
[/event]

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed (can be specified by [filter_second], known as 'second_unit'), however there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
[event]
name=event1
(...)
[event]
name=event2
(...)
[/event]
[/event]
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:

#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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[/scenario]
Congratulations! You have now written your first functional scenario! When you're ready to keep going, head to [[WML for Complete Beginners: Chapter 6]]

or head back to [[WML for Complete Beginners: Chapter 4]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-19T20:34:26Z

Greeneyelink: /* Defining Sides */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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" category button.

(screenshot of the castle terrain category button)

You should see all available castle types. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, so you always have 2 types of terrain ready.

Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette. If you accidentally clicked a hex where you don’t want your castle to expand to, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over.
If you already have a certain terrain type applied on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

Draw the natural terrain (hills, river, etc.) for the rest of the map. You can place villages the same way as any other type of terrain.
We shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

Finally, save your new map. You may save it to the Editor default location (data folder/editor/maps) and copy it over later to the data folder. Instead let us save it directly where our scenario needs it, i.e. the scenario’s map location (add-ons/my_first_campaign/maps/my_first_map.map).

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

Haven't we just done it on the map? Yes, but we shall need to define those sides in detail here in the scenario's configuration file too. Player 1 and 2 on the map shall be called Side 1 and 2 here respectively.

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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

Now we are just one final step away from finishing it, and finally playing it at last. The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-19T20:32:08Z

Greeneyelink: /* Defining Sides */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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" category button.

(screenshot of the castle terrain category button)

You should see all available castle types. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, so you always have 2 types of terrain ready.

Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette. If you accidentally clicked a hex where you don’t want your castle to expand to, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over.
If you already have a certain terrain type applied on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

Draw the natural terrain (hills, river, etc.) for the rest of the map. You can place villages the same way as any other type of terrain.
We shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

Finally, save your new map. You may save it to the Editor default location (data folder/editor/maps) and copy it over later to the data folder. Instead let us save it directly where our scenario needs it, i.e. the scenario’s map location (add-ons/my_first_campaign/maps/my_first_map.map).

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

Haven't we just done it on the map? Yes, but we shall need to define those sides in detail here in the scenario's configuration file too. Player 1 and 2 on the map shall be called Side 1 and 2 here respectively.

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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-19T20:23:46Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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" category button.

(screenshot of the castle terrain category button)

You should see all available castle types. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, so you always have 2 types of terrain ready.

Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette. If you accidentally clicked a hex where you don’t want your castle to expand to, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over.
If you already have a certain terrain type applied on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

Draw the natural terrain (hills, river, etc.) for the rest of the map. You can place villages the same way as any other type of terrain.
We shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

Finally, save your new map. You may save it to the Editor default location (data folder/editor/maps) and copy it over later to the data folder. Instead let us save it directly where our scenario needs it, i.e. the scenario’s map location (add-ons/my_first_campaign/maps/my_first_map.map).

===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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-17T20:56:39Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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)

You should see all available castle terrain types. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, to always have 2 types of terrain ready.

Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette. If you clicked a hex where you don’t want castle terrain, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over.
If you already have a certain terrain type on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

Draw the natural terrain (hills, river, etc.) for the rest of the map. You can place villages the same way as any other type of terrain.
We shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

Finally, save your new map. Remember the exact path and file name, as we shall need it later on.

===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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-17T20:54:59Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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)

You should see all available castle terrain types. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, to always have 2 types of terrain ready.

Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette. If you clicked a hex where you don’t want castle terrain, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over.
If you already have a certain terrain type on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

Draw a castle with a keep for the opposite party too. (Unless of course if you want to build a scenario without an enemy.)

Draw the natural terrain (hills, river, etc.) for the rest of the map. You can place villages the same way as any other type of terrain.
We shall discuss the topic of assigning the villages to either side in a later chapter.

We are almost done with the map, but in order to use it, we have to assign our leaders to the keeps. This is done by using the Starting Positions Tool.

(screenshot of the Starting Positions Tool)

Click on the flag, then choose Player 1 (usually the human player) or Player 2 (usually the AI). Now click on the preferred keep. That's it, now you have your leader assigned to the castle. A label with the player name should also appear.

===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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-17T20:41:26Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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)

You should see all available castle terrain types. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, to always have 2 types of terrain ready.

Go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette. If you clicked a hex where you don’t want castle terrain, just choose any other type of terrain (grassland, forest, swamp, etc.) and paint it over.
If you already have a certain terrain type on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

===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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-17T20:39:20Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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)

Now you should see all available castle terrain types. Left click one to assign it to the left mouse button. Now the bottom of the map area shows your chosen terrain. You can do it for the right button too, to always have 2 types of terrain ready.
Now go to the map area. Click one hex, or click and hold the left mouse button and swipe the mouse through several hexes. Your castle is now built, using the chosen type from the palette.
If you clicked a hex where you don’t want castle terrain, just click on any other type of terrain (grassland, forest, swamp, etc.) and paint it over.
If you already have a certain terrain type on your map, you can assign it to the mouse buttons by Ctrl-clicking on them, instead of finding them again on the palette.

Don’t forget to add a keep to your castle. That’s where your leader shall be positioned at the start of the scenario, and that’s where he (or she) can recruit his/her army from.

===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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 4

2018-04-17T20:30:50Z

Greeneyelink: /* Creating the Scenario Map */

==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". Actually you can use the editor not only to create maps, but it also has some scenario-editing capabilities. More on that in a later chapter, for the time being let us just focus on simple map editing. 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. All the keys we add to define a side go inside this [side] tagset.

[scenario]
[side]
#keys go here
[/side]
[/scenario]

*'''The "side" Key'''
:The "side" key is used to keep track of the side (or player) number of this side. Normally, the player is side 1.
side=1
*'''The "controller" Key'''
:The "controller" key is used to tell WML whether this side belongs to a 'human' or to the 'ai'. This side belongs to a human.
controller=human
*'''The "team_name" Key'''
:The "team_name" key is an internal variable (the user never gets to see its value) which WML uses to keep track of teams. All sides with the same team_name are considered allies.
team_name="good"
*'''The "user_team_name" Key'''
:The "user_team_name" key contains the text for the team name to display to the user. Since this will be seen, it should be marked as translatable using an underscore '_'. Note that user_team_name does not need to be the same as team_name, and that sides with the same team_name need not have the same user_team_name.
user_team_name= _ "My Team"
*'''The "id" Key'''
:The "id" key contains the id (identifier) for this side's leader, and is not seen in-game. Use this id to access the leader from within WML.
id="MyLeader"
*'''The "name" Key'''
:The "name" key represents the name of this side's leader. Since this will be seen in-game, it should be marked as translatable.
name= _ "My Leader"
*'''The "type" Key'''
:The "type" key contains the unit-type of this side's leader. In this example, the leader is an Elvish Ranger.
type="Elvish Ranger"
*'''The "unrenameable" Key'''
:The "unrenameable" key, if set to 'yes' prevents the user from being able to change the name of the leader in-game. For most scenarios, this should be set to 'yes'.
unrenameable=yes
*'''The "canrecruit" Key'''
:The "canrecruit" key, if set to 'yes' allows this leader to recruit units.
canrecruit=yes
*'''The "recruit" Key'''
:The "recruit" key is a comma-separated list of all the units this leader is allowed to recruit. Our example Elvish Ranger is able to recruit Elvish Fighters, Elvish Archers, and Elvish Shamans by the following statement:
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
*'''The "gold" Key'''
:The "gold" key is set to the starting gold amount for this side. This fictional side is given 100 gold to start. (Note that it is possible to give a side a differing amount of starting gold based upon the difficulty level, but that is not covered at this time.)
gold=100
:Repeat this process for every side you wish to create. I'm going to add a simple ai side:
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]

Now the entire contents of the "my_first_scenario.cfg" file should look something 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
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[/scenario]

The next step in creating your first scenario is to add the events which trigger in-game. To learn how to create events, continue to [[WML for Complete Beginners: Chapter 5]].

Or, head back to [[WML for Complete Beginners: Chapter 3]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners

2018-04-17T20:28:55Z

Greeneyelink: /* Main Index */

{{Translations}}

Welcome to the WML Guide for Complete Beginners! From here, you can get started directly by heading to the [[WML for Complete Beginners: Introduction|Introduction]] or you can continue from the chapter you left off.

==Important Notes:==
This is a work in progress.
Minor edits will not cause the edit to be shown immediately on a page to viewers.
-------------

TODO:
1. 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).

2. Finish chapters 6-11 (Partially Complete)

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

==Main Index==

[[WML_for_Complete_Beginners:_Introduction]]

[[WML_for_Complete_Beginners:_Chapter_1]] Syntax

[[WML_for_Complete_Beginners:_Chapter_2]] The Userdata Directory and the Campaign Folder

[[WML_for_Complete_Beginners:_Chapter_3]] The _main.cfg

[[WML_for_Complete_Beginners:_Chapter_4]] Creating Your First Scenario

[[WML_for_Complete_Beginners:_Chapter_5]]

[[WML_for_Complete_Beginners:_Chapter_6]]

[[WML_for_Complete_Beginners:_Chapter_7]]

[[WML_for_Complete_Beginners:_Chapter_8]]

[[WML_for_Complete_Beginners:_Chapter_9]]

[[WML_for_Complete_Beginners:_Chapter_10]]

[[WML_for_Complete_Beginners:_Chapter_11]]

[[WML_for_Complete_Beginners:_Conclusion]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners

2018-04-17T20:23:44Z

Greeneyelink: /* Main Index */

{{Translations}}

Welcome to the WML Guide for Complete Beginners! From here, you can get started directly by heading to the [[WML for Complete Beginners: Introduction|Introduction]] or you can continue from the chapter you left off.

==Important Notes:==
This is a work in progress.
Minor edits will not cause the edit to be shown immediately on a page to viewers.
-------------

TODO:
1. 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).

2. Finish chapters 6-11 (Partially Complete)

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

==Main Index==

[[WML_for_Complete_Beginners:_Introduction]]

[[WML_for_Complete_Beginners:_Chapter_1]] Syntax

[[WML_for_Complete_Beginners:_Chapter_2]] The Userdata Directory and the Campaign Folder

[[WML_for_Complete_Beginners:_Chapter_3]] The _main.cfg

[[WML_for_Complete_Beginners:_Chapter_4]]

[[WML_for_Complete_Beginners:_Chapter_5]]

[[WML_for_Complete_Beginners:_Chapter_6]]

[[WML_for_Complete_Beginners:_Chapter_7]]

[[WML_for_Complete_Beginners:_Chapter_8]]

[[WML_for_Complete_Beginners:_Chapter_9]]

[[WML_for_Complete_Beginners:_Chapter_10]]

[[WML_for_Complete_Beginners:_Chapter_11]]

[[WML_for_Complete_Beginners:_Conclusion]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 2

2018-04-17T20:21:56Z

Greeneyelink: /* The Campaign Folder */

==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.12/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.12/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.12/
|-
!Linux
|~/.local/share/wesnoth/1.12/
|}

''Note:'' On Windows, if you chose 'Store userdata in the install location' during setup, the userdata directory is usually in<br>
~/AppData/Local/VirtualStore/Program Files (x86)/Battle for Wesnoth 1.12.7

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 (more exactly the data/add-ons/ 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/add-ons folder inside the userdata directory. That means that your campaign will also be located inside the data/add-ons folder. If you're not already there, enter the data/add-ons folder now.

Next, create a new folder inside the data/add-ons 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.

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

Or head back to [[WML for Complete Beginners: Chapter 1]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 2

2018-04-17T20:19:30Z

Greeneyelink: /* The data folder */

==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.12/
|-
!Windows Vista and above
|~/Documents/My Games/Wesnoth 1.12/
|-
!Mac OS X
|~/Library/Application Support/Wesnoth 1.12/
|-
!Linux
|~/.local/share/wesnoth/1.12/
|}

''Note:'' On Windows, if you chose 'Store userdata in the install location' during setup, the userdata directory is usually in<br>
~/AppData/Local/VirtualStore/Program Files (x86)/Battle for Wesnoth 1.12.7

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 (more exactly the data/add-ons/ 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.

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

Or head back to [[WML for Complete Beginners: Chapter 1]]

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

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners

2018-04-17T19:52:46Z

Greeneyelink:

{{Translations}}

Welcome to the WML Guide for Complete Beginners! From here, you can get started directly by heading to the [[WML for Complete Beginners: Introduction|Introduction]] or you can continue from the chapter you left off.

==Important Notes:==
This is a work in progress.
Minor edits will not cause the edit to be shown immediately on a page to viewers.
-------------

TODO:
1. 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).

2. Finish chapters 6-11 (Partially Complete)

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

==Main Index==

[[WML_for_Complete_Beginners:_Introduction]]

[[WML_for_Complete_Beginners:_Chapter_1]] Syntax

[[WML_for_Complete_Beginners:_Chapter_2]] The Userdata Directory and the Campaign Folder

[[WML_for_Complete_Beginners:_Chapter_3]]

[[WML_for_Complete_Beginners:_Chapter_4]]

[[WML_for_Complete_Beginners:_Chapter_5]]

[[WML_for_Complete_Beginners:_Chapter_6]]

[[WML_for_Complete_Beginners:_Chapter_7]]

[[WML_for_Complete_Beginners:_Chapter_8]]

[[WML_for_Complete_Beginners:_Chapter_9]]

[[WML_for_Complete_Beginners:_Chapter_10]]

[[WML_for_Complete_Beginners:_Chapter_11]]

[[WML_for_Complete_Beginners:_Conclusion]]

[[Category:WML_for_Complete_Beginners]]