Difference between revisions of "BuildingScenariosSimple"

From The Battle for Wesnoth Wiki
(Building scenarios: Simple)
Line 18: Line 18:
 
= Building scenarios: Simple =
 
= Building scenarios: Simple =
  
This will show you a very simple scenario file,
+
This will show you a very simple scenario file, explaining each line of it.
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.
This file is not fully functional, but it shows you
+
 
the basics needed to describe what this 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]
 
  [scenario]
 
   
 
   
id=test-1
+
  id=test-1
next_scenario=2_test-more
+
  next_scenario=2_test-more
 
   
 
   
name=A Simple Test Scenario
+
  name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
+
  map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20
+
  turns=20
 
   
 
   
{DAWN}
+
  {DAWN}
{MORNING}
+
  {MORNING}
{AFTERNOON}
+
  {AFTERNOON}
{DUSK}
+
  {DUSK}
{FIRST_WATCH}
+
  {FIRST_WATCH}
{SECOND_WATCH}
+
  {SECOND_WATCH}
 
   
 
   
music=wesnoth-1.ogg
+
  music=wesnoth-1.ogg
 
   
 
   
[event]
+
  [event]
name=prestart
+
    name=prestart
  [objectives]
+
    [objectives]
  side=1
+
      side=1
  [objective]
+
      [objective]
    description= _ "Defeat Enemy Leader"
+
        description= _ "Defeat Enemy Leader"
    condition=win
+
        condition=win
  [/objective]
+
      [/objective]
  [objective]
+
      [objective]
    description= _ "Death of Konrad"
+
        description= _ "Death of Konrad"
    condition=lose
+
        condition=lose
  [/objective]
+
      [/objective]
  [/objectives]
+
    [/objectives]
[/event]
+
  [/event]
  .
+
  . continued below
  .
+
  . ||
  .
+
  . \/
 
   
 
   
First, every scenario must be enclosed in a tag;
+
Every scenario must be enclosed in a tag;
 
the '''[scenario]''' tag is used for campaign scenarios.
 
the '''[scenario]''' tag is used for campaign scenarios.
 
The first set of keys in the scenario tag
 
The first set of keys in the scenario tag
describe the very basics of this scenario.
+
describe the very basics of this scenario:
The ''id'' is the computer's name for your 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).
and is not displayed during the game, but will be used on http://stats.wesnoth.org to display game statistics (they will be graphed there in numerical order, so it's a good idea to number the ids).
 
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
+
* 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.
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
+
* 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.
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.
+
* 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.
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 tells the game how a day should
+
* 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.)
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.
+
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).  
This music file must be in the ''music/'' directory and must be in .ogg format.
+
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 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.
+
The ''music'' key is a filename pointing to the music which plays. (See [[MusicListWML]] for more.)
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.
+
This music file must be in the ''music/'' directory and '''must''' be in .ogg format.
  
The ' _ ' facilitates translation using Gettext (see [[GetText]]).
+
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,
 
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.
 
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 of a scenario describes what the players (Human and
+
So far so good. The last necessary part describes what the players (Human and
Computer) start with and can do. Each of the players is described through
+
Computer) start with, what they can do and what they can't do. Each of the players is described in a '''[side]''' tag.
the '''[side]''' tag.
 
  
  .
+
  . /\
  .
+
  . ||
  .
+
  .  continued from above
   
+
  [side]
[side]
+
    side=1
side=1
+
    controller=human
controller=human
+
    team_name=2
team_name=2
+
    user_team_name= _ "Konrad's forces"
 
type=Commander
 
description=Konrad
 
canrecruit=1
 
 
   
 
   
recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman
+
    type=Commander
 +
    description=Konrad
 +
    canrecruit=1
 
   
 
   
{GOLD 100 50 0}
+
    recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman
{INCOME 10 5 0}
 
[/side]
 
 
   
 
   
 +
    {GOLD 100 50 0}
 +
    {INCOME 10 5 0}
 +
  [/side]
 
  [/scenario]
 
  [/scenario]
  
From the above example above you can see
+
Above you can see a sample '''[side]''' for the human player, Konrad. We wll describe every key more in detail below:
a sample '''[side]''' for the human player, Konrad.
+
* ''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.
The first key, ''side'',
+
* ''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.
is the location where this player starts on the map,
+
* ''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.
and is also the ID for this side.
+
* ''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]]).
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
+
The next set of keys describe the leader of this side:
list of units. The possible values are listed in [[UnitTables]].
+
* ''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.
  
The last two things are IDs.
+
* ''recruit'' is a comma-separated list of types of units. The possible values are listed in [[UnitTables]].
'''{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;
+
Then two more preprocessors are used:
second NORMAL, third HARD.
+
* '''{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.
When this is inside the ''controller=human'' in a campaign file
+
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.
then the actual gold the player gets will be the maximum of this value,
+
* '''{INCOME easy normal hard}''' is similar, but indicates the base income.
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.
 
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/'''.
+
Now, to make this scenario playable, we need to make a campaign for it. (see [[BuildingCampaignsTheCampaignFile]])
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending
+
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]])
.cfg (for example: testcampaign.cfg, level1.cfg).
+
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]
 
  [campaign]
name= _ "Test Campaign"
+
  name= _ "Test Campaign"
first_scenario=test-1
+
  first_scenario=test-1
difficulties=EASY,NORMAL,HARD
+
  difficulties=EASY,NORMAL,HARD
 
   
 
   
difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
+
  difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
+
  icon=elvish-fighter.png
 
  [/campaign]
 
  [/campaign]
  
Campaigns are enclosed in the '''[campaign]''' tag. The first key is ''name'', which is
+
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
 
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
+
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).
''next_scenario'').
 
  
The attribute '''difficulties=EASY,NORMAL,HARD'''
+
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.
tells the computer to give the macro '''EASY''' a value
+
The expression '''#ifdef''' can be used later to test these macros. (see [[PreprocessorRef]])
if the first difficulty choice is chosen,
+
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.
'''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''.
+
Two optional keys are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image.
+
''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
+
''difficulty_descriptions'' must have the same number of inputs as  '''difficulties''', most commonly three, separated by semicolons.
semicolons.
+
These inputs then map on to the difficulties, so that if you have set difficulties to:
These inputs then map on to the difficulties, so that if you have set difficulties to
+
"difficulties=EASY,NORMAL,HARD"
"difficulties=EASY,NORMAL,HARD",
+
the first input will specify the display on EASY, the second on NORMAL and the third on HARD.
the first input will specify the display
+
Each difficulty display description starts opens with an ampersand (''&''), then the image to display (eg ''elvish-fighter.png''),
on easy, the second on normal and the third (and last) on hard.
+
then an equals (''='') sign, then the text to display (eg ''Easy'').
Each difficulty display is an '''&''' sign, then the image to display,
+
Optionally you can place an asterisk (''*'') before one of the ampersands, and the corresponding difficulty will be selected by default (here NORMAL is default).
then an equals sign, 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 ==
 
== See Also ==
* [[BuildingMaps]]
+
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]]
+
* [[ScenarioWML]] & [[SyntaxWML]]
 
* [[BuildingScenarios]]
 
* [[BuildingScenarios]]

Revision as of 19:26, 27 June 2007

BuildingScenarios BuildingScenariosWML BuildingScenariosSimple BuildingScenariosIntermediate BuildingScenariosAdvanced
BuildingScenariosComments BuildingScenariosSamples BuildingScenariosFAQ


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