BuildingScenariosSimple
I will show you a very simple scenario file, then explain each line of it. This file is not fully functional, but it shows you the basics needed to describe what this scenario is all about.
[scenario]
id=test-1 next_scenario=test-2
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]
First, 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 is the computer's name for your scenario, and is not displayed during the game. It is neccesary to put this name somewhere else, such as a campaign tag, as well, in order to actually play the scenario. Where you put the ID for the scenario indicates how you would play this scenario in-game. For example, if your scenario is for a campaign, you need to list it as the scenario following another scenario in the campaign.
The next_scenario key lists the scenario that is played after this one is won, with units from this scenario available for recall. The value of this key should be the same as the value of the id key in the scenario following it. If your scenario is not part of a campaign, putting next_scenario=null or skipping this line will cause the "End" screen to be displayed when you win.
The name key is shown on the introduction screen(which usually contains the map graphic) before each scenario is played. It is also the default name for saves on the level. The next key, map_data, is a link to the map file. Since we may not know exactly where this campaign will be installed we write two possible locations of the map data. The quotes are necessary because Wesnoth map data takes up multiple lines, so quotes are used instead to determine where the data begins and ends. The map file must be a valid Wesnoth map file; see BuildingMaps. Finally, the last key in the top set of keys is turns. This sets an event on the specified turn causing the player to lose.
The next section is a set of IDs. This section tell the game how a day 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 IDs except for {SECOND_WATCH}. This can be useful if you have Konrad fighting against the Undead and wanted the Undead to have the upper hand the whole time. Remember though, by setting this to a single ID and not the normal day listed above, your scenario will effectively be taking place during one day or night, not many days as the majority currently are.
The music key is a filename pointing to the music which plays. This music file must be in the music/ directory and must be in .ogg format.
The next part sets the objectives for the scenario. This is done inside an [event] tag, and to have the objectives set before the scenario starts, we must specify name=prestart. Inside the [event] tag, we have an [objectives] (plural) tag, which contains any number of [objective] (singular) tags. For each tag, if condition is "win", the text of description will be displayed in green after "Victory" in the Scenario Objectives. If condition is "lose", the text of description will be displayed in red after "Defeat" in the Scenario Objectives.
The ' _ ' 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.
So far so good. The last necessary part of a scenario describes what the players (Human and Computer) start with and can do. Each of the players is described through the [side] tag.
. . .
[side] side=1 controller=human team_name=2
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]
From the above example above you can see a sample [side] for the human player, Konrad. The first key, side, is the location where this player starts on the map, and is also the ID for this side. It is a number from 1 to 9. The next key that describes this player is controller. The possible values are 'human' and 'ai', with 'ai' as the default. After this, the team_name key describes which team the side is on. In this example Konrad is on team "2", which by default contains side 2. However, if you change the team_name of side 2, Konrad will no longer be allied with it.
The next set of keys describe the player's leader. First we have canrecruit. This key can be '0' or '1', which is "no" or "yes" respectively. If you say no, then the player's leader will not be able to recruit. And if he can't recruit, he's not really a leader, is he? Any team without a canrecruit=1 unit automatically loses, so be sure to use this key. The next key, type, is the type of unit the leader will be. The possible values are listed at UnitTables. The description is the name and description of the leader. All of these keys are ignored for the human player on all campaign scenarios except the first, since the leader from the previous scenario is used instead. However, the type key is still neccesary to prevent the scenario from crashing.
Next we have the recruit key which is a comma-separated list of units. The possible values are listed in UnitTables.
The last two things are IDs. == {GOLD} == inputs any 3 positive numbers. These indicate the amount of money the player will start with. The first value indicates the value on the EASY difficulty level; second NORMAL, third HARD. When this is inside the controller=human in a campaign file then the actual gold the player gets will be the maximum of this value, and the amount of gold the player retained from the previous scenario. The INCOME id is similar, but indicates the base income instead of the base gold. 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. This should usually be stored in its own file in data/campaigns/. 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, level1.cfg).
[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 enclosed 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 (Other scenarios are indicated using next_scenario).
The attribute difficulties=EASY,NORMAL,HARD tells the computer to give the macro EASY a value 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. It is recommended that you do not use any names other than == EASY, NORMAL, and HARD == for your macros, because if you do then the macros {GOLD} and {INCOME} will not work properly.
Two optional keys in [campaign] are difficulty_descriptions and icon. icon has value equal to an image. 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 (and last) on hard. Each difficulty display is an & sign, then the image to display, then a comma, then the text to display. Place an * sign before the display which you wish to be default difficulty, and it will be selected when the player has chosen the campaign.