WML Templates

From The Battle for Wesnoth Wiki
Revision as of 01:09, 26 January 2009 by Simons Mith (talk | contribs) (Clarifications, tidying, some rewording. Unfinished. Will continue 26/01/09. Revert on 28/01 if I don't get back to it...)

These templates are bases for campaigns, scenarios, and units; fill in the blanks to create one. Knowledge of WML is recommended to use these templates; see ReferenceWML.

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.

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.

To make a campaign, you will need the following:

  • 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:

  • A units folder: /CAMPAIGN_NAME/units/
  • An images folder: /CAMPAIGN_NAME/images/
  • And a utilities (macros) folder: /CAMPAIGN_NAME/utils/

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. 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!) 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]
# The name= tag is the name that the user will see on the campaign screen.
name= _ ""
id=CAMPAIGN_NAME
# This define key is important, keep reading and you will see why.
define=CAMPAIGN_NAME
# 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
# Do the replacing here as listed above
difficulty_descriptions={MENU_IMG_TXT2 ## 'easy' icon
_"## 'easy' description
" _"(easiest)"} + ";" + {MENU_IMG_TXT ## 'normal' icon
_"## 'normal' description
"} + ";" + {MENU_IMG_TXT2 ## 'hard' icon
_"## 'hard' description
" _"(hardest)"}
# 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]

#-----------------second part of campaign file----------------------------------------
# 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.
# So that it doesn't load
# all the images, macros, units etc from all available campaigns (which would take a long
# 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. :)

#ifdef CAMPAIGN_NAME

# this adds any custom units you have created for your campaign to Wesnoth's pool of units it knows
# about.
[+units]
       # remember, you are listing the path to the folder, not individual files.
       {@campaigns/CAMPAIGN_NAME/units}
[/units]

# the [binary_path] tag tells wesnoth where the images/, units/, scenarios/, maps/ and utils/
# folders are.
[binary_path]
   path=data/campaigns/CAMPAIGN_NAME
[/binary_path]

# This tells wesnoth to include any .cfg files it find in these folders.
{@campaigns/CAMPAIGN_NAME/utils}
{@campaigns/CAMPAIGN_NAME/scenarios}
#endif

Basic 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 heros (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

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]

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