Difference between revisions of "WML Templates"

From The Battle for Wesnoth Wiki
(Clarifications, tidying, some rewording. Unfinished. Will continue 26/01/09. Revert on 28/01 if I don't get back to it...)
(Finished campaign.cfg. Units, utils, scenarios, maps still to do. And needs sanity checking.)
Line 1: Line 1:
These templates are bases for campaigns, scenarios, and units;
+
This page provides a set of blank 'templates' which can be used as a basis for user-made campaigns, scenarios, and units. You will need to have a basic understanding of WML to make best use of these resources. See [[ReferenceWML]]. You will also need to understand how to create text files on your computer and set up an appropriate directory structure for the campaign. By the time you have created a simple campaign using these templates, you should have learned enough about WML to be able to create more ambitious work on your own.
fill in the blanks to create one.
 
Knowledge of WML is recommended to use these templates; see [[ReferenceWML]].
 
  
 
== Campaigns ==
 
== Campaigns ==
  
For your basic campaign, you will need the following .cfg files in the correct locations. Replace all occurrences of CAMPAIGN_NAME with the name of your campaign. THE NAMES MUST BE ''EXACTLY'' as shown for everything to work reliably. Names should be assumed to be case-sensitive, and you're advised to use underscores _ for spaces between words. Avoid accented characters as well. If you do not, you may find that your campaign only works properly for other people using the same OS as you.<br>
+
For a basic campaign, you need to create a set of .cfg files in the correct locations. That also means you have to create a set of correctly-named directories as well. These examples will lead you through the basic setup of a campaign called ''Example_Campaign''. You will need to replace all occurrences of 'Example_Campaign' will the name of your own campaign.
  
For Linux users, assume that all paths are relative to '''/home/(your username)/.wesnoth/data/campaigns/'''. You do not ever have to add anything to your main Wesnoth folder (the one under /usr/local/share/wesnoth or similar). In fact it is best never to edit any of those files.<br>
+
For everything to work reliably, the names must be ''exactly'' as shown. If there is a mismatch between any of the names, Wesnoth will not be able to find all the data it needs to run your campaign, and it will stop dead with an error. Assume that all names are case-sensitive, and use underscores ( _ ) for spaces between words. Avoid accented characters as well. If you do not, you may find that your campaign only works properly for other people using the same operating system as you.
  
To make a campaign, you will need the following:
+
For Linux users, all paths are relative to '''/home/(your username)/.wesnoth/data/campaigns/'''. You do not ever have to alter your main Wesnoth folder (the one under /usr/local/share/wesnoth or similar). The game has been organised so that your can keep your own data separate from the main Wesnoth data, so that your custom campaigns do not interfere with the workings of the rest of the game.
*A blank text file: /CAMPAIGN_NAME.cfg
 
*A campaign folder: /CAMPAIGN_NAME/
 
*A scenario folder: /CAMPAIGN_NAME/scenarios/
 
*At least one scenario file: /CAMPAIGN_NAME/scenarios/SCENARIO_NAME.cfg
 
*A maps folder:    /CAMPAIGN_NAME/maps/
 
*As many maps as scenarios (covered elsewhere)
 
  
If you are going to use custom units, images and macros, you will need the following files:
+
To make a campaign, you will need to create the following files and directories:
*A units folder: /CAMPAIGN_NAME/units/
+
 
*An images folder: /CAMPAIGN_NAME/images/
+
*A blank text file: /Example_Campaign.cfg
*And a utilities (macros) folder: /CAMPAIGN_NAME/utils/
+
*A campaign folder: /Example_Campaign/
 +
*A scenario folder: /Example_Campaign/scenarios/
 +
*At least one scenario file: /Example_Campaign/scenarios/First_Scenario.cfg
 +
*A maps folder: /Example_Campaign/maps/
 +
*As many maps as scenarios (covered elsewhere). These maps will usually be called /Example_Campaign/maps/First_Scenario.map, Second_Scenario.map and so on, but there may be exceptions.
 +
 
 +
If you are going to use custom units, images or macros, you will also need to create the following directories:
 +
 
 +
*A units folder: /Example_Campaign/units/
 +
*An images folder: /Example_Campaign/images/
 +
*A utilities (macros) folder: /Example_Campaign/utils/
 +
 
 +
You can add these extra folders later on, when you need them, or you can create a full set of folders right at the start. As it does no harm to set them all up in advance and leave them empty, we suggest you do so.
  
 
It is important that you place all the parts of your campaign in the right places and that the folders are named correctly, because Wesnoth will look for these folders to find your scenarios, images etc.
 
It is important that you place all the parts of your campaign in the right places and that the folders are named correctly, because Wesnoth will look for these folders to find your scenarios, images etc.
  
=== _main.cfg, the campaign file ===
 
  
There are two parts of the _main.cfg file. You need both of them in the same file for your campaign to work.
+
=== 1. Example_Campaign.cfg, [Campaign] section ===
''Instructions for use of the following file''
+
 
Start by find/replacing CAMPAIGN_NAME with the name of your campaign (Must be exactly the same as the folder!)
+
The Example_Campaign.cfg file has two parts. The first part determines the available difficulty settings and difficulty descriptions for your campaign. Without this data, your campaign will not appear in the Wesnoth menu, and you won't be able to select it for playing. The difficulty settings are listed between a [campaign] and a [/campaign] tag as shown below. The parts marked in bold are the bits you should customise:
Also replace:
 
* (## 'easy'/'normal'/'hard' icon) with the name of an image, relative to your image folder or the wesnoth main folder. E.g. "mylogo.png" or "misc/chest.png"
 
* (## 'easy'/'normal'/'hard' description) with a very brief description of the difficulty e.g. "For Newbies", "Normal", "Significant Challenge!"
 
* Follow the instructions in the comments.
 
  
 
  [campaign]
 
  [campaign]
# The name= tag is the name that the user will see on the campaign screen.
+
 
  name= _ ""
+
  name= _ "'''An Example Campaign'''"
  id=CAMPAIGN_NAME
+
  id='''EXAMPLE_CAMPAIGN'''
# This define key is important, keep reading and you will see why.
+
  define='''EXAMPLE_CAMPAIGN'''
  define=CAMPAIGN_NAME
+
  first_scenario='''First_Scenario'''
# Put the id of the first scenario here eg START_SCENARIO. As long as it is in the /scenarios/ folder,
+
 
# Wesnoth will find it. (it does not have to have the same filename, but it helps)
 
  first_scenario=
 
 
  difficulties=EASY,NORMAL,HARD
 
  difficulties=EASY,NORMAL,HARD
# Do the replacing here as listed above
+
  difficulty_descriptions={MENU_IMG_TXT2 '''Easy_Image.png'''
  difficulty_descriptions={MENU_IMG_TXT2 ## 'easy' icon
+
  _"'''Easy setting description'''" _"(Easy)"} + ";"
  _"## 'easy' description
+
+ {MENU_IMG_TXT2 '''Normal_Image.png'''
" _"(easiest)"} + ";" + {MENU_IMG_TXT ## 'normal' icon
+
  _"'''Normal setting description'''" _"(Normal)"} + ";"
  _"## 'normal' description
+
+ {MENU_IMG_TXT2 '''Hard_Image.png'''
"} + ";" + {MENU_IMG_TXT2 ## 'hard' icon
+
  _"'''Hard setting description'''" _"(Hard)"}
  _"## 'hard' description
+
 
" _"(hardest)"}
+
icon='''Campaign_Icon.png'''
 +
description= _ "'''This is an example campaign template, all ready to be customised.'''"
 +
 
 +
  [about]
 +
    title= _ "Campaign Designer"
 +
    text="'''Your Name'''"
 +
  [/about]
 +
  [about]
 +
    title= _ "Current Maintainer"
 +
    text="'''Your Name'''"
 +
  [/about]
  
# icon is optional. If you provide an icon, this will be the campaign icon seen on the campaign selection screen.
 
icon=
 
# The decription is the 'story' that the user will see when they click on the campaign.
 
description= _ ""
 
# This is the image that the user will see next to the description. Remember, all images
 
# are relative to your campaign's image folder or Wesnoth's image folder. (So if your image
 
# is directly in your image folder, you can just use "image1.png" or whatever.)
 
image=
 
 
  [/campaign]
 
  [/campaign]
 +
 +
 +
Working through this block of data a few lines at a time:
 +
 +
 +
name= _ "'''An Example Campaign'''"
 +
 +
The name of your campaign as it is displayed in the Wesnoth game. This is free-text. The name should more-or-less correspond to the name of the campaign folder, but you don't have to worry about file naming restrictions such as having to use underscores for spaces.
 +
 +
 +
id='''EXAMPLE_CAMPAIGN'''
 +
 +
The campaign identifier. This is used internally by the Wesnoth game.
 +
 +
 +
define='''EXAMPLE_CAMPAIGN'''
 +
 +
We will call this important entry the ''campaign name key''. The #ifdef command used in section 2 must exactly match whatever you define here.
 +
 +
 +
first_scenario='''First_Scenario'''
 +
 +
The scenario identifier for the first scenario. This must exactly match the scenario ID in the relevant scenario file. It's helpful (but not compulsory) to have the scenario filename and the scenario ID match.
 +
 +
 +
difficulties=EASY,NORMAL,HARD
 +
 +
Three different difficulty levels is very common for Wesnoth scenarios, but you can have more or fewer if you want. For now, stick with three, and keep their names unaltered.
 +
 +
 +
difficulty_descriptions={MENU_IMG_TXT2 '''Easy_Image.png'''
 +
_"'''Easy setting description'''" _"(Easy)"} + ";"
 +
+ {MENU_IMG_TXT2 '''Normal_Image.png'''
 +
_"'''Normal setting description'''" _"(Normal)"} + ";"
 +
+ {MENU_IMG_TXT2 '''Hard_Image.png'''
 +
_"'''Hard setting description'''" _"(Hard)"}
 +
 +
There are six different things you can customise here. The Easy, Normal and Hard setting descriptions are usually set to an atmospheric name for the corresponding difficulty level. For example, you might use 'Scout' for the easiest setting, 'Warrior' for the middle setting, and 'General' for the hardest setting. As a rough guide, you should limit yourself to 1-3 words for each difficulty description. The Easy_Image.png, Normal_Image.png and Hard_Image.png refer to custom graphics for each difficulty level. Normally you would save these in the /Example_Campaign/images/ folder. You can also use any standard Wesnoth graphic. For example, if you wanted to use the image of an orcish archer for one of the difficulty settings, you would give the filename as units/orcs/archer.png
 +
 +
 +
icon='''Campaign_Icon.png'''
 +
 +
A custom campaign icon is optional. If you want to use a standard Wesnoth image, provide the path from the main Wesnoth images directory. For example, items/monolith3.png
 +
Otherwise Wesnoth will look in the /Example_Campaign/images/ folder, in this example for a png file called Campaign_Icon.png
 +
 +
 +
description= _ "'''This is an example campaign template, all ready to be customised.'''"
 +
 +
The campaign description is also free-text. This is a chance to give a quick summary of what your campaign is about. 2-3 lines of text is about the right length.
 +
 +
 +
  [about]
 +
    title= _ "Campaign Designer"
 +
    text="'''Your Name'''"
 +
  [/about]
 +
  [about]
 +
    title= _ "Current Maintainer"
 +
    text="'''Your Name'''"
 +
  [/about]
 +
 +
 +
If you're planning to share the campaign with others, it's helpful to have a bit of information about who you are. You might also want to credit the people who have helped you with artwork, debugging, or lots of other things, but at the minimum you should fill in your name as the original campaign designer and presumably as the current maintainer too.
 +
 +
 +
Having filled in and customised all of this data, you have set up a workable skeleton campaign structure. There are extra pieces of data that could be inserted into the campaign section, but the basic setup described here is enough to be going on with. Once you are ready to be more ambitions, see [[CampaignWML]] for details on other tags and customisation that could be of use.
 +
 +
 +
=== 2. Example_Campaign.cfg, #define section ===
 +
 +
When Wesnoth starts up, it scans for all available campaign files. But loading ''all'' the images, macros, units etc. from all available campaigns might take a very long time and might cause errors, so when Wesnoth first starts it only reads the data stored between [campaign] tags.
 +
 +
 +
Remember the line
 +
 +
define=EXAMPLE_CAMPAIGN
 +
 +
? When a particular campaign is selected by the player, Wesnoth starts loading all the rest of the data for that particular campaign. But for Wesnoth to do this, the ''campaign name key'' and the campaign data must match up correctly. Assuming they do, all the scenario code found by Wesnoth matching the campaign name key will be run. And that is what the lines of code below are for:
 
   
 
   
  #-----------------second part of campaign file----------------------------------------
+
  #ifdef '''EXAMPLE_CAMPAIGN'''
# That is all that should go between the campaign tags. Remember the line "define=CAMPAIGN_NAME"?
+
 
# This sets up the ''campaign name key''. When Wesnoth starts up, it reads all the campaign files.
+
  [binary_path]
  # So that it doesn't load
+
    path=data/campaigns/'''Example_Campaign'''
# ''all'' the images, macros, units etc from all available campaigns (which would take a long
+
  [/binary_path]
  # time and might cause errors), when Wesnoth first starts it only reads the data stored between campaign tags.
+
 
  # But when a particular campaign is selected by the player, Wesnoth starts loading all the rest of the  # data for that particular campaign. But for Wesnoth to do this, the campaign name key and the campaign data must match up correctly. But assuming they do, all the scenario code found by Wesnoth matching the #ifdef code found by Wesnoth will be run. And that is what the line of code below is for. :)
+
  # Load campaign utilities first
   
+
  {@campaigns/'''Example_Campaign'''/utils}
#ifdef CAMPAIGN_NAME
+
 
 
# this adds any custom units you have created for your campaign to Wesnoth's pool of units it knows
 
# about.
 
 
  [+units]
 
  [+units]
        # remember, you are listing the path to the folder, not individual files.
+
  {@campaigns/'''Example_Campaign'''/units}
        {@campaigns/CAMPAIGN_NAME/units}
 
 
  [/units]
 
  [/units]
 +
 +
{@campaigns/'''Example_Campagn'''/scenarios}
 +
 +
#endif
 +
 +
 +
What do these lines of data do?
 +
 
   
 
   
  # the [binary_path] tag tells wesnoth where the images/, units/, scenarios/, maps/ and utils/
+
  #ifdef '''EXAMPLE_CAMPAIGN'''
# folders are.
+
 
 +
This must match the define=EXAMPLE_CAMPAIGN from section 1.
 +
 
 +
 
 
  [binary_path]
 
  [binary_path]
     path=data/campaigns/CAMPAIGN_NAME
+
     path=data/campaigns/'''Example_Campaign'''
 
  [/binary_path]
 
  [/binary_path]
+
 
  # This tells wesnoth to include any .cfg files it find in these folders.
+
The [binary_path] tag tells Wesnoth where the images/, units/, scenarios/, maps/ and utils/ folders are.
  {@campaigns/CAMPAIGN_NAME/utils}
+
 
  {@campaigns/CAMPAIGN_NAME/scenarios}
+
 
 +
  # Load campaign utilities first
 +
 
 +
This line is just a free-text comment. Note that in WML, the order in which we load things matters. It's usually a good idea to load campaign macros and utilities as soon as possible.  By loading these utilities ''before'' the units and scenarios, we know that our custom utilities are available for use in our unit and scenario definitions. Trying to load scenario resources in the wrong order is a common cause of problems when writing campaigns. If for some reason you need to load things in a different order to make your campaign work, adjust the warning accordingly.
 +
 
 +
 
 +
  {@campaigns/'''Example_Campaign'''/utils}
 +
 
 +
This line loads all the campaign macros and utilities.
 +
 
 +
 
 +
[+units]
 +
  {@campaigns/'''Example_Campaign'''/units}
 +
[/units]
 +
 
 +
These lines load all the custom units for the campaign.
 +
 
 +
 
 +
  {@campaigns/'''Example_Campagn'''/scenarios}
 +
 
 +
And this line ensures that Wesnoth can load the next scenario when the previous one is completed.
 +
 
 +
 
 
  #endif
 
  #endif
  
=== Basic utils.cfg ===
+
The #ifdef at the start of section 2 is a special multi-line instruction which must be closed using an #endif tag.
 +
 
 +
 
 +
=== 3. utils.cfg ===
 +
 
 
Next you need  /CAMPAIGN_NAME/utils/utils.cfg: (remember, this is in '''/home/(your username)/.wesnoth/data/campaigns/''' (under linux), '''NOT''' /usr/local/share/wesnoth/data/campaigns!!!)
 
Next you need  /CAMPAIGN_NAME/utils/utils.cfg: (remember, this is in '''/home/(your username)/.wesnoth/data/campaigns/''' (under linux), '''NOT''' /usr/local/share/wesnoth/data/campaigns!!!)
  
Line 102: Line 211:
 
  #enddef
 
  #enddef
 
   
 
   
  # This is a macro that will trigger on the death of your heros (if you want one)
+
  # This is a macro that will trigger on the death of your heroes (if you want one)
 
  #define DEATHS
 
  #define DEATHS
 
  [event]## Copy for each of the heroes
 
  [event]## Copy for each of the heroes
Line 119: Line 228:
 
  #enddef
 
  #enddef
  
=== Scenarios ===
+
=== 4. Scenarios ===
  
 
Note: this template refers to macros in the template utils.cfg shown above.
 
Note: this template refers to macros in the template utils.cfg shown above.
Line 155: Line 264:
 
   type=
 
   type=
 
   
 
   
canrecruit=yes
+
  canrecruit=yes
recruit=
+
  recruit=
[/side]
+
  [/side]
[side]## Copy for enemies
+
  [side]## Copy for enemies
side=2
+
  side=2
team_name=enemy
+
  team_name=enemy
  
description=
+
  description=
type=
+
  type=
  
canrecruit=yes
+
  canrecruit=yes
recruit=
+
  recruit=
{GOLD }
+
  {GOLD }
[/side]
+
  [/side]
{DEATHS}
+
  {DEATHS}
[event]
+
  [event]
name=start
+
  name=start
[recall]
+
    [recall]
description=
+
    description=
[/recall]
+
    [/recall]
[message]
+
    [message]
description=
+
    description=
message= _ ""
+
    message= _ ""
[/message]
+
    [/message]
[objectives]
+
    [objectives]
side=1
+
    side=1
[objective]
+
      [objective]
description= _ ""
+
      description= _ ""
condition=win
+
      condition=win
[/objective]
+
      [/objective]
[objective]
+
      [objective]
description= _ "Death of "
+
      description= _ "Death of "
condition=lose
+
      condition=lose
[/objective]
+
      [/objective]
[objective]
+
      [objective]
description= _ "Death of "
+
      description= _ "Death of "
condition=lose
+
      condition=lose
[/objective]
+
      [/objective]
[objective]
+
      [objective]
description= _ "Turns run out"
+
      description= _ "Turns run out"
condition=lose
+
      condition=lose
[/objective]
+
      [/objective]
[/objectives]
+
    [/objectives]
[/event]
+
  [/event]
[event]## Copy for events
+
  [event]## Copy for events
name=
+
  name=
[filter]
+
    [filter]
[/filter]
+
    [/filter]
[message]## Copy for messages
+
    [message]## Copy for messages
description=
+
    description=
message= _ ""
+
    message= _ ""
[/message]
+
    [/message]
[/event]
+
  [/event]
 
  [/scenario]
 
  [/scenario]
  
== Units ==
+
=== 5. Units ===
  
 
  [unit]
 
  [unit]
Line 232: Line 341:
 
  unit_description= _ ""
 
  unit_description= _ ""
 
  get_hit_sound=groan.wav
 
  get_hit_sound=groan.wav
[attack]
+
  [attack]
name= _ ""
+
  name= _ ""
type=
+
  type=
damage=
+
  damage=
number=
+
  number=
special=null
+
  special=null
[frame]
+
    [frame]
begin=-100
+
    begin=-100
end=100
+
    end=100
image=
+
    image=
[/frame]
+
    [/frame]
[sound]
+
    [sound]
time=-200
+
    time=-200
sound=
+
    sound=
[/sound]
+
    [/sound]
[/attack]
+
  [/attack]
[attack]
+
  [attack]
name= _ ""
+
  name= _ ""
type=
+
  type=
range=long
+
  range=long
damage=
+
  damage=
number=
+
  number=
special=null
+
  special=null
[sound]
+
    [sound]
time=-200
+
    time=-200
sound=
+
    sound=
[/sound]
+
    [/sound]
[missile_frame]
+
    [missile_frame]
begin=-100
+
    begin=-100
end=0
+
    end=0
image=
+
    image=
image_diagonal=
+
    image_diagonal=
[/missile_frame]
+
    [/missile_frame]
[/attack]
+
  [/attack]
 
  [/unit]
 
  [/unit]
  
 
== See Also ==
 
== See Also ==
  
* [[UsefulWMLFragments]]
+
* [[UsefulWMLFragments]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
  
 
[[Category: UsefulWMLFragments]]
 
[[Category: UsefulWMLFragments]]

Revision as of 22:42, 26 January 2009

This page provides a set of blank 'templates' which can be used as a basis for user-made campaigns, scenarios, and units. You will need to have a basic understanding of WML to make best use of these resources. See ReferenceWML. You will also need to understand how to create text files on your computer and set up an appropriate directory structure for the campaign. By the time you have created a simple campaign using these templates, you should have learned enough about WML to be able to create more ambitious work on your own.

Campaigns

For a basic campaign, you need to create a set of .cfg files in the correct locations. That also means you have to create a set of correctly-named directories as well. These examples will lead you through the basic setup of a campaign called Example_Campaign. You will need to replace all occurrences of 'Example_Campaign' will the name of your own campaign.

For everything to work reliably, the names must be exactly as shown. If there is a mismatch between any of the names, Wesnoth will not be able to find all the data it needs to run your campaign, and it will stop dead with an error. Assume that all names are case-sensitive, and use underscores ( _ ) for spaces between words. Avoid accented characters as well. If you do not, you may find that your campaign only works properly for other people using the same operating system as you.

For Linux users, all paths are relative to /home/(your username)/.wesnoth/data/campaigns/. You do not ever have to alter your main Wesnoth folder (the one under /usr/local/share/wesnoth or similar). The game has been organised so that your can keep your own data separate from the main Wesnoth data, so that your custom campaigns do not interfere with the workings of the rest of the game.

To make a campaign, you will need to create the following files and directories:

  • A blank text file: /Example_Campaign.cfg
  • A campaign folder: /Example_Campaign/
  • A scenario folder: /Example_Campaign/scenarios/
  • At least one scenario file: /Example_Campaign/scenarios/First_Scenario.cfg
  • A maps folder: /Example_Campaign/maps/
  • As many maps as scenarios (covered elsewhere). These maps will usually be called /Example_Campaign/maps/First_Scenario.map, Second_Scenario.map and so on, but there may be exceptions.

If you are going to use custom units, images or macros, you will also need to create the following directories:

  • A units folder: /Example_Campaign/units/
  • An images folder: /Example_Campaign/images/
  • A utilities (macros) folder: /Example_Campaign/utils/

You can add these extra folders later on, when you need them, or you can create a full set of folders right at the start. As it does no harm to set them all up in advance and leave them empty, we suggest you do so.

It is important that you place all the parts of your campaign in the right places and that the folders are named correctly, because Wesnoth will look for these folders to find your scenarios, images etc.


1. Example_Campaign.cfg, [Campaign] section

The Example_Campaign.cfg file has two parts. The first part determines the available difficulty settings and difficulty descriptions for your campaign. Without this data, your campaign will not appear in the Wesnoth menu, and you won't be able to select it for playing. The difficulty settings are listed between a [campaign] and a [/campaign] tag as shown below. The parts marked in bold are the bits you should customise:

[campaign]
name= _ "An Example Campaign"
id=EXAMPLE_CAMPAIGN
define=EXAMPLE_CAMPAIGN
first_scenario=First_Scenario
difficulties=EASY,NORMAL,HARD
difficulty_descriptions={MENU_IMG_TXT2 Easy_Image.png
_"Easy setting description" _"(Easy)"} + ";"
+ {MENU_IMG_TXT2 Normal_Image.png
_"Normal setting description" _"(Normal)"} + ";"
+ {MENU_IMG_TXT2 Hard_Image.png
_"Hard setting description" _"(Hard)"}
icon=Campaign_Icon.png
description= _ "This is an example campaign template, all ready to be customised."
  [about]
    title= _ "Campaign Designer"
    text="Your Name"
  [/about]
  [about]
    title= _ "Current Maintainer"
    text="Your Name"
  [/about]
[/campaign]


Working through this block of data a few lines at a time:


name= _ "An Example Campaign"

The name of your campaign as it is displayed in the Wesnoth game. This is free-text. The name should more-or-less correspond to the name of the campaign folder, but you don't have to worry about file naming restrictions such as having to use underscores for spaces.


id=EXAMPLE_CAMPAIGN

The campaign identifier. This is used internally by the Wesnoth game.


define=EXAMPLE_CAMPAIGN

We will call this important entry the campaign name key. The #ifdef command used in section 2 must exactly match whatever you define here.


first_scenario=First_Scenario

The scenario identifier for the first scenario. This must exactly match the scenario ID in the relevant scenario file. It's helpful (but not compulsory) to have the scenario filename and the scenario ID match.


difficulties=EASY,NORMAL,HARD

Three different difficulty levels is very common for Wesnoth scenarios, but you can have more or fewer if you want. For now, stick with three, and keep their names unaltered.


difficulty_descriptions={MENU_IMG_TXT2 Easy_Image.png
_"Easy setting description" _"(Easy)"} + ";"
+ {MENU_IMG_TXT2 Normal_Image.png
_"Normal setting description" _"(Normal)"} + ";"
+ {MENU_IMG_TXT2 Hard_Image.png
_"Hard setting description" _"(Hard)"}

There are six different things you can customise here. The Easy, Normal and Hard setting descriptions are usually set to an atmospheric name for the corresponding difficulty level. For example, you might use 'Scout' for the easiest setting, 'Warrior' for the middle setting, and 'General' for the hardest setting. As a rough guide, you should limit yourself to 1-3 words for each difficulty description. The Easy_Image.png, Normal_Image.png and Hard_Image.png refer to custom graphics for each difficulty level. Normally you would save these in the /Example_Campaign/images/ folder. You can also use any standard Wesnoth graphic. For example, if you wanted to use the image of an orcish archer for one of the difficulty settings, you would give the filename as units/orcs/archer.png


icon=Campaign_Icon.png

A custom campaign icon is optional. If you want to use a standard Wesnoth image, provide the path from the main Wesnoth images directory. For example, items/monolith3.png Otherwise Wesnoth will look in the /Example_Campaign/images/ folder, in this example for a png file called Campaign_Icon.png


description= _ "This is an example campaign template, all ready to be customised."

The campaign description is also free-text. This is a chance to give a quick summary of what your campaign is about. 2-3 lines of text is about the right length.


  [about]
    title= _ "Campaign Designer"
    text="Your Name"
  [/about]
  [about]
    title= _ "Current Maintainer"
    text="Your Name"
  [/about]


If you're planning to share the campaign with others, it's helpful to have a bit of information about who you are. You might also want to credit the people who have helped you with artwork, debugging, or lots of other things, but at the minimum you should fill in your name as the original campaign designer and presumably as the current maintainer too.


Having filled in and customised all of this data, you have set up a workable skeleton campaign structure. There are extra pieces of data that could be inserted into the campaign section, but the basic setup described here is enough to be going on with. Once you are ready to be more ambitions, see CampaignWML for details on other tags and customisation that could be of use.


2. Example_Campaign.cfg, #define section

When Wesnoth starts up, it scans for all available campaign files. But loading all the images, macros, units etc. from all available campaigns might take a very long time and might cause errors, so when Wesnoth first starts it only reads the data stored between [campaign] tags.


Remember the line

define=EXAMPLE_CAMPAIGN

? When a particular campaign is selected by the player, Wesnoth starts loading all the rest of the data for that particular campaign. But for Wesnoth to do this, the campaign name key and the campaign data must match up correctly. Assuming they do, all the scenario code found by Wesnoth matching the campaign name key will be run. And that is what the lines of code below are for:

#ifdef EXAMPLE_CAMPAIGN
[binary_path]
   path=data/campaigns/Example_Campaign
[/binary_path]
# Load campaign utilities first
{@campaigns/Example_Campaign/utils}
[+units]
  {@campaigns/Example_Campaign/units}
[/units]
{@campaigns/Example_Campagn/scenarios}
#endif


What do these lines of data do?


#ifdef EXAMPLE_CAMPAIGN

This must match the define=EXAMPLE_CAMPAIGN from section 1.


[binary_path]
   path=data/campaigns/Example_Campaign
[/binary_path]

The [binary_path] tag tells Wesnoth where the images/, units/, scenarios/, maps/ and utils/ folders are.


# Load campaign utilities first

This line is just a free-text comment. Note that in WML, the order in which we load things matters. It's usually a good idea to load campaign macros and utilities as soon as possible. By loading these utilities before the units and scenarios, we know that our custom utilities are available for use in our unit and scenario definitions. Trying to load scenario resources in the wrong order is a common cause of problems when writing campaigns. If for some reason you need to load things in a different order to make your campaign work, adjust the warning accordingly.


{@campaigns/Example_Campaign/utils}

This line loads all the campaign macros and utilities.


[+units]
  {@campaigns/Example_Campaign/units}
[/units]

These lines load all the custom units for the campaign.


{@campaigns/Example_Campagn/scenarios}

And this line ensures that Wesnoth can load the next scenario when the previous one is completed.


#endif

The #ifdef at the start of section 2 is a special multi-line instruction which must be closed using an #endif tag.


3. utils.cfg

Next you need /CAMPAIGN_NAME/utils/utils.cfg: (remember, this is in /home/(your username)/.wesnoth/data/campaigns/ (under linux), NOT /usr/local/share/wesnoth/data/campaigns!!!)

This is also the place to add any other macros you make, either in their own files, or in this one. The just have to be in the utils/ folder you told wesnoth about :)

# A useful macro to make listing your maps easier.
# Usage: map={MAP scenario1_map}
#define MAP MAP_NAME
map_data="{@campaigns/CAMPAIGN_NAME/maps/{MAP_NAME}}"
#enddef

# This is a macro that will trigger on the death of your heroes (if you want one)
#define DEATHS
[event]## Copy for each of the heroes
name=die
  [filter]
  description= ## the description of the hero unit e.g. "konrad"
  [/filter]
  [message]
  description= ## the description of the hero unit e.g. "konrad"
  message= _ "" ## what you want them to say.
  [/message]
  [endlevel]
  result=defeat ## Hero dying = loss.
  [/endlevel]
[/event]
#enddef

4. Scenarios

Note: this template refers to macros in the template utils.cfg shown above.

[scenario]
name= _ ""
id=
next_scenario=
{MAP }
turns=
  {MORNING}
  {AFTERNOON}
  {DUSK}
  {FIRST_WATCH}
  {SECOND_WATCH}
  {DAWN}
victory_when_enemies_defeated=yes
disallow_recall=no
  [story]
    [part]
    background=
      {DOT }
      {CROSS }
    [/part]
  [/story]
  [side]## Copy for allies
  side=1
  controller=human
  fog=no
  shroud=no
  team_name=good

  description=
  type=

  canrecruit=yes
  recruit=
  [/side]
  [side]## Copy for enemies
  side=2
  team_name=enemy
  description=
  type=
  canrecruit=yes
  recruit=
  {GOLD }
  [/side]
  {DEATHS}
  [event]
  name=start
    [recall]
    description=
    [/recall]
    [message]
    description=
    message= _ ""
    [/message]
    [objectives]
    side=1
      [objective]
      description= _ ""
      condition=win
      [/objective]
      [objective]
      description= _ "Death of "
      condition=lose
      [/objective]
      [objective]
      description= _ "Death of "
      condition=lose
      [/objective]
      [objective]
      description= _ "Turns run out"
      condition=lose
      [/objective]
    [/objectives]
  [/event]
  [event]## Copy for events
  name=
    [filter]
    [/filter]
    [message]## Copy for messages
    description=
    message= _ ""
    [/message]
  [/event]
[/scenario]

5. Units

[unit]
id=
name= _ ""
image=
race=
hitpoints=
movement_type=
movement=
alignment=
ability=null
experience=500
advanceto=null
level=
cost=
usage=## AI usage: values are 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'
unit_description= _ ""
get_hit_sound=groan.wav
  [attack]
  name= _ ""
  type=
  damage=
  number=
  special=null
    [frame]
    begin=-100
    end=100
    image=
    [/frame]
    [sound]
    time=-200
    sound=
    [/sound]
  [/attack]
  [attack]
  name= _ ""
  type=
  range=long
  damage=
  number=
  special=null
    [sound]
    time=-200
    sound=
    [/sound]
    [missile_frame]
    begin=-100
    end=0
    image=
    image_diagonal=
    [/missile_frame]
  [/attack]
[/unit]

See Also