Difference between revisions of "BuildingScenariosSimple"

From The Battle for Wesnoth Wiki
m (EASY''', ||NORMAL||, and '''HARD)
Line 190: Line 190:
The expression '''#ifdef''' can be used later to test these macros.
The expression '''#ifdef''' can be used later to test these macros.
It is recommended that you do not use any names other than
It is recommended that you do not use any names other than
== EASY''', ||NORMAL||, and '''HARD == for your macros,
== '''EASY''', '''NORMAL''', and '''HARD''' == for your macros,
because if you do then the macros '''{GOLD}|| and ||{INCOME}''' will not work properly.
because if you do then the macros '''{GOLD}''' and '''{INCOME}''' will not work properly.
Two optional keys in '''[campaign]''' are ''difficulty_descriptions'' and ''icon''.
Two optional keys in '''[campaign]''' are ''difficulty_descriptions'' and ''icon''.
Line 210: Line 210:
* [[ScenarioWML]]
* [[ScenarioWML]]
* [[BuildingScenarios]]
* [[BuildingScenarios]]

Revision as of 03:22, 5 November 2005

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.

name=A Simple Test Scenario
objectives= _ "
@Defeat enemy leader
#Death of Konrad"

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 final two keys are not really related to one another in any way. 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 objectives key is nothing more than the text displayed in the Scenario Objectives box in-game. The ' _ ' facilitates translation using Gettext (see GetText). You can type anything you want to within this key. Note that having one of the symbols '@' and '#' at the beginning of a line in this key will color the line green and red, respectively.

Conventions for Objectives:

The objectives key is conventionally used as a way of telling the player how to win the scenario. The following common objectives are often implied rather than stated:

@Defeat all enemy leaders
#Death of leader
#Turns run out

One or more objectives are listed under the words Victory and under Defeat. ANY Victory or Defeat objective can be met to win or lose the scenario, but a single Victory objective may have multiple parts. The Victory objectives are colored green while Defeat objectives are colored red.

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.

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman
{GOLD 100 50 0}
{INCOME 10 5 0}

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

name= _ "Test Campaign"
difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"

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.

See Also