The Battle for Wesnoth Wiki - User contributions [en]

Template:BuildingScenariosNav

2007-07-15T11:44:34Z

Mathijs:

<div class="navtemplate">
==== Quick Navigation ====
'''[[BuildingScenarios]]'''
:*'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:*[[BuildingScenariosComments]]
:*[[BuildingScenariosSamples]]
:*[[BuildingScenariosFAQ]]
</div>
{| style="float:right"
|
__TOC__
|}

Template:BuildingScenariosNav

2007-07-15T11:42:43Z

Mathijs:

<div class="navtemplate">
==== Quick Navigation ====
'''[[BuildingScenarios]]'''
:*'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:*[[BuildingScenariosWML]]
:*[[BuildingScenariosComments]]
:*[[BuildingScenariosSamples]]
:*[[BuildingScenariosFAQ]]
</div>
{| style="float:right"
|
__TOC__
|}

BuildingScenariosAdvanced

2007-07-04T15:11:57Z

Mathijs: /* Manipulating Variables */

{{BuildingScenariosNav}}

= Building scenarios: Advanced =

== '''TODO:''' ==
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information on guidelines concerning the general layout of a scenario file
* advanced filtering
* ...

Ayone who feels like writing something, go ahead

== Advanced Events ==

===Internal Actions===
See [[InternalActionsWML]] for a complete list of all tags and values. In what folows, the basics of variable creation and manipulation is explained.

