Difference between revisions of "WML Templates"

From The Battle for Wesnoth Wiki
m
(Clarifications, tidying, some rewording. Unfinished. Will continue 26/01/09. Revert on 28/01 if I don't get back to it...)
Line 5: Line 5:
 
== Campaigns ==
 
== Campaigns ==
  
For your basic campaign, you will need the following .cfg files in the correct locations. Replace all occurances of CAMPAIGN_NAME with the name of your campaign. THE NAMES MUST BE ''EXACTLY'' as shown otherwise for everything to work.<br>
+
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 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). Infact it is best to never edit any of those files.<br>
+
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>
  
 
To make a campaign, you will need the following:
 
To make a campaign, you will need the following:
Line 14: Line 14:
 
*A scenario folder: /CAMPAIGN_NAME/scenarios/
 
*A scenario folder: /CAMPAIGN_NAME/scenarios/
 
*At least one scenario file: /CAMPAIGN_NAME/scenarios/SCENARIO_NAME.cfg
 
*At least one scenario file: /CAMPAIGN_NAME/scenarios/SCENARIO_NAME.cfg
*A maps folder:    /CAPMAIGN_NAME/maps/
+
*A maps folder:    /CAMPAIGN_NAME/maps/
 
*As many maps as scenarios (covered elsewhere)
 
*As many maps as scenarios (covered elsewhere)
  
Line 22: Line 22:
 
*And a utilities (macros) folder: /CAMPAIGN_NAME/utils/
 
*And a utilities (macros) folder: /CAMPAIGN_NAME/utils/
  
It is important that you place parts of your campaign in the right places and that the folders are named correctly, as 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 ===
 
=== _main.cfg, the campaign file ===
Line 32: Line 32:
 
* (## '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' 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!"
 
* (## 'easy'/'normal'/'hard' description) with a very brief description of the difficulty e.g. "For Newbies", "Normal", "Significant Challenge!"
* Follow the insturction in the comments.
+
* Follow the instructions in the comments.
  
 
  [campaign]
 
  [campaign]
Line 41: Line 41:
 
  define=CAMPAIGN_NAME
 
  define=CAMPAIGN_NAME
 
  # Put the id of the first scenario here eg START_SCENARIO. As long as it is in the /scenarios/ folder,
 
  # 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)
+
  # Wesnoth will find it. (it does not have to have the same filename, but it helps)
 
  first_scenario=
 
  first_scenario=
 
  difficulties=EASY,NORMAL,HARD
 
  difficulties=EASY,NORMAL,HARD
Line 53: Line 53:
 
  " _"(hardest)"}
 
  " _"(hardest)"}
  
  # icon is not needed, it just is seen on the campaign selection screen.
+
  # icon is optional. If you provide an icon, this will be the campaign icon seen on the campaign selection screen.
 
  icon=
 
  icon=
 
  # The decription is the 'story' that the user will see when they click on the campaign.
 
  # The decription is the 'story' that the user will see when they click on the campaign.
 
  description= _ ""
 
  description= _ ""
 
  # This is the image that the user will see next to the description. Remember, all images
 
  # 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 wesnoths image folder. (so if your image
+
  # 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 go "image1.png" or whatever.)
+
  # is directly in your image folder, you can just use "image1.png" or whatever.)
 
  image=
 
  image=
 
  [/campaign]
 
  [/campaign]
 
   
 
   
 
  #-----------------second part of campaign file----------------------------------------
 
  #-----------------second part of campaign file----------------------------------------
  # That is all that should go between the campaign tags. Remember that define=CAMPAIGN_NAME
+
  # That is all that should go between the campaign tags. Remember the line "define=CAMPAIGN_NAME"?
  # key? When wesnoth starts up, it reads all the campaign files. So that it doesn't load
+
  # This sets up the ''campaign name key''. When Wesnoth starts up, it reads all the campaign files.
  # ALL the images, macros, units etc from all the campaigns in (which would take a long
+
# So that it doesn't load
  # time and might cause errors), wesnoth only reads between the campaign tags.
+
  # ''all'' the images, macros, units etc from all available campaigns (which would take a long
  # When a campaign is selected by the player, wesnoth will 'define' whatever the define key
+
  # time and might cause errors), when Wesnoth first starts it only reads the data stored between campaign tags.
  # said to. At that point, any # ifdef code (without the space) found by wesnoth that matches
+
  # 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. :)
# that key will be run. And that is what the following is for. :)
 
 
   
 
   
 
  #ifdef CAMPAIGN_NAME
 
  #ifdef CAMPAIGN_NAME
 
   
 
   
  # this adds any units you have created for your campaign to wesnoth's pool of units it knows
+
  # this adds any custom units you have created for your campaign to Wesnoth's pool of units it knows
 
  # about.
 
  # about.
 
  [+units]
 
  [+units]
 
         # remember, you are listing the path to the folder, not individual files.
 
         # remember, you are listing the path to the folder, not individual files.
{@campaigns/CAMPAIGN_NAME/units}
+
        {@campaigns/CAMPAIGN_NAME/units}
 
  [/units]
 
  [/units]
  # this [binary_path] tag tells wesnoth where the images/, units/, scenarios/, maps/ and utils/
+
 +
  # the [binary_path] tag tells wesnoth where the images/, units/, scenarios/, maps/ and utils/
 
  # folders are.
 
  # folders are.
 
  [binary_path]
 
  [binary_path]
Line 106: Line 106:
 
  [event]## Copy for each of the heroes
 
  [event]## Copy for each of the heroes
 
  name=die
 
  name=die
[filter]
+
  [filter]
description= ## the description of the hero unit e.g. "konrad"
+
  description= ## the description of the hero unit e.g. "konrad"
[/filter]
+
  [/filter]
[message]
+
  [message]
description= ## the description of the hero unit e.g. "konrad"
+
  description= ## the description of the hero unit e.g. "konrad"
message= _ "" ## what you want them to say.
+
  message= _ "" ## what you want them to say.
[/message]
+
  [/message]
[endlevel]
+
  [endlevel]
result=defeat ## Hero dieing = loss.
+
  result=defeat ## Hero dying = loss.
[/endlevel]
+
  [/endlevel]
 
  [/event]
 
  [/event]
 
  #enddef
 
  #enddef
Line 129: Line 129:
 
  {MAP }
 
  {MAP }
 
  turns=
 
  turns=
{MORNING}
+
  {MORNING}
{AFTERNOON}
+
  {AFTERNOON}
{DUSK}
+
  {DUSK}
{FIRST_WATCH}
+
  {FIRST_WATCH}
{SECOND_WATCH}
+
  {SECOND_WATCH}
{DAWN}
+
  {DAWN}
  
 
  victory_when_enemies_defeated=yes
 
  victory_when_enemies_defeated=yes
 
  disallow_recall=no
 
  disallow_recall=no
[story]
+
  [story]
[part]
+
    [part]
background=
+
    background=
{DOT }
+
      {DOT }
{CROSS }
+
      {CROSS }
[/part]
+
    [/part]
[/story]
+
  [/story]
[side]## Copy for allies
+
  [side]## Copy for allies
side=1
+
  side=1
controller=human
+
  controller=human
fog=no
+
  fog=no
shroud=no
+
  shroud=no
team_name=good
+
  team_name=good
+
description=
+
  description=
type=
+
  type=
+
 
  canrecruit=yes
 
  canrecruit=yes
 
  recruit=
 
  recruit=

Revision as of 01:09, 26 January 2009

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