Quick Navigation

Learning things step by step

Here we will show you a very simple scenario file and explain 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 useful to read something about the syntax of 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 attributes in the scenario tag describe the very basics of this scenario:

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 at 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 referenced in other tags and files, e.g., 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 may contain a picture of a map or anything else you fancy. See BuildingScenariosIntermediate for an explanation on how to do that). It's also the default name of saved files for 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). It may not be known exactly where this campaign will be located, so in this example we've writen two possible locations for the map file. Also, since the map data in this file uses multiple lines, and since the value of the map_data attribute will later be replaced with this multi-line map data by the Wesnoth preprocesser, quotation marks are needed to indicate where the data begins and ends. Not using the quotation marks breaks the scenario.

Finally, the last key in the top set of keys is turns. This is the number of turns a player is given to finish the scenario (it can be changed during the game, but again, that is stuff for later). If the player fails to finish the scenario in the given time, he has lost (i.e., the defeat event is triggered. See EventWML for more.)

The next section is a group of macros processed by Wesnoth's preprocessers. Macros are essentially WML shortcuts. They allow you to define certain pieces of code which can be re-used whenever they are needed. Wesnoth provides you with a whole series of standard preprocessors to make life easier, but you yourself can write them too (again stuff for later). Let's get back to this example! The macros listed above describe how a day in this scenario will progress. The list of macros above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the macros except for {SECOND_WATCH}. This, for example, might be useful if you've set Konrad to fight the Undead and also want the Undead to have the upper hand throughout the scenario. Remember, though, by setting this to a single time of day rather than the normal diurnal progression shown above, your scenario will effectively take place during one day (or night) rather than across many days as most scenarios do.

The music attribute takes for its value the name of a music file (see MusicListWML for more). This file must be in the music/ directory and must be in Ogg format.

A tag you'll get to know very well when making scenarios is [event]...[/event]. event tags are used to describe what should be done if an event takes place. What this event would be is described by the name attribute. In this case we're describing the so-called prestart event. This event takes place just before the game starts and just after all the introduction screens are shown. Here we have limited the contents of the event tag to just the name attribute and another important tag: [objectives] (N.B. that objectives is plural) containing any number of [objective] (N.B. the singular here) tags. For each [objective] 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 same Objectives. Because we've placed the [objectives] tag inside a prestart event, this will be shown on the very first turn of the scenario.

The side attribute in [objectives] indicates that the conditions defined here by the [object] tags are for the allied faction side 1 (see below). The underscore ("_") facilitates translation using Gettext.

Note that any Victory or Defeat objective can be met in order 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 appropriate 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=yes

    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 'yes' or 'no' (boolean equivalents 1 and 0 and true or false work too). 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=yes 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: the unit tables.
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 the unit tables.

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 can 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).

BuildingScenariosSimple

Quick Navigation

Contents

Learning things step by step

First part

Second part

Making it all work

See Also