====Variables====
(This can be skipped if you're familiar with the concept of variables)

(See [[VariablesWML]] for more)

What are variables? Variables are basicly names. And with those names, we associate a certain value. You can compare this with the words, because words are associated with (several) objects, people, feelings, ... So a variable is just a way of communication: you and the computer (the Wesnoth engine really) are communicating wit each other!

The most important aspect of variables is that they can change with time. (If they don't we call them constants.) Because they change, we can use them to trigger events, or to detect something has happened. You did this already in [[BuildingScenariosIntermediate]], using the [event] tag. We only wanted to trigger the actions inside the [event] when Konrad moved onto tile 4,8. To o so we had to make use of the variables x,y and description.

Most variables provided by the engine are associated with a certain tag and can thus only be used inside them.

====Manipulating====
These three actions can be executed in one single tag: ''''[set_variable]''''
Say we wanted to store 'Hello World' in a variable named ''message_to_the_world''. This is how we would do this:
[event]
.
.
.
[set_variable]
#The name of our variable:
name=message_to_the_world
#The value of message_to_the_world, notice the underscore!
value= _ "Hello World!"
[/set_variable]
.
.
.
[/event]
Now, if we want to change the value to something else later on, e.g. 'Goodbye World', we can use the exact same code as above.
If we want to add something to our message we need to use this:

[event]
.
.
.
[set_variable]
name=message_to_the_world
value= _ "$message_to_the_world Have a nice day!"
[/set_variable]
.
.
.
[/event]
We've been using text variables (called strings) for now. But we can also store numbers and do some basic math with them. The following example clarifies this:

[event]
.
.
.
[set_variable]
name=number_x
value=10
[/set_variable]
[set_variable]
name=number_x
add=-9
[/set_variable]
[set_variable]
name=number_x
multiply=200
[/set_variable]
[set_variable]
name=number_x
multiply=0.5
[/set_variable]
.
.
.
[/event]
In the above, we set a variable named ''number_x'' to the value of 10. We substract 9 (=1), multiply with 200 (=200) and divide by two (or multiply with 0.5) resulting in 10 again.

====Using Variables====
Now that we know how to create and manipulate variables, we'll learn how to use them.
First of all, you need to know what variables you always have at your disposal! In an event tag, these variables are
* side_number- the number of the current player's side (may be empty during start or prestart events)
* turn_number- the number of the current turn (may be empty during start or prestart events)
* x1- this is the x-coordinate of the location where the most recent event was triggered
* y1- this is the y-coordinate of the location where the most recent event was triggered
* x2- this is the x-coordinate of the location that assisted in triggering the most recent event
* y2- this is the y-coordinate of the location that assisted in triggering the most recent event
* unit- inside an event, this is the unit at $x1,$y1 {{DevFeature}}
* second_unit- inside an event, this is the unit at $x2,$y2 {{DevFeature}}
* this_unit- inside a standard unit filter, this is the unit currently being considered for a possible match {{DevFeature}}

Some of these are only containers for other variables. The ''unit'' variable is an example. You can acces those 'sub'-variables by using dots:
unit.hitpoints
unit.side
...

We will use $unit in an example to show you how you can use all this:
[scenario]
.
.
.
[event]
#A unit moves onto a tile:
name=moveto
[filter]
x,y=25,26
[/filter]

[set_variable]
name=unit.hitpoints
add=-5
[/set_variable]
[set_variable]
name=unit.status.poisoned
value=yes
[/set_variable]

#After we have changed the values, we need to apply them.
#We do this by using the unstore_unit tag like this:
[unstore_unit]
variable=$unit
find_vacant=no
[/unstore_unit]
[/event]
#We're finished!
.
.
.
[/scenario]

There's one tag you don't know yet, and thats the '''[unstore_unit]''' tag. To explain this tag I'll explain it's counterparts; '''[store_unit]'''. [store_unit] stores a unit, or several units, in a variables you choose. You can then manipulate those variables as described above. However, you will need to apply these changes, and this is done by using the [unstore_unit] tag. For more see [http://www.wesnoth.org/wiki/InternalActionsWML#.5Bevent.5D InternalActions].



== [[GetText]] & Translations ==
[http://www.wesnoth.org/forum/viewtopic.php?t=11445 As Viliam pointed out] (reordered his words):

Translating programs has two steps. The first step is making [...] scenarios that are
<b>possible</b> to translate; <b>preferably easy</b> to translate. [...] The second
step is the translating of the texts... leave this to translators.

So, as a campaign/scenario developer you have to make sure your campaign will be easy to translate. You can achieve this very easily by preceding all text the user might see on the screen with an underscore. This indicates it is a translatable string. [[GetText]] will then be able to look up a translation, based on your localisation settings.
To make it ever more clear, here's an example:
.
.
.
[message]
description=Konrad
message= <b>_</b> "I am mighty Konrad! I fought many dummies and now I will fight you!"
[/message]
.
.
.

The message key contains the words that will be displayed when Konrad speaks. So this is a translatable string. So it is preceded with an underscore.

Viliam also said:

The most important rule of all is: <b>Do not split sentences.</b>
In some languages placing a word in a sentence requires more than mere string concatenation.
Some languages use [http://en.wikipedia.org/wiki/Declension declension].

== Quick Tag Index ==
'''[[ScenarioWML]]''' the top level tags [scenario], [multiplayer], [test], and [tutorial]
:* [[EventWML]] how to describe an event
:** [[FilterWML]]
:** [[DirectActionsWML]], [[InterfaceActionsWML]], [[InternalActionsWML]]
:* [[SideWML]] how to describe a side
:** [[SingleUnitWML]]
:** [[BuildingScenariosShroudData]]
:* [[MapGeneratorWML]] the random map generator
:* [[TimeWML]] how to describe a day
:* [[IntroWML]] how to describe the intro screen
:* [[UtilWML]] a set of preprocessors you can use

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-07-04T15:10:59Z

Mathijs: /* Storing, Creating and Changing Variables */

{{BuildingScenariosNav}}

= Building scenarios: Advanced =

== '''TODO:''' ==
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information on guidelines concerning the general layout of a scenario file
* advanced filtering
* ...

Ayone who feels like writing something, go ahead

== Advanced Events ==

===Internal Actions===
See [[InternalActionsWML]] for a complete list of all tags and values. In what folows, the basics of variable creation and manipulation is explained.

====Variables====
(This can be skipped if you're familiar with the concept of variables)

(See [[VariablesWML]] for more)

What are variables? Variables are basicly names. And with those names, we associate a certain value. You can compare this with the words, because words are associated with (several) objects, people, feelings, ... So a variable is just a way of communication: you and the computer (the Wesnoth engine really) are communicating wit each other!

The most important aspect of variables is that they can change with time. (If they don't we call them constants.) Because they change, we can use them to trigger events, or to detect something has happened. You did this already in [[BuildingScenariosIntermediate]], using the [event] tag. We only wanted to trigger the actions inside the [event] when Konrad moved onto tile 4,8. To o so we had to make use of the variables x,y and description.

Most variables provided by the engine are associated with a certain tag and can thus only be used inside them.

====Manipulating Variables====
These three actions can be executed in one single tag: ''''[set_variable]''''
Say we wanted to store 'Hello World' in a variable named ''message_to_the_world''. This is how we would do this:
[event]
.
.
.
[set_variable]
#The name of our variable:
name=message_to_the_world
#The value of message_to_the_world, notice the underscore!
value= _ "Hello World!"
[/set_variable]
.
.
.
[/event]
Now, if we want to change the value to something else later on, e.g. 'Goodbye World', we can use the exact same code as above.
If we want to add something to our message we need to use this:

[event]
.
.
.
[set_variable]
name=message_to_the_world
value= _ "$message_to_the_world Have a nice day!"
[/set_variable]
.
.
.
[/event]
We've been using text variables (called strings) for now. But we can also store numbers and do some basic math with them. The following example clarifies this:

[event]
.
.
.
[set_variable]
name=number_x
value=10
[/set_variable]
[set_variable]
name=number_x
add=-9
[/set_variable]
[set_variable]
name=number_x
multiply=200
[/set_variable]
[set_variable]
name=number_x
multiply=0.5
[/set_variable]
.
.
.
[/event]
In the above, we set a variable named ''number_x'' to the value of 10. We substract 9 (=1), multiply with 200 (=200) and divide by two (or multiply with 0.5) resulting in 10 again.

====Using Variables====
Now that we know how to create and manipulate variables, we'll learn how to use them.
First of all, you need to know what variables you always have at your disposal! In an event tag, these variables are
* side_number- the number of the current player's side (may be empty during start or prestart events)
* turn_number- the number of the current turn (may be empty during start or prestart events)
* x1- this is the x-coordinate of the location where the most recent event was triggered
* y1- this is the y-coordinate of the location where the most recent event was triggered
* x2- this is the x-coordinate of the location that assisted in triggering the most recent event
* y2- this is the y-coordinate of the location that assisted in triggering the most recent event
* unit- inside an event, this is the unit at $x1,$y1 {{DevFeature}}
* second_unit- inside an event, this is the unit at $x2,$y2 {{DevFeature}}
* this_unit- inside a standard unit filter, this is the unit currently being considered for a possible match {{DevFeature}}

Some of these are only containers for other variables. The ''unit'' variable is an example. You can acces those 'sub'-variables by using dots:
unit.hitpoints
unit.side
...

We will use $unit in an example to show you how you can use all this:
[scenario]
.
.
.
[event]
#A unit moves onto a tile:
name=moveto
[filter]
x,y=25,26
[/filter]

[set_variable]
name=unit.hitpoints
add=-5
[/set_variable]
[set_variable]
name=unit.status.poisoned
value=yes
[/set_variable]

#After we have changed the values, we need to apply them.
#We do this by using the unstore_unit tag like this:
[unstore_unit]
variable=$unit
find_vacant=no
[/unstore_unit]
[/event]
#We're finished!
.
.
.
[/scenario]

There's one tag you don't know yet, and thats the '''[unstore_unit]''' tag. To explain this tag I'll explain it's counterparts; '''[store_unit]'''. [store_unit] stores a unit, or several units, in a variables you choose. You can then manipulate those variables as described above. However, you will need to apply these changes, and this is done by using the [unstore_unit] tag. For more see [http://www.wesnoth.org/wiki/InternalActionsWML#.5Bevent.5D InternalActions].



== [[GetText]] & Translations ==
[http://www.wesnoth.org/forum/viewtopic.php?t=11445 As Viliam pointed out] (reordered his words):

Translating programs has two steps. The first step is making [...] scenarios that are
<b>possible</b> to translate; <b>preferably easy</b> to translate. [...] The second
step is the translating of the texts... leave this to translators.

So, as a campaign/scenario developer you have to make sure your campaign will be easy to translate. You can achieve this very easily by preceding all text the user might see on the screen with an underscore. This indicates it is a translatable string. [[GetText]] will then be able to look up a translation, based on your localisation settings.
To make it ever more clear, here's an example:
.
.
.
[message]
description=Konrad
message= <b>_</b> "I am mighty Konrad! I fought many dummies and now I will fight you!"
[/message]
.
.
.

The message key contains the words that will be displayed when Konrad speaks. So this is a translatable string. So it is preceded with an underscore.

Viliam also said:

The most important rule of all is: <b>Do not split sentences.</b>
In some languages placing a word in a sentence requires more than mere string concatenation.
Some languages use [http://en.wikipedia.org/wiki/Declension declension].

== Quick Tag Index ==
'''[[ScenarioWML]]''' the top level tags [scenario], [multiplayer], [test], and [tutorial]
:* [[EventWML]] how to describe an event
:** [[FilterWML]]
:** [[DirectActionsWML]], [[InterfaceActionsWML]], [[InternalActionsWML]]
:* [[SideWML]] how to describe a side
:** [[SingleUnitWML]]
:** [[BuildingScenariosShroudData]]
:* [[MapGeneratorWML]] the random map generator
:* [[TimeWML]] how to describe a day
:* [[IntroWML]] how to describe the intro screen
:* [[UtilWML]] a set of preprocessors you can use

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-07-04T15:08:46Z

Mathijs: /* GetText & Translations */

{{BuildingScenariosNav}}

= Building scenarios: Advanced =

== '''TODO:''' ==
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information on guidelines concerning the general layout of a scenario file
* advanced filtering
* ...

Ayone who feels like writing something, go ahead

== Advanced Events ==

===Internal Actions===
See [[InternalActionsWML]] for a complete list of all tags and values. In what folows, the basics of variable creation and manipulation is explained.

====Variables====
(This can be skipped if you're familiar with the concept of variables)

(See [[VariablesWML]] for more)

What are variables? Variables are basicly names. And with those names, we associate a certain value. You can compare this with the words, because words are associated with (several) objects, people, feelings, ... So a variable is just a way of communication: you and the computer (the Wesnoth engine really) are communicating wit each other!

The most important aspect of variables is that they can change with time. (If they don't we call them constants.) Because they change, we can use them to trigger events, or to detect something has happened. You did this already in [[BuildingScenariosIntermediate]], using the [event] tag. We only wanted to trigger the actions inside the [event] when Konrad moved onto tile 4,8. To o so we had to make use of the variables x,y and description.

Most variables provided by the engine are associated with a certain tag and can thus only be used inside them.

====Storing, Creating and Changing Variables====
These three actions can be executed in one single tag: ''''[set_variable]''''
Say we wanted to store 'Hello World' in a variable named ''message_to_the_world''. This is how we would do this:
[event]
.
.
.
[set_variable]
#The name of our variable:
name=message_to_the_world
#The value of message_to_the_world, notice the underscore!
value= _ "Hello World!"
[/set_variable]
.
.
.
[/event]
Now, if we want to change the value to something else later on, e.g. 'Goodbye World', we can use the exact same code as above.
If we want to add something to our message we need to use this:

[event]
.
.
.
[set_variable]
name=message_to_the_world
value= _ "$message_to_the_world Have a nice day!"
[/set_variable]
.
.
.
[/event]
We've been using text variables (called strings) for now. But we can also store numbers and do some basic math with them. The following example clarifies this:

[event]
.
.
.
[set_variable]
name=number_x
value=10
[/set_variable]
[set_variable]
name=number_x
add=-9
[/set_variable]
[set_variable]
name=number_x
multiply=200
[/set_variable]
[set_variable]
name=number_x
multiply=0.5
[/set_variable]
.
.
.
[/event]
In the above, we set a variable named ''number_x'' to the value of 10. We substract 9 (=1), multiply with 200 (=200) and divide by two (or multiply with 0.5) resulting in 10 again.

====Using Variables====
Now that we know how to create and manipulate variables, we'll learn how to use them.
First of all, you need to know what variables you always have at your disposal! In an event tag, these variables are
* side_number- the number of the current player's side (may be empty during start or prestart events)
* turn_number- the number of the current turn (may be empty during start or prestart events)
* x1- this is the x-coordinate of the location where the most recent event was triggered
* y1- this is the y-coordinate of the location where the most recent event was triggered
* x2- this is the x-coordinate of the location that assisted in triggering the most recent event
* y2- this is the y-coordinate of the location that assisted in triggering the most recent event
* unit- inside an event, this is the unit at $x1,$y1 {{DevFeature}}
* second_unit- inside an event, this is the unit at $x2,$y2 {{DevFeature}}
* this_unit- inside a standard unit filter, this is the unit currently being considered for a possible match {{DevFeature}}

Some of these are only containers for other variables. The ''unit'' variable is an example. You can acces those 'sub'-variables by using dots:
unit.hitpoints
unit.side
...

We will use $unit in an example to show you how you can use all this:
[scenario]
.
.
.
[event]
#A unit moves onto a tile:
name=moveto
[filter]
x,y=25,26
[/filter]

[set_variable]
name=unit.hitpoints
add=-5
[/set_variable]
[set_variable]
name=unit.status.poisoned
value=yes
[/set_variable]

#After we have changed the values, we need to apply them.
#We do this by using the unstore_unit tag like this:
[unstore_unit]
variable=$unit
find_vacant=no
[/unstore_unit]
[/event]
#We're finished!
.
.
.
[/scenario]

There's one tag you don't know yet, and thats the '''[unstore_unit]''' tag. To explain this tag I'll explain it's counterparts; '''[store_unit]'''. [store_unit] stores a unit, or several units, in a variables you choose. You can then manipulate those variables as described above. However, you will need to apply these changes, and this is done by using the [unstore_unit] tag. For more see [http://www.wesnoth.org/wiki/InternalActionsWML#.5Bevent.5D InternalActions].



== [[GetText]] & Translations ==
[http://www.wesnoth.org/forum/viewtopic.php?t=11445 As Viliam pointed out] (reordered his words):

Translating programs has two steps. The first step is making [...] scenarios that are
<b>possible</b> to translate; <b>preferably easy</b> to translate. [...] The second
step is the translating of the texts... leave this to translators.

So, as a campaign/scenario developer you have to make sure your campaign will be easy to translate. You can achieve this very easily by preceding all text the user might see on the screen with an underscore. This indicates it is a translatable string. [[GetText]] will then be able to look up a translation, based on your localisation settings.
To make it ever more clear, here's an example:
.
.
.
[message]
description=Konrad
message= <b>_</b> "I am mighty Konrad! I fought many dummies and now I will fight you!"
[/message]
.
.
.

The message key contains the words that will be displayed when Konrad speaks. So this is a translatable string. So it is preceded with an underscore.

Viliam also said:

The most important rule of all is: <b>Do not split sentences.</b>
In some languages placing a word in a sentence requires more than mere string concatenation.
Some languages use [http://en.wikipedia.org/wiki/Declension declension].

== Quick Tag Index ==
'''[[ScenarioWML]]''' the top level tags [scenario], [multiplayer], [test], and [tutorial]
:* [[EventWML]] how to describe an event
:** [[FilterWML]]
:** [[DirectActionsWML]], [[InterfaceActionsWML]], [[InternalActionsWML]]
:* [[SideWML]] how to describe a side
:** [[SingleUnitWML]]
:** [[BuildingScenariosShroudData]]
:* [[MapGeneratorWML]] the random map generator
:* [[TimeWML]] how to describe a day
:* [[IntroWML]] how to describe the intro screen
:* [[UtilWML]] a set of preprocessors you can use

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-07-04T15:07:48Z

Mathijs: /* Using Variables */

{{BuildingScenariosNav}}

= Building scenarios: Advanced =

== '''TODO:''' ==
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information on guidelines concerning the general layout of a scenario file
* advanced filtering
* ...

Ayone who feels like writing something, go ahead

== Advanced Events ==

===Internal Actions===
See [[InternalActionsWML]] for a complete list of all tags and values. In what folows, the basics of variable creation and manipulation is explained.

====Variables====
(This can be skipped if you're familiar with the concept of variables)

(See [[VariablesWML]] for more)

What are variables? Variables are basicly names. And with those names, we associate a certain value. You can compare this with the words, because words are associated with (several) objects, people, feelings, ... So a variable is just a way of communication: you and the computer (the Wesnoth engine really) are communicating wit each other!

The most important aspect of variables is that they can change with time. (If they don't we call them constants.) Because they change, we can use them to trigger events, or to detect something has happened. You did this already in [[BuildingScenariosIntermediate]], using the [event] tag. We only wanted to trigger the actions inside the [event] when Konrad moved onto tile 4,8. To o so we had to make use of the variables x,y and description.

Most variables provided by the engine are associated with a certain tag and can thus only be used inside them.

====Storing, Creating and Changing Variables====
These three actions can be executed in one single tag: ''''[set_variable]''''
Say we wanted to store 'Hello World' in a variable named ''message_to_the_world''. This is how we would do this:
[event]
.
.
.
[set_variable]
#The name of our variable:
name=message_to_the_world
#The value of message_to_the_world, notice the underscore!
value= _ "Hello World!"
[/set_variable]
.
.
.
[/event]
Now, if we want to change the value to something else later on, e.g. 'Goodbye World', we can use the exact same code as above.
If we want to add something to our message we need to use this:

[event]
.
.
.
[set_variable]
name=message_to_the_world
value= _ "$message_to_the_world Have a nice day!"
[/set_variable]
.
.
.
[/event]
We've been using text variables (called strings) for now. But we can also store numbers and do some basic math with them. The following example clarifies this:

[event]
.
.
.
[set_variable]
name=number_x
value=10
[/set_variable]
[set_variable]
name=number_x
add=-9
[/set_variable]
[set_variable]
name=number_x
multiply=200
[/set_variable]
[set_variable]
name=number_x
multiply=0.5
[/set_variable]
.
.
.
[/event]
In the above, we set a variable named ''number_x'' to the value of 10. We substract 9 (=1), multiply with 200 (=200) and divide by two (or multiply with 0.5) resulting in 10 again.

====Using Variables====
Now that we know how to create and manipulate variables, we'll learn how to use them.
First of all, you need to know what variables you always have at your disposal! In an event tag, these variables are
* side_number- the number of the current player's side (may be empty during start or prestart events)
* turn_number- the number of the current turn (may be empty during start or prestart events)
* x1- this is the x-coordinate of the location where the most recent event was triggered
* y1- this is the y-coordinate of the location where the most recent event was triggered
* x2- this is the x-coordinate of the location that assisted in triggering the most recent event
* y2- this is the y-coordinate of the location that assisted in triggering the most recent event
* unit- inside an event, this is the unit at $x1,$y1 {{DevFeature}}
* second_unit- inside an event, this is the unit at $x2,$y2 {{DevFeature}}
* this_unit- inside a standard unit filter, this is the unit currently being considered for a possible match {{DevFeature}}

Some of these are only containers for other variables. The ''unit'' variable is an example. You can acces those 'sub'-variables by using dots:
unit.hitpoints
unit.side
...

We will use $unit in an example to show you how you can use all this:
[scenario]
.
.
.
[event]
#A unit moves onto a tile:
name=moveto
[filter]
x,y=25,26
[/filter]

[set_variable]
name=unit.hitpoints
add=-5
[/set_variable]
[set_variable]
name=unit.status.poisoned
value=yes
[/set_variable]

#After we have changed the values, we need to apply them.
#We do this by using the unstore_unit tag like this:
[unstore_unit]
variable=$unit
find_vacant=no
[/unstore_unit]
[/event]
#We're finished!
.
.
.
[/scenario]

There's one tag you don't know yet, and thats the '''[unstore_unit]''' tag. To explain this tag I'll explain it's counterparts; '''[store_unit]'''. [store_unit] stores a unit, or several units, in a variables you choose. You can then manipulate those variables as described above. However, you will need to apply these changes, and this is done by using the [unstore_unit] tag. For more see [http://www.wesnoth.org/wiki/InternalActionsWML#.5Bevent.5D InternalActions].



== [[GetText]] & Translations ==
[http://www.wesnoth.org/forum/viewtopic.php?t=11445 As Viliam pointed out] (reordered his words):

Translating programs has two steps. The first step is making [...] scenarios that are <b>possible</b> to translate;
<b>preferably easy</b> to translate. [...] The second step is the translating of the texts... leave this to translators.

So, as a campaign/scenario developer you have to make sure your campaign will be easy to translate. You can achieve this very easily by preceding all text the user might see on the screen with an underscore. This indicates it is a translatable string. [[GetText]] will then be able to look up a translation, based on your localisation settings.
To make it ever more clear, here's an example:
.
.
.
[message]
description=Konrad
message= <b>_</b> "I am mighty Konrad! I fought many dummies and now I will fight you!"
[/message]
.
.
.

The message key contains the words that will be displayed when Konrad speaks. So this is a translatable string. So it is preceded with an underscore.

Viliam also said:

The most important rule of all is: <b>Do not split sentences.</b>
In some languages placing a word in a sentence requires more than mere string concatenation.
Some languages use [http://en.wikipedia.org/wiki/Declension declension].

== Quick Tag Index ==
'''[[ScenarioWML]]''' the top level tags [scenario], [multiplayer], [test], and [tutorial]
:* [[EventWML]] how to describe an event
:** [[FilterWML]]
:** [[DirectActionsWML]], [[InterfaceActionsWML]], [[InternalActionsWML]]
:* [[SideWML]] how to describe a side
:** [[SingleUnitWML]]
:** [[BuildingScenariosShroudData]]
:* [[MapGeneratorWML]] the random map generator
:* [[TimeWML]] how to describe a day
:* [[IntroWML]] how to describe the intro screen
:* [[UtilWML]] a set of preprocessors you can use

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-07-04T15:03:48Z

Mathijs: /* Filters & Events */

{{BuildingScenariosNav}}

= Building scenarios: Advanced =

== '''TODO:''' ==
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information on guidelines concerning the general layout of a scenario file
* advanced filtering
* ...

Ayone who feels like writing something, go ahead

== Advanced Events ==

===Internal Actions===
See [[InternalActionsWML]] for a complete list of all tags and values. In what folows, the basics of variable creation and manipulation is explained.

====Variables====
(This can be skipped if you're familiar with the concept of variables)

(See [[VariablesWML]] for more)

What are variables? Variables are basicly names. And with those names, we associate a certain value. You can compare this with the words, because words are associated with (several) objects, people, feelings, ... So a variable is just a way of communication: you and the computer (the Wesnoth engine really) are communicating wit each other!

The most important aspect of variables is that they can change with time. (If they don't we call them constants.) Because they change, we can use them to trigger events, or to detect something has happened. You did this already in [[BuildingScenariosIntermediate]], using the [event] tag. We only wanted to trigger the actions inside the [event] when Konrad moved onto tile 4,8. To o so we had to make use of the variables x,y and description.

Most variables provided by the engine are associated with a certain tag and can thus only be used inside them.

====Storing, Creating and Changing Variables====
These three actions can be executed in one single tag: ''''[set_variable]''''
Say we wanted to store 'Hello World' in a variable named ''message_to_the_world''. This is how we would do this:
[event]
.
.
.
[set_variable]
#The name of our variable:
name=message_to_the_world
#The value of message_to_the_world, notice the underscore!
value= _ "Hello World!"
[/set_variable]
.
.
.
[/event]
Now, if we want to change the value to something else later on, e.g. 'Goodbye World', we can use the exact same code as above.
If we want to add something to our message we need to use this:

[event]
.
.
.
[set_variable]
name=message_to_the_world
value= _ "$message_to_the_world Have a nice day!"
[/set_variable]
.
.
.
[/event]
We've been using text variables (called strings) for now. But we can also store numbers and do some basic math with them. The following example clarifies this:

[event]
.
.
.
[set_variable]
name=number_x
value=10
[/set_variable]
[set_variable]
name=number_x
add=-9
[/set_variable]
[set_variable]
name=number_x
multiply=200
[/set_variable]
[set_variable]
name=number_x
multiply=0.5
[/set_variable]
.
.
.
[/event]
In the above, we set a variable named ''number_x'' to the value of 10. We substract 9 (=1), multiply with 200 (=200) and divide by two (or multiply with 0.5) resulting in 10 again.

====Using Variables====
Now that we know how to create and manipulate variables, we'll learn how to use them.
First of all, you need to know what variables you always have at your disposal! In an event tag, these variables are
* side_number- the number of the current player's side (may be empty during start or prestart events)
* turn_number- the number of the current turn (may be empty during start or prestart events)
* x1- this is the x-coordinate of the location where the most recent event was triggered
* y1- this is the y-coordinate of the location where the most recent event was triggered
* x2- this is the x-coordinate of the location that assisted in triggering the most recent event
* y2- this is the y-coordinate of the location that assisted in triggering the most recent event
* unit- inside an event, this is the unit at $x1,$y1 {{DevFeature}}
* second_unit- inside an event, this is the unit at $x2,$y2 {{DevFeature}}
* this_unit- inside a standard unit filter, this is the unit currently being considered for a possible match {{DevFeature}}

Some of these are only containers for other variables. The ''unit'' variable is an example. You can acces those 'sub'-variables by using dots:
unit.hitpoints
unit.side
...

We will use $unit in an example to show you how you can use all this:
[scenario]
.
.
.
[event]
#A unit moves onto a tile:
name=moveto
[filter]
x,y=25,26
[/filter]

[set_variable]
name=unit.hitpoints
add=-5
[/set_variable]
[set_variable]
name=unit.status.poisoned
value=yes
[/set_variable]

#After we have changed the values, we need to apply them.
#We do this by using the unstore_unit tag like this:
[unstore_unit]
variable=$unit
find_vacant=no
[/unstore_unit]
[/event]
#We're finished!
.
.
.
[/scenario]

There's one tag you don't know yet, and thats the ''''[unstore_unit]''''' tag. To explain this tag I'll explain it's counterparts; '''''[store_unit]'''''. [store_unit] stores a unit, or several units, in a variables you choose. You can then manipulate those variables as described above. However, you will need to apply these changes, and this is done by using the [unstore_unit] tag. For more see [InternalActionsWML#.5Bevent.5D InternalActions].



== [[GetText]] & Translations ==
[http://www.wesnoth.org/forum/viewtopic.php?t=11445 As Viliam pointed out] (reordered his words):

Translating programs has two steps. The first step is making [...] scenarios that are <b>possible</b> to translate;
<b>preferably easy</b> to translate. [...] The second step is the translating of the texts... leave this to translators.

So, as a campaign/scenario developer you have to make sure your campaign will be easy to translate. You can achieve this very easily by preceding all text the user might see on the screen with an underscore. This indicates it is a translatable string. [[GetText]] will then be able to look up a translation, based on your localisation settings.
To make it ever more clear, here's an example:
.
.
.
[message]
description=Konrad
message= <b>_</b> "I am mighty Konrad! I fought many dummies and now I will fight you!"
[/message]
.
.
.

The message key contains the words that will be displayed when Konrad speaks. So this is a translatable string. So it is preceded with an underscore.

Viliam also said:

The most important rule of all is: <b>Do not split sentences.</b>
In some languages placing a word in a sentence requires more than mere string concatenation.
Some languages use [http://en.wikipedia.org/wiki/Declension declension].

== Quick Tag Index ==
'''[[ScenarioWML]]''' the top level tags [scenario], [multiplayer], [test], and [tutorial]
:* [[EventWML]] how to describe an event
:** [[FilterWML]]
:** [[DirectActionsWML]], [[InterfaceActionsWML]], [[InternalActionsWML]]
:* [[SideWML]] how to describe a side
:** [[SingleUnitWML]]
:** [[BuildingScenariosShroudData]]
:* [[MapGeneratorWML]] the random map generator
:* [[TimeWML]] how to describe a day
:* [[IntroWML]] how to describe the intro screen
:* [[UtilWML]] a set of preprocessors you can use

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-06-28T15:53:40Z

Mathijs: /* Filters & Events */

BuildingScenariosAdvanced

2007-06-28T15:52:46Z

Mathijs: /* Filters & Events */

BuildingScenariosAdvanced

2007-06-28T15:51:49Z

Mathijs: /* Building scenarios: Advanced - added an example for events and filters*/

BuildingScenariosAdvanced

2007-06-28T15:24:29Z

Mathijs: /* '''TODO:''' */

BuildingScenariosAdvanced

2007-06-28T15:23:51Z

Mathijs: /* '''TODO:''' */

BuildingScenariosAdvanced

2007-06-28T15:23:12Z

Mathijs: /* Building scenarios: Advanced */

WesnothTranslationsHowTo

2007-06-28T15:07:27Z

Mathijs: /* Translations How-To */

This page contains information on how-to translate and submit translation updates.

== How to submit your translations ==

'' ''' Translation Maintainers ''' ''

The translation maintainers should send the updated/new translation
po-files to the language coordinator:
Ivanovic (crazy-ivanovic AT gmx DOT net) or
Torangan (david AT torangan DOT de).
Additionally they have to quickly check over other people's translations
(other people translating the same language) as the other translators
(if any) will have to send their translations to their language maintainer
before inclusion in the SVN (the online source code repository). You should also subscribe to the [http://www.wesnoth.org/wiki/WesnothTranslations#Mailing_List wesnoth-i18n mailinglist].

Send the files as an archive containing the complete .po files (no .mo or .gmo files) and ensure that they follow the directory structure used in version control. For example, the archive with the German (de) translations should therefore be structured as follows:
wesnoth/de.po
wesnoth-httt/de.po
wesnoth-tutorial/de.po
etc.

'' ''' Translators ''' ''

The other translators (those who are not maintainers) should contact
the maintainer for their language to see if there is some work to do.
After you have done some work on the translation you should email it
to your language maintainer. He/she will then (if needed) check it over
before sending it on to the language coordinators. A list of all translators
currently working on a language is found on each language page.

'' ''' NEW Translators ''' ''

If you want to help out with the translation of an language already started on,
contact the translation maintainer for the language.
If you want to start translation of Wesnoth to a new language,
first contact Ivanovic or Torangan.
And then just follow the instructions written in '' Translators '' .

== Translations How-To ==

Notes:
* If you haven't got Wesnoth from latest SVN, start out by doing so.
Take a look at [[WesnothSVN]] for instructions about that.
* The old translation system, using cfg files and some wesnoth-specific
tools (make_translation, merge_translation, weslang) was abandoned
in the 0.8.3 release of Wesnoth in favor of the standard [[GetText|GNU GetText]] system.
* Infos how the two branches do work can be found in the [http://www.wesnoth.org/forum/viewtopic.php?t=7618 Forum].

If you are a translator, see [[GettextForTranslators]] for more information.

If you are a developer, gettext internals for Wesnoth are discussed here:
[[GettextForWesnothDevelopers]].

== Specifying typefaces and fonts for a translation ==

Translations in a language which mainly uses characters outside of the Latin1 character set may want to specify different typefaces. In the translatable strings, there is a string named
"DejaVuSans.ttf,FreeSans.ttf,sazanami-gothic.ttf,gkai00mp.ttf"
which specifies the order in which fonts are to be tried, for each character, before the program finds a font which contains this character: the font appearing first in the list is tried first. Translators may change this string in the translation.
For example, it would be a good idea to specify first a font which contains all the characters generally used in the target language. This is especially important for translations into Asian languages. Please refer to the page [[WesnothAsianLanguages]] for more information.

== See Also ==
* [[GettextForTranslators]]
* [[WesnothAsianLanguages]]
* [[WesnothTranslations]]
* [[TranslatorsGuide]]
* [http://gettext.wesnoth.org Translation statistics]

Races

2007-06-28T15:01:53Z

Mathijs: /* Woses: removed ancient and elder wose/sorry mistaken */

== The Six Main Races ==

=== Men ===
The race of men is an extremely diverse one. Although men originally came from the Old Continent, they have spread all over the world, and split into many different cultures and races. They do not possess much magic, though they can learn it, and can learn many more types of it than most others. They have no extra special abilities or aptitudes except their versatility and drive. Although often at odds with all races, they can occasionally form alliances with the less aggressive races such as elves and dwarves, and the less scrupulous among them do not shrink back from hiring orcish mercenaries, either. They have no natural enemies, although the majority of men, like most people of all races, have an instinctive dislike of the undead. Men are shorter than the elves, but taller still than dwarves or orcs. Their skin color can vary, from almost white to dark brown.

==== Wesnothians ====
Many different groups of men exist, but the majority of them on the Great Continent live in the country of Wesnoth. The Wesnothians first appeared on the Great Continent from a land far across the ocean to the West, the Green Isle. Their capital city is Weldyn. The country is protected by the soldiers of the Wesnothian Army, the most organized military force in the known world. Its warriors come from the main provinces, where all men are conscripted at an early age.
* [[unit:Bowman|Bowman]]
* [[unit:Cavalryman|Cavalryman]]
* [[unit:Fencer|Fencer]]
* [[unit:HeavyInfantryman|HeavyInfantryman]]
* [[unit:Mage|Mage]]
* [[unit:Spearman|Spearman]]

==== The Clansmen ====
The eastern provinces of Wesnoth, known as the Clan Homelands, have a geography consisting of more open plains and rolling hills than the western, more civilized provinces. They are home to the Horse Clans, who are allied with the Wesnothian Army but are somewhat separate, and maintain their own identity - as well as their own army. Some consider them to be a tributary state, that sends food and soldiers to Wesnoth in exchange for protection; others say they are on equal footing with the western half of Wesnoth, and they just serve different purposes in the country. In any case, the eastern provinces do not have a conscript army the way Western Wesnoth does. Training for fighting is part of the way of life of the Clans, so the parents will teach the children to ride horses, fight and shoot a bow from an early age. In general, the Clan warriors are less organized than the Civilized fighters, and their strengths and weaknesses complement each other.
* [[unit:Bowman|Bowman]]
* [[unit:Horseman|Horseman]]

==== Outlaws and Necromancers ====
Bands of outlaws roam the wild areas of the Great Continent, stealing from unprotected villages. Most would run in fear if faced by a true army, but the more skilled of them would not be afraid to walk right into an opponent's camp, assassinate their leader, and run away.

Although the art of necromancy is outlawed in Wesnoth, some mages choose to practice it, starting them on the road to Lichdom.

* [[unit:Footpad|Footpad]]
* [[unit:Poacher|Poacher]]
* [[unit:Thief|Thief]]
* [[unit:Bandit|Bandit]]

* [[unit:DarkAdept|DarkAdept]]

=== Elves ===

Elves are the elder race. They are skilled with the bow and arrow - almost all of them carry one - and are also good with the sword. They do not use many weapons but these, although they are in command of powerful magic, and do use it when needed. Physically, Elves are quite tall, and seem even taller due to their slimness. They are peaceful beings, but will fight against any who enter their homeland unasked. They live mostly in the forests of the Southwest, although some choose to live in the harsh Northlands.
* [[unit:ElvishArcher|ElvishArcher]]
* [[unit:ElvishFighter|ElvishFighter]]
* [[unit:ElvishScout|ElvishScout]]
* [[unit:ElvishShaman|ElvishShaman]]

=== Orcs ===

Orcs are a race of fierce, brown-skinned human-like creatures found across the wild places of the world. They came from across the sea, following the humans of the Green Isle. They are violent, quick-tempered, and belligerent, and hold an ancient hatred for the race of elves. Although orcs are disorganized and prone to infighting, warbands under a strong leader can cut bloody inroads into the boundaries where civilization meets wilderness. Most live in the Northland, away from the settled land of Wesnoth, whose people they are more often than not at war with. They are a greedy race, and
often can be found fighting under the banner of a lich-lord or human, hoping to gain riches from those they defeat.
* [[unit:OrcishArcher|OrcishArcher]]
* [[unit:OrcishAssassin|OrcishAssassin]]
* [[unit:OrcishGrunt|OrcishGrunt]]

Goblins are a different breed than the orcs, smaller and weaker, but quicker. However, since they are the same species, they are considered by most the same race.
* [[unit:WolfRider|WolfRider]]
* [[unit:GoblinSpearman|GoblinSpearman]]

=== Dwarves ===

Dwarves were living on the Great Continent before Haldric arrived, but they were also immigrants, like him, coming from the East across the mountains. Dwarves are the height of human children, but are stronger than even fully grown men.
They are a solitary folk, cautious and slow to anger, but once their anger is roused they are terrible fighters.
Wielding many weapons with equal skill, dwarves are effective against many different races. They see in pitch darkness due to their constant work underground, and their heavy armor protects them against almost any physical attack, although magic can harm them effectively. The most skilled smiths of any in the realm, they are often hired by foreign kings to craft magical items, and the weapons and jewelry they make have been the cause of numerous wars.
* [[unit:DwarvishFighter|DwarvishFighter]]
* [[unit:DwarvishGuardsman|DwarvishGuardsman]]
* [[unit:DwarvishThunderer|DwarvishThunderer]]
* [[unit:DwarvishUlfserker|DwarvishUlfserker]]
* [[unit:GryphonRider|GryphonRider]]

=== Undead ===

As their race's name means, these are lost souls caught between this realm and next. Themselves deprived of life, they wish to likewise deprive all others of it. They are created by Necromancers, practitioners of dark magic, and are controlled by them when raised. After the necromancer controlling them dies, they remain in this world, and continue fighting for a purpose no one, perhaps not even themselves, know. Most of them are strong against physical attacks, but are weak against fire and holy assaults. Since they do not require bodily warmth to survive, cold is very ineffectual
against them.
* [[unit:Ghost|Ghost]]
* [[unit:Ghoul|Ghoul]]
* [[unit:Skeleton|Skeleton]]
* [[unit:SkeletonArcher|SkeletonArcher]]
* [[unit:VampireBat|VampireBat]]
* [[unit:WalkingCorpse|WalkingCorpse]]

=== Drakes ===

Drakes are the sons of dragons, almost the last legacy of those mighty beasts.
Most of the race can fly and spit fire.
When the fire in their body is extinguished so is their life.
Because of this they are weak against cold, but they are good against most other attacks.
However, due to their soft underbellies, "sharp, pointy weapons" have always been their weakness, a characteristic most consider very dragonlike. They are heavy and move slowly, but once they reach their enemy they are devastating.
Their homeland was an island named Morogor, located between Wesnoth and the Green Isle, but it slowly sank into the sea, and now many of them are nomads, flying over the sea looking for a place to settle undisturbed.
* [[unit:DrakeBurner|DrakeBurner]]
* [[unit:DrakeClasher|DrakeClasher]]
* [[unit:DrakeFighter|DrakeFighter]]
* [[unit:DrakeGlider|DrakeGlider]]

== Other Races ==

There are other races than these six main ones. They often align with the larger races, but these alliances are usually not permanent.

=== Saurians ===
These are the smaller, more crafty allies of the Drakes. They often live in swamps or other damp places.
* [[unit:SaurianSkirmisher|SaurianSkirmisher]]
* [[unit:SaurianTribalist|SaurianTribalist]]

=== Merfolk ===
The Merfolk live in the shallow parts of the ocean, wary of the monsters that lurk in the deep. Ordinarily they form alliances with no one, but in Asheviere's time they allied with the elves in order to defeat their captors. Mermen are powerful and quick in any watery environment, but struggle greatly to move on land.
* [[unit:MermaidInitiate|MermaidInitiate]]
* [[unit:MermanFighter|MermanFighter]]
* [[unit:MermanHunter|MermanHunter]]

=== Nagas ===
Nagas are the long time enemies of the Merfolk, and in Asheviere's time they allied with orcs to finally defeat their opponents. They usually join forces with anyone willing to help them defeat the mermen.
* [[unit:NagaFighter|NagaFighter]]

=== Ogres ===
The Ogres are wild beasts that live in the Northlands, but the Wesnothian army occasionally captures them and trains them for battle. They are extremely brutish and stupid, but possess enough intelligence to wield a weapon.
* [[unit:YoungOgre|YoungOgre]]

=== Trolls ===
The Trolls are slightly more intelligent than Ogres, and ally with the Orcs whenever their shared homeland is in danger. However, most of the time they avoid each other.
* [[unit:TrollWhelp|TrollWhelp]]

===Woses===
Little is known about the Woses, apart from their tree-like appearance. However these beings have not descended from trees, despite the similarity in form. They seem to be wardens of the natural world.
* [[unit:Wose|Wose]]

=== Monsters ===

There are many monsters that roam about the land, not obeying anyone's orders. Occasionally, but not often, those who see them survive to tell the tale, and it is only from them that the people of Wesnoth know of their existence.
* [[unit:Cockatrice|Cockatrice]]
* [[unit:Cuttlefish|Cuttlefish]]
* [[unit:FireDragon|FireDragon]]
* [[unit:GiantScorpion|GiantScorpion]]
* [[unit:GiantSpider|GiantSpider]]
* [[unit:Gryphon|Gryphon]]
* [[unit:Mudcrawler|Mudcrawler]]
* [[unit:SeaSerpent|SeaSerpent]]
* [[unit:Yeti|Yeti]]

See Also:
* [[UnitDescriptionRewriting]] - coordinating the revision

Races

2007-06-28T14:59:19Z

Mathijs: /* Woses: added ancient and elder wose */

== The Six Main Races ==

=== Men ===
The race of men is an extremely diverse one. Although men originally came from the Old Continent, they have spread all over the world, and split into many different cultures and races. They do not possess much magic, though they can learn it, and can learn many more types of it than most others. They have no extra special abilities or aptitudes except their versatility and drive. Although often at odds with all races, they can occasionally form alliances with the less aggressive races such as elves and dwarves, and the less scrupulous among them do not shrink back from hiring orcish mercenaries, either. They have no natural enemies, although the majority of men, like most people of all races, have an instinctive dislike of the undead. Men are shorter than the elves, but taller still than dwarves or orcs. Their skin color can vary, from almost white to dark brown.

==== Wesnothians ====
Many different groups of men exist, but the majority of them on the Great Continent live in the country of Wesnoth. The Wesnothians first appeared on the Great Continent from a land far across the ocean to the West, the Green Isle. Their capital city is Weldyn. The country is protected by the soldiers of the Wesnothian Army, the most organized military force in the known world. Its warriors come from the main provinces, where all men are conscripted at an early age.
* [[unit:Bowman|Bowman]]
* [[unit:Cavalryman|Cavalryman]]
* [[unit:Fencer|Fencer]]
* [[unit:HeavyInfantryman|HeavyInfantryman]]
* [[unit:Mage|Mage]]
* [[unit:Spearman|Spearman]]

==== The Clansmen ====
The eastern provinces of Wesnoth, known as the Clan Homelands, have a geography consisting of more open plains and rolling hills than the western, more civilized provinces. They are home to the Horse Clans, who are allied with the Wesnothian Army but are somewhat separate, and maintain their own identity - as well as their own army. Some consider them to be a tributary state, that sends food and soldiers to Wesnoth in exchange for protection; others say they are on equal footing with the western half of Wesnoth, and they just serve different purposes in the country. In any case, the eastern provinces do not have a conscript army the way Western Wesnoth does. Training for fighting is part of the way of life of the Clans, so the parents will teach the children to ride horses, fight and shoot a bow from an early age. In general, the Clan warriors are less organized than the Civilized fighters, and their strengths and weaknesses complement each other.
* [[unit:Bowman|Bowman]]
* [[unit:Horseman|Horseman]]

==== Outlaws and Necromancers ====
Bands of outlaws roam the wild areas of the Great Continent, stealing from unprotected villages. Most would run in fear if faced by a true army, but the more skilled of them would not be afraid to walk right into an opponent's camp, assassinate their leader, and run away.

Although the art of necromancy is outlawed in Wesnoth, some mages choose to practice it, starting them on the road to Lichdom.

* [[unit:Footpad|Footpad]]
* [[unit:Poacher|Poacher]]
* [[unit:Thief|Thief]]
* [[unit:Bandit|Bandit]]

* [[unit:DarkAdept|DarkAdept]]

=== Elves ===

Elves are the elder race. They are skilled with the bow and arrow - almost all of them carry one - and are also good with the sword. They do not use many weapons but these, although they are in command of powerful magic, and do use it when needed. Physically, Elves are quite tall, and seem even taller due to their slimness. They are peaceful beings, but will fight against any who enter their homeland unasked. They live mostly in the forests of the Southwest, although some choose to live in the harsh Northlands.
* [[unit:ElvishArcher|ElvishArcher]]
* [[unit:ElvishFighter|ElvishFighter]]
* [[unit:ElvishScout|ElvishScout]]
* [[unit:ElvishShaman|ElvishShaman]]

=== Orcs ===

Orcs are a race of fierce, brown-skinned human-like creatures found across the wild places of the world. They came from across the sea, following the humans of the Green Isle. They are violent, quick-tempered, and belligerent, and hold an ancient hatred for the race of elves. Although orcs are disorganized and prone to infighting, warbands under a strong leader can cut bloody inroads into the boundaries where civilization meets wilderness. Most live in the Northland, away from the settled land of Wesnoth, whose people they are more often than not at war with. They are a greedy race, and
often can be found fighting under the banner of a lich-lord or human, hoping to gain riches from those they defeat.
* [[unit:OrcishArcher|OrcishArcher]]
* [[unit:OrcishAssassin|OrcishAssassin]]
* [[unit:OrcishGrunt|OrcishGrunt]]

Goblins are a different breed than the orcs, smaller and weaker, but quicker. However, since they are the same species, they are considered by most the same race.
* [[unit:WolfRider|WolfRider]]
* [[unit:GoblinSpearman|GoblinSpearman]]

=== Dwarves ===

Dwarves were living on the Great Continent before Haldric arrived, but they were also immigrants, like him, coming from the East across the mountains. Dwarves are the height of human children, but are stronger than even fully grown men.
They are a solitary folk, cautious and slow to anger, but once their anger is roused they are terrible fighters.
Wielding many weapons with equal skill, dwarves are effective against many different races. They see in pitch darkness due to their constant work underground, and their heavy armor protects them against almost any physical attack, although magic can harm them effectively. The most skilled smiths of any in the realm, they are often hired by foreign kings to craft magical items, and the weapons and jewelry they make have been the cause of numerous wars.
* [[unit:DwarvishFighter|DwarvishFighter]]
* [[unit:DwarvishGuardsman|DwarvishGuardsman]]
* [[unit:DwarvishThunderer|DwarvishThunderer]]
* [[unit:DwarvishUlfserker|DwarvishUlfserker]]
* [[unit:GryphonRider|GryphonRider]]

=== Undead ===

As their race's name means, these are lost souls caught between this realm and next. Themselves deprived of life, they wish to likewise deprive all others of it. They are created by Necromancers, practitioners of dark magic, and are controlled by them when raised. After the necromancer controlling them dies, they remain in this world, and continue fighting for a purpose no one, perhaps not even themselves, know. Most of them are strong against physical attacks, but are weak against fire and holy assaults. Since they do not require bodily warmth to survive, cold is very ineffectual
against them.
* [[unit:Ghost|Ghost]]
* [[unit:Ghoul|Ghoul]]
* [[unit:Skeleton|Skeleton]]
* [[unit:SkeletonArcher|SkeletonArcher]]
* [[unit:VampireBat|VampireBat]]
* [[unit:WalkingCorpse|WalkingCorpse]]

=== Drakes ===

Drakes are the sons of dragons, almost the last legacy of those mighty beasts.
Most of the race can fly and spit fire.
When the fire in their body is extinguished so is their life.
Because of this they are weak against cold, but they are good against most other attacks.
However, due to their soft underbellies, "sharp, pointy weapons" have always been their weakness, a characteristic most consider very dragonlike. They are heavy and move slowly, but once they reach their enemy they are devastating.
Their homeland was an island named Morogor, located between Wesnoth and the Green Isle, but it slowly sank into the sea, and now many of them are nomads, flying over the sea looking for a place to settle undisturbed.
* [[unit:DrakeBurner|DrakeBurner]]
* [[unit:DrakeClasher|DrakeClasher]]
* [[unit:DrakeFighter|DrakeFighter]]
* [[unit:DrakeGlider|DrakeGlider]]

== Other Races ==

There are other races than these six main ones. They often align with the larger races, but these alliances are usually not permanent.

=== Saurians ===
These are the smaller, more crafty allies of the Drakes. They often live in swamps or other damp places.
* [[unit:SaurianSkirmisher|SaurianSkirmisher]]
* [[unit:SaurianTribalist|SaurianTribalist]]

=== Merfolk ===
The Merfolk live in the shallow parts of the ocean, wary of the monsters that lurk in the deep. Ordinarily they form alliances with no one, but in Asheviere's time they allied with the elves in order to defeat their captors. Mermen are powerful and quick in any watery environment, but struggle greatly to move on land.
* [[unit:MermaidInitiate|MermaidInitiate]]
* [[unit:MermanFighter|MermanFighter]]
* [[unit:MermanHunter|MermanHunter]]

=== Nagas ===
Nagas are the long time enemies of the Merfolk, and in Asheviere's time they allied with orcs to finally defeat their opponents. They usually join forces with anyone willing to help them defeat the mermen.
* [[unit:NagaFighter|NagaFighter]]

=== Ogres ===
The Ogres are wild beasts that live in the Northlands, but the Wesnothian army occasionally captures them and trains them for battle. They are extremely brutish and stupid, but possess enough intelligence to wield a weapon.
* [[unit:YoungOgre|YoungOgre]]

=== Trolls ===
The Trolls are slightly more intelligent than Ogres, and ally with the Orcs whenever their shared homeland is in danger. However, most of the time they avoid each other.
* [[unit:TrollWhelp|TrollWhelp]]

===Woses===
Little is known about the Woses, apart from their tree-like appearance. However these beings have not descended from trees, despite the similarity in form. They seem to be wardens of the natural world.
* [[unit:Wose|Wose]]
* [[unit:ElderWose|Elder Wose]]
* [[unit:AncientWose|Ancient Wose]]

=== Monsters ===

There are many monsters that roam about the land, not obeying anyone's orders. Occasionally, but not often, those who see them survive to tell the tale, and it is only from them that the people of Wesnoth know of their existence.
* [[unit:Cockatrice|Cockatrice]]
* [[unit:Cuttlefish|Cuttlefish]]
* [[unit:FireDragon|FireDragon]]
* [[unit:GiantScorpion|GiantScorpion]]
* [[unit:GiantSpider|GiantSpider]]
* [[unit:Gryphon|Gryphon]]
* [[unit:Mudcrawler|Mudcrawler]]
* [[unit:SeaSerpent|SeaSerpent]]
* [[unit:Yeti|Yeti]]

See Also:
* [[UnitDescriptionRewriting]] - coordinating the revision

Races

2007-06-28T14:57:41Z

Mathijs: /* Woses */

BuildingScenariosSimple

2007-06-28T07:54:45Z

Mathijs: /* Building scenarios: Simple */

{{BuildingScenariosNav}}

= Learning things step by step =

This will show you a very simple scenario file, explaining each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove usefull to read something about the syntax used in the Wesnoth Markup Language: [[SyntaxWML]]'''

== First part ==
[scenario]

id=test-1
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]
. continued below
. ||
. \/

Every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario:
* The ''id'' (short for ''identifier'') is the computer's name for your scenario, and is not displayed during the game. However, it will be used to display game statistics (they will be graphed on http://stats.wesnoth.org in numerical order, so it's also a good idea to give the id's a number). This name is also used as reference in other tags and files, eg inside a '''[campaign]''' tag using the ''first_scenario'' key(see [[BuildingCampaignsTheCampaignFile]]) or inside a '''[scenario]''' tag using the ''next_scenario'' key (see below).

* The value of the ''next_scenario'' key is the id (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put '''next_scenario=null''' inside the file. This will tell the game to display the End screen when this scenario is won.

* The value of the ''name'' key is shown on the introduction screen before each scenario is played. (This can contain a picture of a map, or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explenation on how to do that.) It's also the default name for saves on the level.

* The next key, ''map_data'', is a link to the map file. You can create map files using the Wesnoth Map Editor (see [[WesnothMapEditor]] and [[BuildingMaps]] for more information). Since we may not know exactly where this campaign will be located we'll write two possible locations of the map file. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used to indicate where the data begins and ends. If you don't do this, it will break the scenario.

* Finally, the last key in the top set of keys is ''turns''. This is the amount of turns a player is given to finish the scenario. (It can be changed during the game, but again, that is stuff for later.) When the player fails to finish the secnario in the given time, he has lost. (Said otherwise: the ''defeat'' event is trigered. See [[EventWML]] for more.)

The next section is a set of preprocessors (see [[PreprocessorRef]]). Preprocessors are essentially WML shortcuts. They allow you to define certain pieces of code and re-use it whenever it is needed. Wesnoth provides you with a whole serie of standard preprocessors to make life more easy, but you yourself can define them too (again stuff for later).
Lets get back to this example! The preprocessors used here, describe how a day in this scenario should progress. This listing above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the preprocessors except for '''{SECOND_WATCH}'''. This could be useful if you have Konrad
fighting the Undead and want the Undead to have the upper hand the whole time. Remember though, by setting this to a single tme of day and not the normal progress listed above, your scenario will effectively be taking place during one day or night, not many days as most scenarios are.

The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.

A tag you'll get to know very good when making scenarios shows up: '''[event]...[/event]'''.
Event tags are used to describe what should be done if an 'event' takes place. What this event is, is described by ''name''key. In this case we're describing the so-called 'prestart' event. This one takes place just ''before'' the game starts and just ''after'' all of the introductions screens were shown.
Here we have limited the contents of the tag to another important tag: '''[objectives]''' (plural) containing any number of '''[objective]''' (singular) tags.
For each '''[objective]''' (singular) tag, if ''condition'' is set to "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is set to "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives. Because we've placed this tag inside a prestart event, this will be shown at the very first turn of the scenario.
The ''side'' key indicates that these conditions are for side 1 (see below).
The ' _ ' (underscore) facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.
Also note that the '''[objective]''' tag only describes what the objectives are. You will still need to set the appropiate events before they will work. (But that's again stuff for later)

== Second part ==
So far so good! The last necessary part describes what the players (Human and
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.

. /\
. ||
. continued from above
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]

Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
* ''side'': the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]) It's a number from 1 to 9.
* ''controller'': possible values are 'human' or 'ai' (artificial intelligence, meaning your computer). If you don't specify this key, 'ai' is used as the default.
* ''team_name'' describes which team the side is on. It defaults to the same number as ''side'', so setting it to ''2'' allies this side with side 2, if you haven't changed the team_name of side 2.
* ''user_team_name'' is the name displayed when you view the sie stats (by pressing alt+s during gameplay). The underscore facilitates translation using GetText (see [[GetText]]).

The next set of keys describe the leader of this side:
* ''canrecruit'': This key can be '1' or '0', meaning "yes" or "no" respectively. If you no, then the leader won't be able to recruit. (Not much of a leader then, is he?) Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
* ''type'' describes what type of unit the leader will be. The possible values are listed here: [[UnitTables]].
* ''description'' is the name and description of the leader.
In a campaign, all of these 'leader-describing' keys are ignored for the human player (except ''canrecruit''), since the leader from the previous scenario is used instead. However, the ''type'' key is still neccesary to prevent the scenario from crashing.

* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].

Then two more preprocessors are used:
* '''{GOLD easy normal hard}''' takes 3 positive numbers. These indicate the amount of money the player will start with on the EASY, NORMAL and HARD difficulty level.
In a campaign file, inside a human controlled side (''controller=human''), this is the minimum amount. The actual amount the player gets ca, be larger if the player retained more from previous scenarios.
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
The defaults for each of these values are 100 gold and 2 base income.

== Making it all work ==
Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
This should NOT be stored inside the main directory '''data/campaigns''' but inside '''userdata/data/campaigns'''. This prevents breaking the mainline campaigns or even worse, the entire game. (see [[BuildingCampaignsDirectoryStructure]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending .cfg (for example: testcampaign.cfg).
This is a short example on how to do this:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are described in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign. Scenarios following after this one are referenced inside the first scenario using ''next_scenario'' (see above).

The key '''difficulties=EASY,NORMAL,HARD''' tells the computer to set the macro '''EASY''' if the first difficulty choice is chosen, '''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
It is recommended that you do not use other names than '''EASY''', '''NORMAL''', and '''HARD''' for your macros, because if you do then the standard macros, such as '''{GOLD}''' and '''{INCOME}''', won't work properly.

Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image, displayed inside the campaign list.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to:
"difficulties=EASY,NORMAL,HARD"
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
then an equals (''='') sign, then the text to display (eg ''Easy'').
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

BuildingScenarios

2007-06-28T07:52:41Z

Mathijs: /* Index */

Wesnoth scenarios are the individual levels within the game. Each scenario contains two files. First is the map
itself, this is described in [[BuildingMaps]]. The second is the config file. This configuration file is used to
describe everything about the scenario. Both of the files are ascii and can be edited in any standard text editor (vi,
notepad, etc.) If you decide to use a wordprocessor, please make sure you remember to ''Save As'' text.

Scenarios are written in the Wesnoth Markup Language. This is a very simple language to learn.
The WML language is described in [[ReferenceWML]].
The WML syntax is described in [[SyntaxWML]].
Wesnoth has a preprocessor that allows designers to reorganize information into a more convenient structure.
The WML preprocessor is described in [[PreprocessorRef]].

This document is split into several sections, starting with a basic tutorial and moving into more complex techniques. From the information contained within this document you should have all the knowledge to create Wesnoth scenarios. If you see any mistakes or missing information, please feel free to fix the pages yourself, add a comment to the comment page, or email me jzaun at campus dot hpu dot edu.

<div class="navtemplate">
==== Index ====
[[BuildingScenarios]]
:* '''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:* [[BuildingScenariosSimple - French Version]]
:* [[BuildingScenariosComments]] - Comments left for advice
:* [[BuildingScenariosSamples]] - Basic sample code
:* [[BuildingScenariosShroudData]] - A tutorial on shroud_data
:* [[BuildingScenariosBalancing]] - How to balance your scenario
:* [[BuildingScenariosFAQ]] - Frequently Asked Questions
</div class="navtemplate">

== Quick Tag Index ==
'''[[ScenarioWML]]''' the top level tags [scenario], [multiplayer], [test], and [tutorial]
:* [[EventWML]] how to describe an event
:** [[FilterWML]]
:** [[DirectActionsWML]], [[InterfaceActionsWML]], [[InternalActionsWML]]
:* [[SideWML]] how to describe a side
:** [[SingleUnitWML]]
:** [[BuildingScenariosShroudData]]
:* [[MapGeneratorWML]] the random map generator
:* [[TimeWML]] how to describe a day
:* [[IntroWML]] how to describe the intro screen
:* [[UtilWML]] a set of preprocessors you can use

== See Also ==

* [[Create]]
* [[ReferenceWML]] - WML master reference
** [[AlphabeticalWML]] - a tag index
** [[BuildingScenariosIndex]] - in-depth key and tag index

{{Create}}

BuildingScenarios

2007-06-28T07:45:44Z

Mathijs:

Wesnoth scenarios are the individual levels within the game. Each scenario contains two files. First is the map
itself, this is described in [[BuildingMaps]]. The second is the config file. This configuration file is used to
describe everything about the scenario. Both of the files are ascii and can be edited in any standard text editor (vi,
notepad, etc.) If you decide to use a wordprocessor, please make sure you remember to ''Save As'' text.

Scenarios are written in the Wesnoth Markup Language. This is a very simple language to learn.
The WML language is described in [[ReferenceWML]].
The WML syntax is described in [[SyntaxWML]].
Wesnoth has a preprocessor that allows designers to reorganize information into a more convenient structure.
The WML preprocessor is described in [[PreprocessorRef]].

This document is split into several sections, starting with a basic tutorial and moving into more complex techniques. From the information contained within this document you should have all the knowledge to create Wesnoth scenarios. If you see any mistakes or missing information, please feel free to fix the pages yourself, add a comment to the comment page, or email me jzaun at campus dot hpu dot edu.

== Index ==

* [[BuildingScenarios]]
:: '''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:: [[BuildingScenariosSimple - French Version]]
* [[BuildingScenariosComments]] - Comments left for advice
* [[BuildingScenariosSamples]] - Basic sample code
* [[BuildingScenariosShroudData]] - A tutorial on shroud_data
* [[BuildingScenariosBalancing]] - How to balance your scenario
* [[BuildingScenariosFAQ]] - Frequently Asked Questions

== Quick Tag Index ==
'''[[ScenarioWML]]''' the top level tags [scenario], [multiplayer], [test], and [tutorial]
:* [[EventWML]] how to describe an event
:** [[FilterWML]]
:** [[DirectActionsWML]], [[InterfaceActionsWML]], [[InternalActionsWML]]
:* [[SideWML]] how to describe a side
:** [[SingleUnitWML]]
:** [[BuildingScenariosShroudData]]
:* [[MapGeneratorWML]] the random map generator
:* [[TimeWML]] how to describe a day
:* [[IntroWML]] how to describe the intro screen
:* [[UtilWML]] a set of preprocessors you can use

== See Also ==

* [[Create]]
* [[ReferenceWML]] - WML master reference
** [[AlphabeticalWML]] - a tag index
** [[BuildingScenariosIndex]] - in-depth key and tag index

{{Create}}

BuildingMaps

2007-06-27T21:23:18Z

Mathijs: /* See Also: shroud data */

This is all you need to know about maps:

# A map is just a bunch of letters arranged in a rectangle (the rectangle is known as the "map data")
# There are two ways to save this rectangle in a file

Seriously now, here are the details.

== Wesnoth map data format ==

Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:

* A map data file consists of any number of lines, each with the same number of characters.
* Each character must be either a letter specified in a ''letter'' key specifying a terrain (see [[TerrainLettersWML]]), or a digit.
* When the file is interpreted, each letter will be replaced by the terrain it refers to.
* Each nonzero digit ''n'' where ''n'' = 1, 2, 3, ... will be replaced by keep, with the leader of side ''n'' placed on the keep.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('r') tiles, the map data would look like this:

rrgggggg
ggrrgggg
ggggrrgg
ggggggrr

'''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]'''''
The map format for the new Wesnoth version has been changed so this description is for the newer version.

Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:

* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('r') tiles, the map data would look like this:

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== Creating a map ==

This is not the Matrix. You do not need to look at encoded maps. The source code and most binary distributions come with the official graphical map editor. When compiling from source, remember to use the ''--enable-editor'' option when configuring, otherwise the map editor won't be compiled. Using the map editor tends to be straightforward, judging from the feedback received from novice mapmakers. However, if you do encounter problems locating or using the editor, please ask for help on the [http://www.wesnoth.org/forum forum].

After the map is created, you may find it easier to make small tweaks by editing the textual map data directly.

Making good, balanced, interesting maps is another task altogether, and if someone wants to take a stab at sharing insight about this art, please do so.

== Using map data ==

Map data is used in two ways.
# It is used as an input to the key ''map_data'' (see [[ScenarioWML]]).
# Files consisting entirely of map data can be read and edited easily by the [[WesnothMapEditor]].
#* Files in the folder '''''userdata''/editor/maps/''' which consist entirely of map data can be played in multiplayer as user maps.

==== The map_data key ====

The first way is to use the map_data key. A campaign scenario starts with the '''[scenario]''' tag. A multiplayer map scenario starts with the '''[multiplayer]''' tag. Each tag takes the key ''map_data''. The value of the ''map_data'' key is the map data enclosed in quotes. Here is an example:
map_data="111111111111111111"

==== Standalone map file ====

The second way to store a map is in a text file that consists '''only''' of the map data. The advantage of this method is that it's simple. If you drop one of the map files in '''''userdata''/editor/maps/''', the game will find it automatically in multiplayer. On the other hand, this method also works with more complex scenarios. If there is a scenario file somewhere (campaign or multiplayer) that has a line similar to the following:
map_data="{@editor/''map_filename''}"
then all of the map data in the file is inserted between the quote marks.

== Discussion: Scenario File vs Standalone ==

Campaign writers can't write campaigns without scenarios, so campaigns will always use the ''map_data'' key, either with the raw data in quotes or a preprocessor symbol {} pointing to the standalone file.

Multiplayer mapmakers, however, '''have a choice'''. If you want to place an object or unit on the map, you must create a scenario file starting with the '''[multiplayer]''' tag and containing the ''map_data'' key therein. You lose the simplicity of the standalone map file, but you gain tremendous power. Not only can you add units and objects, you can set allies, experience modifiers, add a map description, and add custom events (among other things). The question, "How do I place an object on the map with the map editor" is such a common question that I am sorry this information is buried so deeply here. But, now that you know you can seek out an example of a multiplayer map scenario file to use as an example. The game comes with many maps of each type. Check out [[BuildingMultiplayer]] for more information.

== See Also ==

* [[Create]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[BuildingScenariosShroudData]]

{{Create}}

BuildingScenarios

2007-06-27T21:19:18Z

Mathijs: /* Index: * BuildingScenariosFAQ */

Wesnoth scenarios are the individual levels within the game. Each scenario contains two files. First is the map
itself, this is described in [[BuildingMaps]]. The second is the config file. This configuration file is used to
describe everything about the scenario. Both of the files are ascii and can be edited in any standard text editor (vi,
notepad, etc.) If you decide to use a wordprocessor, please make sure you remember to ''Save As'' text.

Scenarios are written in the Wesnoth Markup Language. This is a very simple language to learn.
The WML language is described in [[ReferenceWML]].
The WML syntax is described in [[SyntaxWML]].
Wesnoth has a preprocessor that allows designers to reorganize information into a more convenient structure.
The WML preprocessor is described in [[PreprocessorRef]].

This document is split into several sections, starting with a basic tutorial and moving into more complex techniques. From the information contained within this document you should have all the knowledge to create Wesnoth scenarios. If you see any mistakes or missing information, please feel free to fix the pages yourself, add a comment to the comment page, or email me jzaun at campus dot hpu dot edu.

=== Index ===

* [[BuildingScenarios]]
:: [[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:: [[BuildingScenariosSimple - French Version]]
* [[BuildingScenariosComments]]
* [[BuildingScenariosSamples]]
* [[BuildingScenariosShroudData]]
* [[BuildingScenariosBalancing]]
* [[BuildingScenariosFAQ]]

== See Also ==

* [[Create]]
* [[ReferenceWML]] - WML master reference
** [[AlphabeticalWML]] - a tag index
** [[BuildingScenariosIndex]] - in-depth key and tag index

{{Create}}

Template:BuildingScenariosNav

2007-06-27T21:17:01Z

Mathijs:

{| style="float:right"
|
__TOC__
|}
<div class="navtemplate">
==== Quick Navigation ====
'''[[BuildingScenarios]]'''
:*'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:*[[BuildingScenariosWML]]
:*[[BuildingScenariosComments]]
:*[[BuildingScenariosSamples]]
:*[[BuildingScenariosFAQ]]
</div>

Create

2007-06-27T21:11:25Z

Mathijs: /* What can I create, and how? */

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

It should also be noted that '''we need a lot of help creating artwork for the core of the game.''' The current projects we are working on are [http://www.wesnoth.org/forum/viewtopic.php?t=9162 listed here]. We'll happily help you out, if you take a swing at them.

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

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

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth_editor-1.3.4.jpg http://www.wesnoth.org/images/sshots/wesnoth_editor-1.3.4-175.jpg]
<div class="thumbcaption">Battle for Wesnoth map editor</div></div>
</div>

* [[BuildingMaps|Maps]] - the layout of terrain tiles
* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer

* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]]

* '''[[Create Art|Art]]''' - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth

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

== What have others done? ==
Quick descriptions of the campaigns and scenarios that have been published on the campaign server.
* [[UserScenarios|User contributed campaigns]]
There are a multitude multiplayer maps and discussion of the campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and campaign development forum]
* [[Complete Faction List (unfinished)|Complete Faction List]]

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

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Scenario_and_Campaigns|FAQ]] - if you have a question, post it
* Campaign server [http://wolff.to/campaigns/list.html web interface] - An alternate way to download user campaigns
* [[Status_of_User_Scenarios| Status of User Scenarios]] - Lists which usercampaigns are working and which ones are broken
{{Home}}

Template:BuildingScenariosNav

2007-06-27T21:09:26Z

Mathijs:

----
{| style="float:right"
|
__TOC__
|}
<div class="navtemplate">
==== Quick Navigation ====
'''[[BuildingScenarios]]'''
:*'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:*[[BuildingScenariosWML]]
:*[[BuildingScenariosComments]]
:*[[BuildingScenariosSamples]]
:*[[BuildingScenariosFAQ]]
</div>

Template:BuildingScenariosNav

2007-06-27T21:09:11Z

Mathijs:

----
{| style="float:right"
|
__TOC__
|}
<div class="navtemplate">
==== Quick Navigation ====
'''[[BuildingScenarios]]:'''
:*'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:*[[BuildingScenariosWML]]
:*[[BuildingScenariosComments]]
:*[[BuildingScenariosSamples]]
:*[[BuildingScenariosFAQ]]
</div>

BuildingScenariosAdvanced

2007-06-27T21:08:13Z

Mathijs: /* Added a navigation template at the top */

{{BuildingScenariosNav}}

= Building scenarios: Advanced =

'''TODO:'''
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information about GetText and making your scenario translatable
* information on guidelines concerning the general layout of a scenario file
* LOTS of links to pages any campaign editor needs frequently
* ...

Ayone who feels like writing something, go ahead

:Mathijs

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosSimple

2007-06-27T21:07:34Z

Mathijs: /* Added a navigation template at the top */

{{BuildingScenariosNav}}

= Building scenarios: Simple =

This will show you a very simple scenario file, explaining each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove usefull to read something about the syntax used in the Wesnoth Markup Language: [[SyntaxWML]]'''

== First part ==
[scenario]

id=test-1
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]
. continued below
. ||
. \/

Every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario:
* The ''id'' (short for ''identifier'') is the computer's name for your scenario, and is not displayed during the game. However, it will be used to display game statistics (they will be graphed on http://stats.wesnoth.org in numerical order, so it's also a good idea to give the id's a number). This name is also used as reference in other tags and files, eg inside a '''[campaign]''' tag using the ''first_scenario'' key(see [[BuildingCampaignsTheCampaignFile]]) or inside a '''[scenario]''' tag using the ''next_scenario'' key (see below).

* The value of the ''next_scenario'' key is the id (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put '''next_scenario=null''' inside the file. This will tell the game to display the End screen when this scenario is won.

* The value of the ''name'' key is shown on the introduction screen before each scenario is played. (This can contain a picture of a map, or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explenation on how to do that.) It's also the default name for saves on the level.

* The next key, ''map_data'', is a link to the map file. You can create map files using the Wesnoth Map Editor (see [[WesnothMapEditor]] and [[BuildingMaps]] for more information). Since we may not know exactly where this campaign will be located we'll write two possible locations of the map file. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used to indicate where the data begins and ends. If you don't do this, it will break the scenario.

* Finally, the last key in the top set of keys is ''turns''. This is the amount of turns a player is given to finish the scenario. (It can be changed during the game, but again, that is stuff for later.) When the player fails to finish the secnario in the given time, he has lost. (Said otherwise: the ''defeat'' event is trigered. See [[EventWML]] for more.)

The next section is a set of preprocessors (see [[PreprocessorRef]]). Preprocessors are essentially WML shortcuts. They allow you to define certain pieces of code and re-use it whenever it is needed. Wesnoth provides you with a whole serie of standard preprocessors to make life more easy, but you yourself can define them too (again stuff for later).
Lets get back to this example! The preprocessors used here, describe how a day in this scenario should progress. This listing above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the preprocessors except for '''{SECOND_WATCH}'''. This could be useful if you have Konrad
fighting the Undead and want the Undead to have the upper hand the whole time. Remember though, by setting this to a single tme of day and not the normal progress listed above, your scenario will effectively be taking place during one day or night, not many days as most scenarios are.

The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.

A tag you'll get to know very good when making scenarios shows up: '''[event]...[/event]'''.
Event tags are used to describe what should be done if an 'event' takes place. What this event is, is described by ''name''key. In this case we're describing the so-called 'prestart' event. This one takes place just ''before'' the game starts and just ''after'' all of the introductions screens were shown.
Here we have limited the contents of the tag to another important tag: '''[objectives]''' (plural) containing any number of '''[objective]''' (singular) tags.
For each '''[objective]''' (singular) tag, if ''condition'' is set to "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is set to "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives. Because we've placed this tag inside a prestart event, this will be shown at the very first turn of the scenario.
The ''side'' key indicates that these conditions are for side 1 (see below).
The ' _ ' (underscore) facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.
Also note that the '''[objective]''' tag only describes what the objectives are. You will still need to set the appropiate events before they will work. (But that's again stuff for later)

== Second part ==
So far so good! The last necessary part describes what the players (Human and
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.

. /\
. ||
. continued from above
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]

Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
* ''side'': the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]) It's a number from 1 to 9.
* ''controller'': possible values are 'human' or 'ai' (artificial intelligence, meaning your computer). If you don't specify this key, 'ai' is used as the default.
* ''team_name'' describes which team the side is on. It defaults to the same number as ''side'', so setting it to ''2'' allies this side with side 2, if you haven't changed the team_name of side 2.
* ''user_team_name'' is the name displayed when you view the sie stats (by pressing alt+s during gameplay). The underscore facilitates translation using GetText (see [[GetText]]).

The next set of keys describe the leader of this side:
* ''canrecruit'': This key can be '1' or '0', meaning "yes" or "no" respectively. If you no, then the leader won't be able to recruit. (Not much of a leader then, is he?) Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
* ''type'' describes what type of unit the leader will be. The possible values are listed here: [[UnitTables]].
* ''description'' is the name and description of the leader.
In a campaign, all of these 'leader-describing' keys are ignored for the human player (except ''canrecruit''), since the leader from the previous scenario is used instead. However, the ''type'' key is still neccesary to prevent the scenario from crashing.

* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].

Then two more preprocessors are used:
* '''{GOLD easy normal hard}''' takes 3 positive numbers. These indicate the amount of money the player will start with on the EASY, NORMAL and HARD difficulty level.
In a campaign file, inside a human controlled side (''controller=human''), this is the minimum amount. The actual amount the player gets ca, be larger if the player retained more from previous scenarios.
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
The defaults for each of these values are 100 gold and 2 base income.

== Making it all work ==
Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
This should NOT be stored inside the main directory '''data/campaigns''' but inside '''userdata/data/campaigns'''. This prevents breaking the mainline campaigns or even worse, the entire game. (see [[BuildingCampaignsDirectoryStructure]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending .cfg (for example: testcampaign.cfg).
This is a short example on how to do this:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are described in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign. Scenarios following after this one are referenced inside the first scenario using ''next_scenario'' (see above).

The key '''difficulties=EASY,NORMAL,HARD''' tells the computer to set the macro '''EASY''' if the first difficulty choice is chosen, '''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
It is recommended that you do not use other names than '''EASY''', '''NORMAL''', and '''HARD''' for your macros, because if you do then the standard macros, such as '''{GOLD}''' and '''{INCOME}''', won't work properly.

Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image, displayed inside the campaign list.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to:
"difficulties=EASY,NORMAL,HARD"
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
then an equals (''='') sign, then the text to display (eg ''Easy'').
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

BuildingScenariosIntermediate

2007-06-27T21:07:07Z

Mathijs: /* Added a navigation template at the top */

{{BuildingScenariosNav}}

= Building scenarios: Intermediate =
In this tutorial we will dig somewhat deeper into the secrets of WML and scenario building: events, explaining the use of some special attributes, setting up somewhat more advanced sides, ...

== Events ==
You can trigger certain actions that occur during a scenario using the events mechanism. Let us look at an example of a simple event. Suppose you wanted Konrad to say "it's getting cold" when he moves to the location (4,8):

[event]
name=moveto
[filter]
description=Konrad
x=4
y=8
[/filter]
[message]
description=Konrad
message= _ "It's getting cold"
[/message]
[/event]

First you have the name of the event.
Here, we have a 'moveto' event, meaning it is fired every time a unit moves somewhere.
For a list of the different possible event names, see [[EventWML]]

Of course, we don't want this to be fired every single time some unit moves somewhere! So, we use the '''[filter]''' tag to filter out what kind of moveto event we want.
How filters are used is described in [[FilterWML]].

== Special attributes ==

Note that generally, a set of actions is triggered only once.
You can make a set of actions be triggered every time the event occurs
by adding the attribute '''first_time_only=no''' in the event.

Also, whenever an event is triggered, the player cannot undo the move, even if it was a moveto event. We could make a scenario where moves cannot be undone by adding the event

[event]
name=moveto
first_time_only=no
[/event]

(which would not do anything, but would prevent the player from undoing moves)

The event:

[event]
name=enemies defeated
[endlevel]
result=victory
bonus=yes
[/endlevel]
[/event]

is an implied trigger and appears automatically at the end of each scenario.
To prevent this event, add the attribute '''victory_when_enemies_defeated=no''' inside the main tag (usually [scenario]).

The attribute '''disallow_recall=yes''' prevents the player from recalling units in this scenario.

The attributes '''fog=yes''' and '''shroud=yes''' can be put in a '''[side]''' tag to make that side have fog of war/shroud. (Fog of war prevents seeing all enemy movement, shroud prevents seeing all of the map.)

== Advanced Sides ==

Ok, so as you have seen in [[BuildingScenariosSimple]], you can setup what the human player and AI player start with, and some simple options for controlling how the AI works. From the '''[side]''' tag listed below you can see we are going to learn some more interesting things that can be controlled from there. I'm not going to explain all the keys, just the new ones.

[scenario]
.
.
.

[side]
type=Lich
description=Galga
side=2
canrecruit=1

#ifdef EASY
recruit=Skeleton,Revenant,Blood Bat,Ghost,Bone Shooter
recruitment_pattern=fighter,fighter,archer,scout
gold=300
#endif

#ifdef NORMAL
recruit=Skeleton,Revenant,Chocobone,Blood Bat,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=500
#endif

#ifdef HARD
recruit=Skeleton,Revenant,Chocobone,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=700
#endif

aggression=1.0
village_value=0.0
leader_value=50.0
enemy=1
[/side]
[/scenario]

As you can see from the above listing, the '''[side]''' tag can get a little complex.
The '''#ifdef''' is relatively simple to understand. If the user is playing EASY then everything between '''#ifdef EASY''' and '''#endif''' is set and the others are ignored. If the user is playing NORMAL then everything between '''#ifdef NORMAL''' and '''#endif''' is set and the others are ignored. Finally if the user is playing HARD then everything between '''#ifdef HARD''' and '''#endif''' is set and the others are ignored. This allows a scenario to be configured differently for each level of gameplay the user may choose. There are also two new keys listed, '''village_value''' and '''leader_value'''.

Lets get into some more interesting stuff. The map files hold the ground tiles. This is the very bottom layer of things. The units walking around during a game are on the very top layer. This is all well and good, but wouldn't it be nice to be able to place some unique items on the map? What if you wanted to place a building, or a potion, or anything somewhere in your scenario? Well you can! Using the '''[item]''' tag:

[scenario]
.
.
.

[item]
x=31
y=43
image=item-holywater.png
[/item]

.
.
.
[/scenario]

The '''[item]''' tag is actually very simple to use, as you can see from above. There are three keys, the first two are '''x''' and '''y'''. They are the location on the map. The third key is '''image'''. This it the image file to place in that location. This image must be located in the images directory. Ok, that was simple wasn't it?

Now you have enough information to make some interesting looking scenarios with tuned AI players. This is a big step. Next we are going to learn how to make your newly created scenario fit nicely into a campaign. This involves making the intro shown before the scenario is played a bit more descriptive. This is all done from within the '''[story]''' tag.

[scenario]
.
.
.

[story]
[part]
story= _ "... but one of the Orcs survived long enough to send the news to the queen..."
image=misc/story6.png
[/part]
.
.
.
[/story]
.
.
.
[/scenario]

The story tag contains the story told before the player starts the scenario. You can ommit this, then you will skip the introductionary screens. A story tag exists out of parts (inside [part] tags). Each part can contain several keys describing what content it has got. See [[IntroWML]] for more information.

== See Also ==
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

Template:BuildingScenariosNav

2007-06-27T21:05:33Z

Mathijs:

----
{| style="float:right"
|
__TOC__
|}
<div class="navtemplate">
==== Quick Navigation: ====
'''[[BuildingScenarios]]:'''
:*'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:*[[BuildingScenariosWML]]
:*[[BuildingScenariosComments]]
:*[[BuildingScenariosSamples]]
:*[[BuildingScenariosFAQ]]
</div>

BuildingScenarios

2007-06-27T20:58:44Z

Mathijs: /* Index */

StartingPoints

2007-06-27T20:52:07Z

Mathijs: /* Tweaking the Game (Create) */

__NOTOC__
Battle for Wesnoth is a turn-based fantasy strategy game.

Defeat all enemy leaders using a well-chosen cadre of troops,
taking care to manage your resources of gold and villages.
All units have their own strengths and weaknesses; to win,
deploy your forces to their best advantage while
denying your foes the chance to do the same. As units gain
experience, they acquire new abilities and become more
powerful. Play in your own language and test your skill
against a smart computer opponent, or join Wesnoth's large
community of on-line players.
Create your own custom units, scenarios or campaigns,
and share them with others.

Battle for Wesnoth is released under the
[http://www.gnu.org/licenses/licenses.html#GPL GPL].
Prebuilt packages are available for most operating systems,
including Windows, Mac OS X, and GNU/Linux, or you can build
your own from source code.

== Getting the Game ==
==== Downloading ====
* [[Download]] - get the most recent source-files and many binaries
** [[WesnothBinaries]] - precompiled for GNU/Linux, BeOS, PDAs, ...
** [[WesnothBinariesLinux]] - precompiled for many GNU/Linux distributions

==== Compiling ====
* [[CompilingWesnoth]] - on Unix, Mac, Windows, GNU/Linux, PDAs, ...
* [[DebuggingWesnoth]] - on GNU/Linux and Unix-like systems
* [[WesnothOnLinuxPDAs]] - on the Qtopia/OPIE and thepdaXrom/Zaurus C series

== Playing the Game ([[Play]]) ==

==== For New Players ====
* [[GettingStarted]] - read me first!
* [[WesnothManual]] - the rules
* [[MainlineScenarios]] - walkthroughs for the game-supplied campaigns

==== For Not-So-New Players ====
* [[AdvancedTactics]] - beating the AI and other people
* [[MultiplayerServers]] - where to play against other people online

==== Reference ====
* [[HotKeysSystem]] - keyboard shortcuts
* [[CommandMode]] - commands you can use in-game
* [[ServerAdministration]] - commands that authenticated users can use to administer the server
* [http://zapicm.freeshell.org Units] - Units advancement trees and stats
** [http://zapicm.freeshell.org/dev Development version]
** [http://zapicm.freeshell.org/stable Stable version]
** [http://zapicm.freeshell.org/trunk Trunk version]
* [[RaceDescriptions]] - Elves, Humans, Dwarves, Orcs, Drakes, Undead, Others
** [[Complete_Faction_List_%28unfinished%29]] - list all user made factions
* [[WesnothAcronyms|Wesnoth Acronyms (by category)]] - common wesnothian acronyms explained
* [[WesnothAcronyms(alphabetic)|Wesnoth Acronyms (alphabetic)]] - common wesnothian acronyms explained

== Tweaking the Game ([[Create]]) ==
==== Scenarios & Campaigns ====
* [[UserScenarios]] - user-written scenarios, campaigns and game modifications
* [[BuildingCampaigns]] - how to make your own single player campaigns
* [[MultiplayerCampaigns]] - how to make your own multiplayer campaigns
* [[BuildingScenarios]] - how to make your own scenarios
* [[BuildingUnits]] - how to make your own units
* [[UnitAnalysis]] - tool to analyze units
==== References ====
* [[ReferenceWML]] and [[AlphabeticalWML]] - all about Wesnoth Markup Language
* [[ReferencePythonAPI]] - upcoming Python interface for AI
==== Tools & Utilities ====
* [[ExternalUtilities]] - scripts to help create scenarios, campaigns, and graphics
* [[WesnothMapEditor]] - summary of controls
==== Art related ====
* [[Create_Art#Art_Tutorials|Art Tutorials]] - help in creating art
* [[GraphicLibrary]] - unit and terrain images posted on the forums
* [[Tiles_Status]] - terrain tiles: proposed and in progress.

== Improving the Game ==
* [[ReportingBugs]] - use Gna
* To submit a feature request, use http://bugs.wesnoth.org
* [[FrequentlyProposedIdeas]] - before you propose an idea, check here!
==== Developer information ====
* [[DeveloperResources]] - useful links
* [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
* [[WesnothSVN]] - accessing the source code
* [[HackingWesnoth]] - guide for programmers
* [[CodingStandards]] - for programmers
* [[UnitDescriptionRewriting]] - coordinating the revision
* [http://wesnoth.slack.it/missing.cgi Missing unit animations and sounds] - what's available and what's missing
* [[WritingYourOwnAI]] - write a C++ plugin
* [[ThemeSystem]] - customizing the screen layout for the game and the editor
* [[ReleasingWesnoth]] - steps to follow to release a new version
* [[WesnothPackagersGuide]] - guidelines for packaging Wesnoth for different platforms
* [[WesnothPreferences]]
* [[EasyCoding]] - Bugs and features that are easy to implement for new coders
* [[NotSoEasyCoding]] - Bugs and features which are doable but lacking someone working on them
* [[WesnothGL]] - Guide to programming the Wesnoth OpenGL branch

==== Game translations ====
* [[GettextForTranslators]] - how to translate Wesnoth under [[GetText]]
* [[WesnothTranslations]] - 11 complete, 2 almost complete, 7 more than halfway, 10 partial
* [[WesCamp]] - a project for translating user-made campaigns

== About the Game ==
* [[WesnothPhilosophy]] - Dave on Wesnoth
* [[WesnothHistory]] - the Ages of Wesnoth
* [[WesnothGeography]] - description of Wesnoth and surrounding lands
* [[WesnothFigures]] - notable figures of valorous and infamous deeds in Wesnoth
* [[WesnothReviews]] - third party reviews of Wesnoth
* [irc://irc.wesnoth.org/wesnoth #wesnoth] - our IRC channel
* [[Donate]] or [http://cafepress.com/wesnoth buy Wesnoth merchandise].
* [[Trailer]] - the Wesnoth trailer

== Other ==
* [[UsefulLinks]]
* [[WesnothLSM]] - presentation at LSM
* [http://wesnoth.slack.it/?WesnothPlayerMap Map of Wesnoth player locations] - add yourself to the map!
* [http://en.wikipedia.org/wiki/Battle_for_Wesnoth Wikipedia entry for Wesnoth]
* [[WikiHaiku]]

== About this Wiki ==
* [[Help:Editing|Editing]] - learn how to edit pages
* [[Sandbox]] - experiment with the wiki
* [[WikiMigration]] - we were looking for a replacement for our old wiki (and ended up using Mediawiki)

StartingPoints

2007-06-27T20:50:16Z

Mathijs: /* Tweaking the Game (Create) */

__NOTOC__
Battle for Wesnoth is a turn-based fantasy strategy game.

Defeat all enemy leaders using a well-chosen cadre of troops,
taking care to manage your resources of gold and villages.
All units have their own strengths and weaknesses; to win,
deploy your forces to their best advantage while
denying your foes the chance to do the same. As units gain
experience, they acquire new abilities and become more
powerful. Play in your own language and test your skill
against a smart computer opponent, or join Wesnoth's large
community of on-line players.
Create your own custom units, scenarios or campaigns,
and share them with others.

Battle for Wesnoth is released under the
[http://www.gnu.org/licenses/licenses.html#GPL GPL].
Prebuilt packages are available for most operating systems,
including Windows, Mac OS X, and GNU/Linux, or you can build
your own from source code.

== Getting the Game ==
==== Downloading ====
* [[Download]] - get the most recent source-files and many binaries
** [[WesnothBinaries]] - precompiled for GNU/Linux, BeOS, PDAs, ...
** [[WesnothBinariesLinux]] - precompiled for many GNU/Linux distributions

==== Compiling ====
* [[CompilingWesnoth]] - on Unix, Mac, Windows, GNU/Linux, PDAs, ...
* [[DebuggingWesnoth]] - on GNU/Linux and Unix-like systems
* [[WesnothOnLinuxPDAs]] - on the Qtopia/OPIE and thepdaXrom/Zaurus C series

== Playing the Game ([[Play]]) ==

==== For New Players ====
* [[GettingStarted]] - read me first!
* [[WesnothManual]] - the rules
* [[MainlineScenarios]] - walkthroughs for the game-supplied campaigns

==== For Not-So-New Players ====
* [[AdvancedTactics]] - beating the AI and other people
* [[MultiplayerServers]] - where to play against other people online

==== Reference ====
* [[HotKeysSystem]] - keyboard shortcuts
* [[CommandMode]] - commands you can use in-game
* [[ServerAdministration]] - commands that authenticated users can use to administer the server
* [http://zapicm.freeshell.org Units] - Units advancement trees and stats
** [http://zapicm.freeshell.org/dev Development version]
** [http://zapicm.freeshell.org/stable Stable version]
** [http://zapicm.freeshell.org/trunk Trunk version]
* [[RaceDescriptions]] - Elves, Humans, Dwarves, Orcs, Drakes, Undead, Others
** [[Complete_Faction_List_%28unfinished%29]] - list all user made factions
* [[WesnothAcronyms|Wesnoth Acronyms (by category)]] - common wesnothian acronyms explained
* [[WesnothAcronyms(alphabetic)|Wesnoth Acronyms (alphabetic)]] - common wesnothian acronyms explained

== Tweaking the Game ([[Create]]) ==
# Scenarios & Campaigns:
* [[UserScenarios]] - user-written scenarios, campaigns and game modifications
* [[BuildingCampaigns]] - how to make your own single player campaigns
* [[MultiplayerCampaigns]] - how to make your own multiplayer campaigns
* [[BuildingScenarios]] - how to make your own scenarios
* [[BuildingUnits]] - how to make your own units
* [[UnitAnalysis]] - tool to analyze units
# References:
* [[ReferenceWML]] and [[AlphabeticalWML]] - all about Wesnoth Markup Language
* [[ReferencePythonAPI]] - upcoming Python interface for AI
# Tools & Utilities:
* [[ExternalUtilities]] - scripts to help create scenarios, campaigns, and graphics
* [[WesnothMapEditor]] - summary of controls
# Art related:
* [[Create_Art#Art_Tutorials|Art Tutorials]] - help in creating art
* [[GraphicLibrary]] - unit and terrain images posted on the forums
* [[Tiles_Status]] - terrain tiles: proposed and in progress.

== Improving the Game ==
* [[ReportingBugs]] - use Gna
* To submit a feature request, use http://bugs.wesnoth.org
* [[FrequentlyProposedIdeas]] - before you propose an idea, check here!
==== Developer information ====
* [[DeveloperResources]] - useful links
* [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
* [[WesnothSVN]] - accessing the source code
* [[HackingWesnoth]] - guide for programmers
* [[CodingStandards]] - for programmers
* [[UnitDescriptionRewriting]] - coordinating the revision
* [http://wesnoth.slack.it/missing.cgi Missing unit animations and sounds] - what's available and what's missing
* [[WritingYourOwnAI]] - write a C++ plugin
* [[ThemeSystem]] - customizing the screen layout for the game and the editor
* [[ReleasingWesnoth]] - steps to follow to release a new version
* [[WesnothPackagersGuide]] - guidelines for packaging Wesnoth for different platforms
* [[WesnothPreferences]]
* [[EasyCoding]] - Bugs and features that are easy to implement for new coders
* [[NotSoEasyCoding]] - Bugs and features which are doable but lacking someone working on them
* [[WesnothGL]] - Guide to programming the Wesnoth OpenGL branch

==== Game translations ====
* [[GettextForTranslators]] - how to translate Wesnoth under [[GetText]]
* [[WesnothTranslations]] - 11 complete, 2 almost complete, 7 more than halfway, 10 partial
* [[WesCamp]] - a project for translating user-made campaigns

== About the Game ==
* [[WesnothPhilosophy]] - Dave on Wesnoth
* [[WesnothHistory]] - the Ages of Wesnoth
* [[WesnothGeography]] - description of Wesnoth and surrounding lands
* [[WesnothFigures]] - notable figures of valorous and infamous deeds in Wesnoth
* [[WesnothReviews]] - third party reviews of Wesnoth
* [irc://irc.wesnoth.org/wesnoth #wesnoth] - our IRC channel
* [[Donate]] or [http://cafepress.com/wesnoth buy Wesnoth merchandise].
* [[Trailer]] - the Wesnoth trailer

== Other ==
* [[UsefulLinks]]
* [[WesnothLSM]] - presentation at LSM
* [http://wesnoth.slack.it/?WesnothPlayerMap Map of Wesnoth player locations] - add yourself to the map!
* [http://en.wikipedia.org/wiki/Battle_for_Wesnoth Wikipedia entry for Wesnoth]
* [[WikiHaiku]]

== About this Wiki ==
* [[Help:Editing|Editing]] - learn how to edit pages
* [[Sandbox]] - experiment with the wiki
* [[WikiMigration]] - we were looking for a replacement for our old wiki (and ended up using Mediawiki)

BuildingScenariosAdvanced

2007-06-27T20:46:23Z

Mathijs: /* Quick Navigation: */

==== Quick Navigation: ====
'''[[BuildingScenarios]]'''
:'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Advanced =

'''TODO:'''
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information about GetText and making your scenario translatable
* information on guidelines concerning the general layout of a scenario file
* LOTS of links to pages any campaign editor needs frequently
* ...

Ayone who feels like writing something, go ahead

:Mathijs

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosIntermediate

2007-06-27T20:45:53Z

Mathijs: /* Quick Navigation: */

BuildingScenariosSimple

2007-06-27T20:45:41Z

Mathijs: /* Quick Navigation */

----
{| style="float:right"
|
__TOC__
|}
==== Quick Navigation: ====
'''[[BuildingScenarios]]'''
:'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Simple =

This will show you a very simple scenario file, explaining each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove usefull to read something about the syntax used in the Wesnoth Markup Language: [[SyntaxWML]]'''

== First part ==
[scenario]

id=test-1
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]
. continued below
. ||
. \/

Every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario:
* The ''id'' (short for ''identifier'') is the computer's name for your scenario, and is not displayed during the game. However, it will be used to display game statistics (they will be graphed on http://stats.wesnoth.org in numerical order, so it's also a good idea to give the id's a number). This name is also used as reference in other tags and files, eg inside a '''[campaign]''' tag using the ''first_scenario'' key(see [[BuildingCampaignsTheCampaignFile]]) or inside a '''[scenario]''' tag using the ''next_scenario'' key (see below).

* The value of the ''next_scenario'' key is the id (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put '''next_scenario=null''' inside the file. This will tell the game to display the End screen when this scenario is won.

* The value of the ''name'' key is shown on the introduction screen before each scenario is played. (This can contain a picture of a map, or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explenation on how to do that.) It's also the default name for saves on the level.

* The next key, ''map_data'', is a link to the map file. You can create map files using the Wesnoth Map Editor (see [[WesnothMapEditor]] and [[BuildingMaps]] for more information). Since we may not know exactly where this campaign will be located we'll write two possible locations of the map file. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used to indicate where the data begins and ends. If you don't do this, it will break the scenario.

* Finally, the last key in the top set of keys is ''turns''. This is the amount of turns a player is given to finish the scenario. (It can be changed during the game, but again, that is stuff for later.) When the player fails to finish the secnario in the given time, he has lost. (Said otherwise: the ''defeat'' event is trigered. See [[EventWML]] for more.)

The next section is a set of preprocessors (see [[PreprocessorRef]]). Preprocessors are essentially WML shortcuts. They allow you to define certain pieces of code and re-use it whenever it is needed. Wesnoth provides you with a whole serie of standard preprocessors to make life more easy, but you yourself can define them too (again stuff for later).
Lets get back to this example! The preprocessors used here, describe how a day in this scenario should progress. This listing above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the preprocessors except for '''{SECOND_WATCH}'''. This could be useful if you have Konrad
fighting the Undead and want the Undead to have the upper hand the whole time. Remember though, by setting this to a single tme of day and not the normal progress listed above, your scenario will effectively be taking place during one day or night, not many days as most scenarios are.

The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.

A tag you'll get to know very good when making scenarios shows up: '''[event]...[/event]'''.
Event tags are used to describe what should be done if an 'event' takes place. What this event is, is described by ''name''key. In this case we're describing the so-called 'prestart' event. This one takes place just ''before'' the game starts and just ''after'' all of the introductions screens were shown.
Here we have limited the contents of the tag to another important tag: '''[objectives]''' (plural) containing any number of '''[objective]''' (singular) tags.
For each '''[objective]''' (singular) tag, if ''condition'' is set to "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is set to "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives. Because we've placed this tag inside a prestart event, this will be shown at the very first turn of the scenario.
The ''side'' key indicates that these conditions are for side 1 (see below).
The ' _ ' (underscore) facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.
Also note that the '''[objective]''' tag only describes what the objectives are. You will still need to set the appropiate events before they will work. (But that's again stuff for later)

== Second part ==
So far so good! The last necessary part describes what the players (Human and
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.

. /\
. ||
. continued from above
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]

Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
* ''side'': the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]) It's a number from 1 to 9.
* ''controller'': possible values are 'human' or 'ai' (artificial intelligence, meaning your computer). If you don't specify this key, 'ai' is used as the default.
* ''team_name'' describes which team the side is on. It defaults to the same number as ''side'', so setting it to ''2'' allies this side with side 2, if you haven't changed the team_name of side 2.
* ''user_team_name'' is the name displayed when you view the sie stats (by pressing alt+s during gameplay). The underscore facilitates translation using GetText (see [[GetText]]).

The next set of keys describe the leader of this side:
* ''canrecruit'': This key can be '1' or '0', meaning "yes" or "no" respectively. If you no, then the leader won't be able to recruit. (Not much of a leader then, is he?) Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
* ''type'' describes what type of unit the leader will be. The possible values are listed here: [[UnitTables]].
* ''description'' is the name and description of the leader.
In a campaign, all of these 'leader-describing' keys are ignored for the human player (except ''canrecruit''), since the leader from the previous scenario is used instead. However, the ''type'' key is still neccesary to prevent the scenario from crashing.

* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].

Then two more preprocessors are used:
* '''{GOLD easy normal hard}''' takes 3 positive numbers. These indicate the amount of money the player will start with on the EASY, NORMAL and HARD difficulty level.
In a campaign file, inside a human controlled side (''controller=human''), this is the minimum amount. The actual amount the player gets ca, be larger if the player retained more from previous scenarios.
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
The defaults for each of these values are 100 gold and 2 base income.

== Making it all work ==
Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
This should NOT be stored inside the main directory '''data/campaigns''' but inside '''userdata/data/campaigns'''. This prevents breaking the mainline campaigns or even worse, the entire game. (see [[BuildingCampaignsDirectoryStructure]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending .cfg (for example: testcampaign.cfg).
This is a short example on how to do this:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are described in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign. Scenarios following after this one are referenced inside the first scenario using ''next_scenario'' (see above).

The key '''difficulties=EASY,NORMAL,HARD''' tells the computer to set the macro '''EASY''' if the first difficulty choice is chosen, '''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
It is recommended that you do not use other names than '''EASY''', '''NORMAL''', and '''HARD''' for your macros, because if you do then the standard macros, such as '''{GOLD}''' and '''{INCOME}''', won't work properly.

Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image, displayed inside the campaign list.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to:
"difficulties=EASY,NORMAL,HARD"
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
then an equals (''='') sign, then the text to display (eg ''Easy'').
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

BuildingScenariosIntermediate

2007-06-27T20:45:23Z

Mathijs: /* Quick Navigation: */

----
{| style="float:right"
|
__TOC__
|}
==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Intermediate =
In this tutorial we will dig somewhat deeper into the secrets of WML and scenario building: events, explaining the use of some special attributes, setting up somewhat more advanced sides, ...

== Events ==
You can trigger certain actions that occur during a scenario using the events mechanism. Let us look at an example of a simple event. Suppose you wanted Konrad to say "it's getting cold" when he moves to the location (4,8):

[event]
name=moveto
[filter]
description=Konrad
x=4
y=8
[/filter]
[message]
description=Konrad
message= _ "It's getting cold"
[/message]
[/event]

First you have the name of the event.
Here, we have a 'moveto' event, meaning it is fired every time a unit moves somewhere.
For a list of the different possible event names, see [[EventWML]]

Of course, we don't want this to be fired every single time some unit moves somewhere! So, we use the '''[filter]''' tag to filter out what kind of moveto event we want.
How filters are used is described in [[FilterWML]].

== Special attributes ==

Note that generally, a set of actions is triggered only once.
You can make a set of actions be triggered every time the event occurs
by adding the attribute '''first_time_only=no''' in the event.

Also, whenever an event is triggered, the player cannot undo the move, even if it was a moveto event. We could make a scenario where moves cannot be undone by adding the event

[event]
name=moveto
first_time_only=no
[/event]

(which would not do anything, but would prevent the player from undoing moves)

The event:

[event]
name=enemies defeated
[endlevel]
result=victory
bonus=yes
[/endlevel]
[/event]

is an implied trigger and appears automatically at the end of each scenario.
To prevent this event, add the attribute '''victory_when_enemies_defeated=no''' inside the main tag (usually [scenario]).

The attribute '''disallow_recall=yes''' prevents the player from recalling units in this scenario.

The attributes '''fog=yes''' and '''shroud=yes''' can be put in a '''[side]''' tag to make that side have fog of war/shroud. (Fog of war prevents seeing all enemy movement, shroud prevents seeing all of the map.)

== Advanced Sides ==

Ok, so as you have seen in [[BuildingScenariosSimple]], you can setup what the human player and AI player start with, and some simple options for controlling how the AI works. From the '''[side]''' tag listed below you can see we are going to learn some more interesting things that can be controlled from there. I'm not going to explain all the keys, just the new ones.

[scenario]
.
.
.

[side]
type=Lich
description=Galga
side=2
canrecruit=1

#ifdef EASY
recruit=Skeleton,Revenant,Blood Bat,Ghost,Bone Shooter
recruitment_pattern=fighter,fighter,archer,scout
gold=300
#endif

#ifdef NORMAL
recruit=Skeleton,Revenant,Chocobone,Blood Bat,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=500
#endif

#ifdef HARD
recruit=Skeleton,Revenant,Chocobone,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=700
#endif

aggression=1.0
village_value=0.0
leader_value=50.0
enemy=1
[/side]
[/scenario]

As you can see from the above listing, the '''[side]''' tag can get a little complex.
The '''#ifdef''' is relatively simple to understand. If the user is playing EASY then everything between '''#ifdef EASY''' and '''#endif''' is set and the others are ignored. If the user is playing NORMAL then everything between '''#ifdef NORMAL''' and '''#endif''' is set and the others are ignored. Finally if the user is playing HARD then everything between '''#ifdef HARD''' and '''#endif''' is set and the others are ignored. This allows a scenario to be configured differently for each level of gameplay the user may choose. There are also two new keys listed, '''village_value''' and '''leader_value'''.

Lets get into some more interesting stuff. The map files hold the ground tiles. This is the very bottom layer of things. The units walking around during a game are on the very top layer. This is all well and good, but wouldn't it be nice to be able to place some unique items on the map? What if you wanted to place a building, or a potion, or anything somewhere in your scenario? Well you can! Using the '''[item]''' tag:

[scenario]
.
.
.

[item]
x=31
y=43
image=item-holywater.png
[/item]

.
.
.
[/scenario]

The '''[item]''' tag is actually very simple to use, as you can see from above. There are three keys, the first two are '''x''' and '''y'''. They are the location on the map. The third key is '''image'''. This it the image file to place in that location. This image must be located in the images directory. Ok, that was simple wasn't it?

Now you have enough information to make some interesting looking scenarios with tuned AI players. This is a big step. Next we are going to learn how to make your newly created scenario fit nicely into a campaign. This involves making the intro shown before the scenario is played a bit more descriptive. This is all done from within the '''[story]''' tag.

[scenario]
.
.
.

[story]
[part]
story= _ "... but one of the Orcs survived long enough to send the news to the queen..."
image=misc/story6.png
[/part]
.
.
.
[/story]
.
.
.
[/scenario]

The story tag contains the story told before the player starts the scenario. You can ommit this, then you will skip the introductionary screens. A story tag exists out of parts (inside [part] tags). Each part can contain several keys describing what content it has got. See [[IntroWML]] for more information.

== See Also ==
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-06-27T20:45:13Z

Mathijs:

==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]] - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]'''
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Advanced =

'''TODO:'''
This contained a repetition of what was already inside [[BuildingScenariosIntermediate]]
This should contain:
* (more) information about making & using preprocessors ([[PreprocessorRef]])
* information about GetText and making your scenario translatable
* information on guidelines concerning the general layout of a scenario file
* LOTS of links to pages any campaign editor needs frequently
* ...

Ayone who feels like writing something, go ahead

:Mathijs

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-06-27T20:44:30Z

Mathijs:

BuildingScenariosAdvanced

2007-06-27T20:44:01Z

Mathijs:

BuildingScenariosAdvanced

2007-06-27T20:38:42Z

Mathijs: /* Building scenarios: Advanced */

==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Advanced =

Ok, so as you have seen in [[BuildingScenariosSimple]], you can setup what the human player and AI player start with. From the '''[side]''' tag listed below you can see we are going to learn some more interesting things about AI that can be controlled from there. We'll have a look at the new keys one by one.

[scenario]
.
.
.
[side]
side=2
enemy=1

canrecruit=1

type=Lich
description=Galga

#ifdef EASY
recruit=Skeleton,Revenant,Blood Bat,Ghost,Bone Shooter
recruitment_pattern=fighter,fighter,archer,scout
gold=300
#endif

#ifdef NORMAL
recruit=Skeleton,Revenant,Chocobone,Blood Bat,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=500
#endif

#ifdef HARD
recruit=Skeleton,Revenant,Chocobone,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=700
#endif

aggression=1.0
village_value=0.0
leader_value=50.0
[/side]
.
.
.
[/scenario]

As you can see from the above listing, the '''[side]''' tag can get a little complex. The ''#ifdef'' is relatively simple
to explain. If the user is playing EASY then everything between '''#ifdef EASY''' and '''#endif''' is set and the others
are ignored. If the user is playing NORMAL then everything between '''#ifdef NORMAL''' and '''#endif''' is set and the
others are ignored. Finally if the user is playing HARD then everything between '''#ifdef HARD''' and '''#endif''' is set
and the others are ignored. This allows a scenario to be configured differently for each level of gameplay the user
may choose. There are also four new keys listed, '''recruitment_pattern''', '''aggression''', '''village_value''' and '''leader_value'''.

''''THIS IS OBSOLETE:'''' '''Editor's Note: For 0.8.3 and later, scenarios no longer need IDs'''

If a scenario is meant to be translated, it must have ID's. ID's are used to represent text in the scenario. A translation maps the ID of each text in the scenario to a translation text.

Example:

[message]
message= _ "Where are we? Which way now? I am tired of this darkness!"
description=Konrad
id=hasty_1
[/message]

This is the first message in the scenario "Hasty Alliance". To translate this message into French, we put the key

hasty_1="Où sommes-nous ? Quel chemin devons-nous emprunter maintenant ? Je suis fatigué de cette obscurité !"

in the French translation file and when Wesnoth is played in French this message will be displayed rather than the
original one. The key
''' id ''' should be added to any tag with text that is meant to be translated (remember, the [scenario] tag already has an
id, do not add
another one).

Now you have enough information to make some interesting looking scenarios with tuned AI players.
This is a big step.
Next we are going to learn how to make your newly created scenario fit nicely into a campaign.
This involves making a descriptive intro shown before the scenario is played.
See [[IntroWML]] for a description of the intro screen.

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-06-27T20:35:27Z

Mathijs: /* See Also */

==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Advanced =

Ok, so as you have seen in [[BuildingScenariosSimple]], you can setup what the human player and AI player start with. From the '''[side]''' tag listed below you can see we are going to learn some more interesting things about AI that can be controlled from there. We'll have a look at the new keys one by one.

[scenario]
.
.
.
[side]
side=2
enemy=1

canrecruit=1

type=Lich
description=Galga

#ifdef EASY
recruit=Skeleton,Revenant,Blood Bat,Ghost,Bone Shooter
recruitment_pattern=fighter,fighter,archer,scout
gold=300
#endif

#ifdef NORMAL
recruit=Skeleton,Revenant,Chocobone,Blood Bat,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=500
#endif

#ifdef HARD
recruit=Skeleton,Revenant,Chocobone,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=700
#endif

aggression=1.0
village_value=0.0
leader_value=50.0
[/side]
.
.
.
[/scenario]

As you can see from the above listing, the '''[side]''' tag can get a little complex. The ''#ifdef'' is relatively simple
to explain. If the user is playing EASY then everything between '''#ifdef EASY''' and '''#endif''' is set and the others
are ignored. If the user is playing NORMAL then everything between '''#ifdef NORMAL''' and '''#endif''' is set and the
others are ignored. Finally if the user is playing HARD then everything between '''#ifdef HARD''' and '''#endif''' is set
and the others are ignored. This allows a scenario to be configured differently for each level of gameplay the user
may choose. There are also four new keys listed, '''recruitment_pattern''', '''aggression''', '''village_value''' and '''leader_value'''.

If a scenario is meant to be translated, it must have ids
(Editor's Note: For 0.8.3 and later, scenarios no longer need IDs.).
IDs are used to represent text in the scenario.
A translation maps the ID of each text in the scenario to a translation text.

Example:

[message]
message= _ "Where are we? Which way now? I am tired of this darkness!"
description=Konrad
id=hasty_1
[/message]

This is the first message in the scenario "Hasty Alliance". To translate this message into French, we put the key

hasty_1="Où sommes-nous ? Quel chemin devons-nous emprunter maintenant ? Je suis fatigué de cette obscurité !"

in the French translation file and when Wesnoth is played in French this message will be displayed rather than the
original one. The key
''' id ''' should be added to any tag with text that is meant to be translated (remember, the [scenario] tag already has an
id, do not add
another one).

Now you have enough information to make some interesting looking scenarios with tuned AI players.
This is a big step.
Next we are going to learn how to make your newly created scenario fit nicely into a campaign.
This involves making a descriptive intro shown before the scenario is played.
See [[IntroWML]] for a description of the intro screen.

See [[ReferenceWML]] for a more complete description of what WML can do.

== See Also ==
* [[ScenarioWML]], [[SyntaxWML]] & [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-06-27T20:34:44Z

Mathijs: /* See Also */

==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Advanced =

Ok, so as you have seen in [[BuildingScenariosSimple]], you can setup what the human player and AI player start with. From the '''[side]''' tag listed below you can see we are going to learn some more interesting things about AI that can be controlled from there. We'll have a look at the new keys one by one.

[scenario]
.
.
.
[side]
side=2
enemy=1

canrecruit=1

type=Lich
description=Galga

#ifdef EASY
recruit=Skeleton,Revenant,Blood Bat,Ghost,Bone Shooter
recruitment_pattern=fighter,fighter,archer,scout
gold=300
#endif

#ifdef NORMAL
recruit=Skeleton,Revenant,Chocobone,Blood Bat,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=500
#endif

#ifdef HARD
recruit=Skeleton,Revenant,Chocobone,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=700
#endif

aggression=1.0
village_value=0.0
leader_value=50.0
[/side]
.
.
.
[/scenario]

As you can see from the above listing, the '''[side]''' tag can get a little complex. The ''#ifdef'' is relatively simple
to explain. If the user is playing EASY then everything between '''#ifdef EASY''' and '''#endif''' is set and the others
are ignored. If the user is playing NORMAL then everything between '''#ifdef NORMAL''' and '''#endif''' is set and the
others are ignored. Finally if the user is playing HARD then everything between '''#ifdef HARD''' and '''#endif''' is set
and the others are ignored. This allows a scenario to be configured differently for each level of gameplay the user
may choose. There are also four new keys listed, '''recruitment_pattern''', '''aggression''', '''village_value''' and '''leader_value'''.

If a scenario is meant to be translated, it must have ids
(Editor's Note: For 0.8.3 and later, scenarios no longer need IDs.).
IDs are used to represent text in the scenario.
A translation maps the ID of each text in the scenario to a translation text.

Example:

[message]
message= _ "Where are we? Which way now? I am tired of this darkness!"
description=Konrad
id=hasty_1
[/message]

This is the first message in the scenario "Hasty Alliance". To translate this message into French, we put the key

hasty_1="Où sommes-nous ? Quel chemin devons-nous emprunter maintenant ? Je suis fatigué de cette obscurité !"

in the French translation file and when Wesnoth is played in French this message will be displayed rather than the
original one. The key
''' id ''' should be added to any tag with text that is meant to be translated (remember, the [scenario] tag already has an
id, do not add
another one).

Now you have enough information to make some interesting looking scenarios with tuned AI players.
This is a big step.
Next we are going to learn how to make your newly created scenario fit nicely into a campaign.
This involves making a descriptive intro shown before the scenario is played.
See [[IntroWML]] for a description of the intro screen.

See [[ReferenceWML]] for a more complete description of what WML can do.

== See Also ==
* [[ReferenceWML]]
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-06-27T20:34:08Z

Mathijs: /* Building scenarios: Advanced */

==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Advanced =

Ok, so as you have seen in [[BuildingScenariosSimple]], you can setup what the human player and AI player start with. From the '''[side]''' tag listed below you can see we are going to learn some more interesting things about AI that can be controlled from there. We'll have a look at the new keys one by one.

[scenario]
.
.
.
[side]
side=2
enemy=1

canrecruit=1

type=Lich
description=Galga

#ifdef EASY
recruit=Skeleton,Revenant,Blood Bat,Ghost,Bone Shooter
recruitment_pattern=fighter,fighter,archer,scout
gold=300
#endif

#ifdef NORMAL
recruit=Skeleton,Revenant,Chocobone,Blood Bat,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=500
#endif

#ifdef HARD
recruit=Skeleton,Revenant,Chocobone,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=700
#endif

aggression=1.0
village_value=0.0
leader_value=50.0
[/side]
.
.
.
[/scenario]

As you can see from the above listing, the '''[side]''' tag can get a little complex. The ''#ifdef'' is relatively simple
to explain. If the user is playing EASY then everything between '''#ifdef EASY''' and '''#endif''' is set and the others
are ignored. If the user is playing NORMAL then everything between '''#ifdef NORMAL''' and '''#endif''' is set and the
others are ignored. Finally if the user is playing HARD then everything between '''#ifdef HARD''' and '''#endif''' is set
and the others are ignored. This allows a scenario to be configured differently for each level of gameplay the user
may choose. There are also four new keys listed, '''recruitment_pattern''', '''aggression''', '''village_value''' and '''leader_value'''.

If a scenario is meant to be translated, it must have ids
(Editor's Note: For 0.8.3 and later, scenarios no longer need IDs.).
IDs are used to represent text in the scenario.
A translation maps the ID of each text in the scenario to a translation text.

Example:

[message]
message= _ "Where are we? Which way now? I am tired of this darkness!"
description=Konrad
id=hasty_1
[/message]

This is the first message in the scenario "Hasty Alliance". To translate this message into French, we put the key

hasty_1="Où sommes-nous ? Quel chemin devons-nous emprunter maintenant ? Je suis fatigué de cette obscurité !"

in the French translation file and when Wesnoth is played in French this message will be displayed rather than the
original one. The key
''' id ''' should be added to any tag with text that is meant to be translated (remember, the [scenario] tag already has an
id, do not add
another one).

Now you have enough information to make some interesting looking scenarios with tuned AI players.
This is a big step.
Next we are going to learn how to make your newly created scenario fit nicely into a campaign.
This involves making a descriptive intro shown before the scenario is played.
See [[IntroWML]] for a description of the intro screen.

See [[ReferenceWML]] for a more complete description of what WML can do.

== See Also ==
* [[BuildingScenarios]]

BuildingScenariosAdvanced

2007-06-27T20:31:44Z

Mathijs:

==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Advanced =

Ok, so as you have seen in [[BuildingScenariosSimple]], you can setup what the human player and AI player start with. From
the '''[side]''' tag listed below you can see we are going to learn some more interesting things about AI that can be
controlled from there. I'm not going to explain all the keys, just the new ones.

.
.
.

[side]
side=2
enemy=1

canrecruit=1

type=Lich
description=Galga

#ifdef EASY
recruit=Skeleton,Revenant,Blood Bat,Ghost,Bone Shooter
recruitment_pattern=fighter,fighter,archer,scout
gold=300
#endif

#ifdef NORMAL
recruit=Skeleton,Revenant,Chocobone,Blood Bat,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=500
#endif

#ifdef HARD
recruit=Skeleton,Revenant,Chocobone,Wraith,Bone Shooter,Dark Adept
recruitment_pattern=fighter,fighter,archer,scout
gold=700
#endif

aggression=1.0
village_value=0.0
leader_value=50.0
[/side]

As you can see from the above listing, the '''[side]''' tag can get a little complex. The ''#ifdef'' is relatively simple
to explain. If the user is playing EASY then everything between '''#ifdef EASY''' and '''#endif''' is set and the others
are ignored. If the user is playing NORMAL then everything between '''#ifdef NORMAL''' and '''#endif''' is set and the
others are ignored. Finally if the user is playing HARD then everything between '''#ifdef HARD''' and '''#endif''' is set
and the others are ignored. This allows a scenario to be configured differently for each level of gameplay the user
may choose. There are also four new keys listed, '''recruitment_pattern''', '''aggression''', '''village_value''' and '''leader_value'''.

If a scenario is meant to be translated, it must have ids
(Editor's Note: For 0.8.3 and later, scenarios no longer need IDs.).
IDs are used to represent text in the scenario.
A translation maps the ID of each text in the scenario to a translation text.

Example:

[message]
message= _ "Where are we? Which way now? I am tired of this darkness!"
description=Konrad
id=hasty_1
[/message]

This is the first message in the scenario "Hasty Alliance". To translate this message into French, we put the key

hasty_1="Où sommes-nous ? Quel chemin devons-nous emprunter maintenant ? Je suis fatigué de cette obscurité !"

in the French translation file and when Wesnoth is played in French this message will be displayed rather than the
original one. The key
''' id ''' should be added to any tag with text that is meant to be translated (remember, the [scenario] tag already has an
id, do not add
another one).

Now you have enough information to make some interesting looking scenarios with tuned AI players.
This is a big step.
Next we are going to learn how to make your newly created scenario fit nicely into a campaign.
This involves making a descriptive intro shown before the scenario is played.
See [[IntroWML]] for a description of the intro screen.

See [[ReferenceWML]] for a more complete description of what WML can do.

== See Also ==
* [[BuildingScenarios]]

BuildingScenariosSimple

2007-06-27T20:30:40Z

Mathijs: /* Quick Navigation */

----
{| style="float:right"
|
__TOC__
|}
==== Quick Navigation ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosComments]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Simple =

This will show you a very simple scenario file, explaining each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove usefull to read something about the syntax used in the Wesnoth Markup Language: [[SyntaxWML]]'''

== First part ==
[scenario]

id=test-1
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]
. continued below
. ||
. \/

Every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario:
* The ''id'' (short for ''identifier'') is the computer's name for your scenario, and is not displayed during the game. However, it will be used to display game statistics (they will be graphed on http://stats.wesnoth.org in numerical order, so it's also a good idea to give the id's a number). This name is also used as reference in other tags and files, eg inside a '''[campaign]''' tag using the ''first_scenario'' key(see [[BuildingCampaignsTheCampaignFile]]) or inside a '''[scenario]''' tag using the ''next_scenario'' key (see below).

* The value of the ''next_scenario'' key is the id (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put '''next_scenario=null''' inside the file. This will tell the game to display the End screen when this scenario is won.

* The value of the ''name'' key is shown on the introduction screen before each scenario is played. (This can contain a picture of a map, or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explenation on how to do that.) It's also the default name for saves on the level.

* The next key, ''map_data'', is a link to the map file. You can create map files using the Wesnoth Map Editor (see [[WesnothMapEditor]] and [[BuildingMaps]] for more information). Since we may not know exactly where this campaign will be located we'll write two possible locations of the map file. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used to indicate where the data begins and ends. If you don't do this, it will break the scenario.

* Finally, the last key in the top set of keys is ''turns''. This is the amount of turns a player is given to finish the scenario. (It can be changed during the game, but again, that is stuff for later.) When the player fails to finish the secnario in the given time, he has lost. (Said otherwise: the ''defeat'' event is trigered. See [[EventWML]] for more.)

The next section is a set of preprocessors (see [[PreprocessorRef]]). Preprocessors are essentially WML shortcuts. They allow you to define certain pieces of code and re-use it whenever it is needed. Wesnoth provides you with a whole serie of standard preprocessors to make life more easy, but you yourself can define them too (again stuff for later).
Lets get back to this example! The preprocessors used here, describe how a day in this scenario should progress. This listing above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the preprocessors except for '''{SECOND_WATCH}'''. This could be useful if you have Konrad
fighting the Undead and want the Undead to have the upper hand the whole time. Remember though, by setting this to a single tme of day and not the normal progress listed above, your scenario will effectively be taking place during one day or night, not many days as most scenarios are.

The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.

A tag you'll get to know very good when making scenarios shows up: '''[event]...[/event]'''.
Event tags are used to describe what should be done if an 'event' takes place. What this event is, is described by ''name''key. In this case we're describing the so-called 'prestart' event. This one takes place just ''before'' the game starts and just ''after'' all of the introductions screens were shown.
Here we have limited the contents of the tag to another important tag: '''[objectives]''' (plural) containing any number of '''[objective]''' (singular) tags.
For each '''[objective]''' (singular) tag, if ''condition'' is set to "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is set to "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives. Because we've placed this tag inside a prestart event, this will be shown at the very first turn of the scenario.
The ''side'' key indicates that these conditions are for side 1 (see below).
The ' _ ' (underscore) facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.
Also note that the '''[objective]''' tag only describes what the objectives are. You will still need to set the appropiate events before they will work. (But that's again stuff for later)

== Second part ==
So far so good! The last necessary part describes what the players (Human and
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.

. /\
. ||
. continued from above
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]

Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
* ''side'': the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]) It's a number from 1 to 9.
* ''controller'': possible values are 'human' or 'ai' (artificial intelligence, meaning your computer). If you don't specify this key, 'ai' is used as the default.
* ''team_name'' describes which team the side is on. It defaults to the same number as ''side'', so setting it to ''2'' allies this side with side 2, if you haven't changed the team_name of side 2.
* ''user_team_name'' is the name displayed when you view the sie stats (by pressing alt+s during gameplay). The underscore facilitates translation using GetText (see [[GetText]]).

The next set of keys describe the leader of this side:
* ''canrecruit'': This key can be '1' or '0', meaning "yes" or "no" respectively. If you no, then the leader won't be able to recruit. (Not much of a leader then, is he?) Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
* ''type'' describes what type of unit the leader will be. The possible values are listed here: [[UnitTables]].
* ''description'' is the name and description of the leader.
In a campaign, all of these 'leader-describing' keys are ignored for the human player (except ''canrecruit''), since the leader from the previous scenario is used instead. However, the ''type'' key is still neccesary to prevent the scenario from crashing.

* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].

Then two more preprocessors are used:
* '''{GOLD easy normal hard}''' takes 3 positive numbers. These indicate the amount of money the player will start with on the EASY, NORMAL and HARD difficulty level.
In a campaign file, inside a human controlled side (''controller=human''), this is the minimum amount. The actual amount the player gets ca, be larger if the player retained more from previous scenarios.
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
The defaults for each of these values are 100 gold and 2 base income.

== Making it all work ==
Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
This should NOT be stored inside the main directory '''data/campaigns''' but inside '''userdata/data/campaigns'''. This prevents breaking the mainline campaigns or even worse, the entire game. (see [[BuildingCampaignsDirectoryStructure]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending .cfg (for example: testcampaign.cfg).
This is a short example on how to do this:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are described in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign. Scenarios following after this one are referenced inside the first scenario using ''next_scenario'' (see above).

The key '''difficulties=EASY,NORMAL,HARD''' tells the computer to set the macro '''EASY''' if the first difficulty choice is chosen, '''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
It is recommended that you do not use other names than '''EASY''', '''NORMAL''', and '''HARD''' for your macros, because if you do then the standard macros, such as '''{GOLD}''' and '''{INCOME}''', won't work properly.

Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image, displayed inside the campaign list.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to:
"difficulties=EASY,NORMAL,HARD"
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
then an equals (''='') sign, then the text to display (eg ''Easy'').
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

BuildingScenariosIntermediate

2007-06-27T20:30:03Z

Mathijs: /* Building scenarios: Intermediate */

BuildingScenariosSimple

2007-06-27T20:02:26Z

Mathijs: /* Quick Navigation: */

----
{| style="float:right"
|
__TOC__
|}
==== Quick Navigation ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Simple =

This will show you a very simple scenario file, explaining each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove usefull to read something about the syntax used in the Wesnoth Markup Language: [[SyntaxWML]]'''

== First part ==
[scenario]

id=test-1
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]
. continued below
. ||
. \/

Every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario:
* The ''id'' (short for ''identifier'') is the computer's name for your scenario, and is not displayed during the game. However, it will be used to display game statistics (they will be graphed on http://stats.wesnoth.org in numerical order, so it's also a good idea to give the id's a number). This name is also used as reference in other tags and files, eg inside a '''[campaign]''' tag using the ''first_scenario'' key(see [[BuildingCampaignsTheCampaignFile]]) or inside a '''[scenario]''' tag using the ''next_scenario'' key (see below).

* The value of the ''next_scenario'' key is the id (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put '''next_scenario=null''' inside the file. This will tell the game to display the End screen when this scenario is won.

* The value of the ''name'' key is shown on the introduction screen before each scenario is played. (This can contain a picture of a map, or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explenation on how to do that.) It's also the default name for saves on the level.

* The next key, ''map_data'', is a link to the map file. You can create map files using the Wesnoth Map Editor (see [[WesnothMapEditor]] and [[BuildingMaps]] for more information). Since we may not know exactly where this campaign will be located we'll write two possible locations of the map file. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used to indicate where the data begins and ends. If you don't do this, it will break the scenario.

* Finally, the last key in the top set of keys is ''turns''. This is the amount of turns a player is given to finish the scenario. (It can be changed during the game, but again, that is stuff for later.) When the player fails to finish the secnario in the given time, he has lost. (Said otherwise: the ''defeat'' event is trigered. See [[EventWML]] for more.)

The next section is a set of preprocessors (see [[PreprocessorRef]]). Preprocessors are essentially WML shortcuts. They allow you to define certain pieces of code and re-use it whenever it is needed. Wesnoth provides you with a whole serie of standard preprocessors to make life more easy, but you yourself can define them too (again stuff for later).
Lets get back to this example! The preprocessors used here, describe how a day in this scenario should progress. This listing above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the preprocessors except for '''{SECOND_WATCH}'''. This could be useful if you have Konrad
fighting the Undead and want the Undead to have the upper hand the whole time. Remember though, by setting this to a single tme of day and not the normal progress listed above, your scenario will effectively be taking place during one day or night, not many days as most scenarios are.

The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.

A tag you'll get to know very good when making scenarios shows up: '''[event]...[/event]'''.
Event tags are used to describe what should be done if an 'event' takes place. What this event is, is described by ''name''key. In this case we're describing the so-called 'prestart' event. This one takes place just ''before'' the game starts and just ''after'' all of the introductions screens were shown.
Here we have limited the contents of the tag to another important tag: '''[objectives]''' (plural) containing any number of '''[objective]''' (singular) tags.
For each '''[objective]''' (singular) tag, if ''condition'' is set to "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is set to "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives. Because we've placed this tag inside a prestart event, this will be shown at the very first turn of the scenario.
The ''side'' key indicates that these conditions are for side 1 (see below).
The ' _ ' (underscore) facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.
Also note that the '''[objective]''' tag only describes what the objectives are. You will still need to set the appropiate events before they will work. (But that's again stuff for later)

== Second part ==
So far so good! The last necessary part describes what the players (Human and
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.

. /\
. ||
. continued from above
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]

Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
* ''side'': the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]) It's a number from 1 to 9.
* ''controller'': possible values are 'human' or 'ai' (artificial intelligence, meaning your computer). If you don't specify this key, 'ai' is used as the default.
* ''team_name'' describes which team the side is on. It defaults to the same number as ''side'', so setting it to ''2'' allies this side with side 2, if you haven't changed the team_name of side 2.
* ''user_team_name'' is the name displayed when you view the sie stats (by pressing alt+s during gameplay). The underscore facilitates translation using GetText (see [[GetText]]).

The next set of keys describe the leader of this side:
* ''canrecruit'': This key can be '1' or '0', meaning "yes" or "no" respectively. If you no, then the leader won't be able to recruit. (Not much of a leader then, is he?) Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
* ''type'' describes what type of unit the leader will be. The possible values are listed here: [[UnitTables]].
* ''description'' is the name and description of the leader.
In a campaign, all of these 'leader-describing' keys are ignored for the human player (except ''canrecruit''), since the leader from the previous scenario is used instead. However, the ''type'' key is still neccesary to prevent the scenario from crashing.

* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].

Then two more preprocessors are used:
* '''{GOLD easy normal hard}''' takes 3 positive numbers. These indicate the amount of money the player will start with on the EASY, NORMAL and HARD difficulty level.
In a campaign file, inside a human controlled side (''controller=human''), this is the minimum amount. The actual amount the player gets ca, be larger if the player retained more from previous scenarios.
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
The defaults for each of these values are 100 gold and 2 base income.

== Making it all work ==
Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
This should NOT be stored inside the main directory '''data/campaigns''' but inside '''userdata/data/campaigns'''. This prevents breaking the mainline campaigns or even worse, the entire game. (see [[BuildingCampaignsDirectoryStructure]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending .cfg (for example: testcampaign.cfg).
This is a short example on how to do this:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are described in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign. Scenarios following after this one are referenced inside the first scenario using ''next_scenario'' (see above).

The key '''difficulties=EASY,NORMAL,HARD''' tells the computer to set the macro '''EASY''' if the first difficulty choice is chosen, '''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
It is recommended that you do not use other names than '''EASY''', '''NORMAL''', and '''HARD''' for your macros, because if you do then the standard macros, such as '''{GOLD}''' and '''{INCOME}''', won't work properly.

Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image, displayed inside the campaign list.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to:
"difficulties=EASY,NORMAL,HARD"
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
then an equals (''='') sign, then the text to display (eg ''Easy'').
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

BuildingScenariosSimple

2007-06-27T19:59:38Z

Mathijs:

----
{| style="float:right"
|
__TOC__
|}
==== Quick Navigation: ====
[[BuildingScenarios]]
:'''[[BuildingScenariosSimple]]''' - [[BuildingScenariosIntermediate]] - [[BuildingScenariosAdvanced]]
:[[BuildingScenariosWML]]
:[[BuildingScenariosSamples]]
:[[BuildingScenariosFAQ]]
<br>
----

= Building scenarios: Simple =

This will show you a very simple scenario file, explaining each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove usefull to read something about the syntax used in the Wesnoth Markup Language: [[SyntaxWML]]'''

== First part ==
[scenario]

id=test-1
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]
. continued below
. ||
. \/

Every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario:
* The ''id'' (short for ''identifier'') is the computer's name for your scenario, and is not displayed during the game. However, it will be used to display game statistics (they will be graphed on http://stats.wesnoth.org in numerical order, so it's also a good idea to give the id's a number). This name is also used as reference in other tags and files, eg inside a '''[campaign]''' tag using the ''first_scenario'' key(see [[BuildingCampaignsTheCampaignFile]]) or inside a '''[scenario]''' tag using the ''next_scenario'' key (see below).

* The value of the ''next_scenario'' key is the id (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put '''next_scenario=null''' inside the file. This will tell the game to display the End screen when this scenario is won.

* The value of the ''name'' key is shown on the introduction screen before each scenario is played. (This can contain a picture of a map, or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explenation on how to do that.) It's also the default name for saves on the level.

* The next key, ''map_data'', is a link to the map file. You can create map files using the Wesnoth Map Editor (see [[WesnothMapEditor]] and [[BuildingMaps]] for more information). Since we may not know exactly where this campaign will be located we'll write two possible locations of the map file. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used to indicate where the data begins and ends. If you don't do this, it will break the scenario.

* Finally, the last key in the top set of keys is ''turns''. This is the amount of turns a player is given to finish the scenario. (It can be changed during the game, but again, that is stuff for later.) When the player fails to finish the secnario in the given time, he has lost. (Said otherwise: the ''defeat'' event is trigered. See [[EventWML]] for more.)

The next section is a set of preprocessors (see [[PreprocessorRef]]). Preprocessors are essentially WML shortcuts. They allow you to define certain pieces of code and re-use it whenever it is needed. Wesnoth provides you with a whole serie of standard preprocessors to make life more easy, but you yourself can define them too (again stuff for later).
Lets get back to this example! The preprocessors used here, describe how a day in this scenario should progress. This listing above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the preprocessors except for '''{SECOND_WATCH}'''. This could be useful if you have Konrad
fighting the Undead and want the Undead to have the upper hand the whole time. Remember though, by setting this to a single tme of day and not the normal progress listed above, your scenario will effectively be taking place during one day or night, not many days as most scenarios are.

The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.

A tag you'll get to know very good when making scenarios shows up: '''[event]...[/event]'''.
Event tags are used to describe what should be done if an 'event' takes place. What this event is, is described by ''name''key. In this case we're describing the so-called 'prestart' event. This one takes place just ''before'' the game starts and just ''after'' all of the introductions screens were shown.
Here we have limited the contents of the tag to another important tag: '''[objectives]''' (plural) containing any number of '''[objective]''' (singular) tags.
For each '''[objective]''' (singular) tag, if ''condition'' is set to "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is set to "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives. Because we've placed this tag inside a prestart event, this will be shown at the very first turn of the scenario.
The ''side'' key indicates that these conditions are for side 1 (see below).
The ' _ ' (underscore) facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.
Also note that the '''[objective]''' tag only describes what the objectives are. You will still need to set the appropiate events before they will work. (But that's again stuff for later)

== Second part ==
So far so good! The last necessary part describes what the players (Human and
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.

. /\
. ||
. continued from above
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]

Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
* ''side'': the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]) It's a number from 1 to 9.
* ''controller'': possible values are 'human' or 'ai' (artificial intelligence, meaning your computer). If you don't specify this key, 'ai' is used as the default.
* ''team_name'' describes which team the side is on. It defaults to the same number as ''side'', so setting it to ''2'' allies this side with side 2, if you haven't changed the team_name of side 2.
* ''user_team_name'' is the name displayed when you view the sie stats (by pressing alt+s during gameplay). The underscore facilitates translation using GetText (see [[GetText]]).

The next set of keys describe the leader of this side:
* ''canrecruit'': This key can be '1' or '0', meaning "yes" or "no" respectively. If you no, then the leader won't be able to recruit. (Not much of a leader then, is he?) Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
* ''type'' describes what type of unit the leader will be. The possible values are listed here: [[UnitTables]].
* ''description'' is the name and description of the leader.
In a campaign, all of these 'leader-describing' keys are ignored for the human player (except ''canrecruit''), since the leader from the previous scenario is used instead. However, the ''type'' key is still neccesary to prevent the scenario from crashing.

* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].

Then two more preprocessors are used:
* '''{GOLD easy normal hard}''' takes 3 positive numbers. These indicate the amount of money the player will start with on the EASY, NORMAL and HARD difficulty level.
In a campaign file, inside a human controlled side (''controller=human''), this is the minimum amount. The actual amount the player gets ca, be larger if the player retained more from previous scenarios.
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
The defaults for each of these values are 100 gold and 2 base income.

== Making it all work ==
Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
This should NOT be stored inside the main directory '''data/campaigns''' but inside '''userdata/data/campaigns'''. This prevents breaking the mainline campaigns or even worse, the entire game. (see [[BuildingCampaignsDirectoryStructure]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending .cfg (for example: testcampaign.cfg).
This is a short example on how to do this:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are described in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign. Scenarios following after this one are referenced inside the first scenario using ''next_scenario'' (see above).

The key '''difficulties=EASY,NORMAL,HARD''' tells the computer to set the macro '''EASY''' if the first difficulty choice is chosen, '''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
It is recommended that you do not use other names than '''EASY''', '''NORMAL''', and '''HARD''' for your macros, because if you do then the standard macros, such as '''{GOLD}''' and '''{INCOME}''', won't work properly.

Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image, displayed inside the campaign list.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to:
"difficulties=EASY,NORMAL,HARD"
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
then an equals (''='') sign, then the text to display (eg ''Easy'').
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

BuildingScenariosSimple

2007-06-27T19:26:28Z

Mathijs: /* Building scenarios: Simple */

<table width=100% border=0>
<tr>
<td>[[BuildingScenarios]]</td>
<td>[[BuildingScenariosWML]]</td>
<td>[[BuildingScenariosSimple]]</td>
<td>[[BuildingScenariosIntermediate]]</td>
<td>[[BuildingScenariosAdvanced]]</td>
</tr><tr>
<td></td>
<td>[[BuildingScenariosComments]]</td>
<td>[[BuildingScenariosSamples]]</td>
<td>[[BuildingScenariosFAQ]]</td>
<td></td>
</tr>
</table>

= Building scenarios: Simple =

This will show you a very simple scenario file, explaining each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove usefull to read something about the syntax used in the Wesnoth Markup Language: [[SyntaxWML]]'''

[scenario]

id=test-1
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]
. continued below
. ||
. \/

Every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario:
* The ''id'' (short for ''identifier'') is the computer's name for your scenario, and is not displayed during the game. However, it will be used to display game statistics (they will be graphed on http://stats.wesnoth.org in numerical order, so it's also a good idea to give the id's a number). This name is also used as reference in other tags and files, eg inside a '''[campaign]''' tag using the ''first_scenario'' key(see [[BuildingCampaignsTheCampaignFile]]) or inside a '''[scenario]''' tag using the ''next_scenario'' key (see below).

* The value of the ''next_scenario'' key is the id (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put '''next_scenario=null''' inside the file. This will tell the game to display the End screen when this scenario is won.

* The value of the ''name'' key is shown on the introduction screen before each scenario is played. (This can contain a picture of a map, or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explenation on how to do that.) It's also the default name for saves on the level.

* The next key, ''map_data'', is a link to the map file. You can create map files using the Wesnoth Map Editor (see [[WesnothMapEditor]] and [[BuildingMaps]] for more information). Since we may not know exactly where this campaign will be located we'll write two possible locations of the map file. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used to indicate where the data begins and ends. If you don't do this, it will break the scenario.

* Finally, the last key in the top set of keys is ''turns''. This is the amount of turns a player is given to finish the scenario. (It can be changed during the game, but again, that is stuff for later.) When the player fails to finish the secnario in the given time, he has lost. (Said otherwise: the ''defeat'' event is trigered. See [[EventWML]] for more.)

The next section is a set of preprocessors (see [[PreprocessorRef]]). Preprocessors are essentially WML shortcuts. They allow you to define certain pieces of code and re-use it whenever it is needed. Wesnoth provides you with a whole serie of standard preprocessors to make life more easy, but you yourself can define them too (again stuff for later).
Lets get back to this example! The preprocessors used here, describe how a day in this scenario should progress. This listing above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the preprocessors except for '''{SECOND_WATCH}'''. This could be useful if you have Konrad
fighting the Undead and want the Undead to have the upper hand the whole time. Remember though, by setting this to a single tme of day and not the normal progress listed above, your scenario will effectively be taking place during one day or night, not many days as most scenarios are.

The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.

A tag you'll get to know very good when making scenarios shows up: '''[event]...[/event]'''.
Event tags are used to describe what should be done if an 'event' takes place. What this event is, is described by ''name''key. In this case we're describing the so-called 'prestart' event. This one takes place just ''before'' the game starts and just ''after'' all of the introductions screens were shown.
Here we have limited the contents of the tag to another important tag: '''[objectives]''' (plural) containing any number of '''[objective]''' (singular) tags.
For each '''[objective]''' (singular) tag, if ''condition'' is set to "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is set to "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives. Because we've placed this tag inside a prestart event, this will be shown at the very first turn of the scenario.
The ''side'' key indicates that these conditions are for side 1 (see below).
The ' _ ' (underscore) facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.
Also note that the '''[objective]''' tag only describes what the objectives are. You will still need to set the appropiate events before they will work. (But that's again stuff for later)

So far so good. The last necessary part describes what the players (Human and
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.

. /\
. ||
. continued from above
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]

Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
* ''side'': the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]) It's a number from 1 to 9.
* ''controller'': possible values are 'human' or 'ai' (artificial intelligence, meaning your computer). If you don't specify this key, 'ai' is used as the default.
* ''team_name'' describes which team the side is on. It defaults to the same number as ''side'', so setting it to ''2'' allies this side with side 2, if you haven't changed the team_name of side 2.
* ''user_team_name'' is the name displayed when you view the sie stats (by pressing alt+s during gameplay). The underscore facilitates translation using GetText (see [[GetText]]).

The next set of keys describe the leader of this side:
* ''canrecruit'': This key can be '1' or '0', meaning "yes" or "no" respectively. If you no, then the leader won't be able to recruit. (Not much of a leader then, is he?) Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
* ''type'' describes what type of unit the leader will be. The possible values are listed here: [[UnitTables]].
* ''description'' is the name and description of the leader.
In a campaign, all of these 'leader-describing' keys are ignored for the human player (except ''canrecruit''), since the leader from the previous scenario is used instead. However, the ''type'' key is still neccesary to prevent the scenario from crashing.

* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].

Then two more preprocessors are used:
* '''{GOLD easy normal hard}''' takes 3 positive numbers. These indicate the amount of money the player will start with on the EASY, NORMAL and HARD difficulty level.
In a campaign file, inside a human controlled side (''controller=human''), this is the minimum amount. The actual amount the player gets ca, be larger if the player retained more from previous scenarios.
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
The defaults for each of these values are 100 gold and 2 base income.

Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
This should NOT be stored inside the main directory '''data/campaigns''' but inside '''userdata/data/campaigns'''. This prevents breaking the mainline campaigns or even worse, the entire game. (see [[BuildingCampaignsDirectoryStructure]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending .cfg (for example: testcampaign.cfg).
This is a short example on how to do this:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are described in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign. Scenarios following after this one are referenced inside the first scenario using ''next_scenario'' (see above).

The key '''difficulties=EASY,NORMAL,HARD''' tells the computer to set the macro '''EASY''' if the first difficulty choice is chosen, '''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
It is recommended that you do not use other names than '''EASY''', '''NORMAL''', and '''HARD''' for your macros, because if you do then the standard macros, such as '''{GOLD}''' and '''{INCOME}''', won't work properly.

Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image, displayed inside the campaign list.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to:
"difficulties=EASY,NORMAL,HARD"
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
then an equals (''='') sign, then the text to display (eg ''Easy'').
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]