WML Templates

From The Battle for Wesnoth Wiki
Revision as of 22:42, 26 January 2009 by Simons Mith (talk | contribs) (Finished campaign.cfg. Units, utils, scenarios, maps still to do. And needs sanity checking.)

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