Difference between revisions of "BuildingCampaignsTheCampaignFile"

From The Battle for Wesnoth Wiki
(Added description of abbrev key.)
(The Final Result: Update for CAMPAIGN_DIFFICULTY macro)
 
(17 intermediate revisions by 10 users not shown)
Line 1: Line 1:
Each campaign must contain a WML file which contains a [campaign] tag. In order for the campaign to be translatable, it must also contain a [textdomain] tag, which should precede the [campaign] tag.
+
Inside the campaign folder, each campaign must contain a WML file (usually named _main.cfg) which contains a [campaign] tag. In order for the campaign to be translatable, it must also contain a [textdomain] tag, which should precede the [campaign] tag.
  
This file contains the information the game needs to find the rest of the bits of your campaign scattered in other files and put them together to have a playable campaign.  Much information about this file can be found in the [[CampaignWML]] entry.  What follows is a description of each line of the campaign file and an explanation of what it does.
+
This file contains the information the game needs to find the rest of the bits of your campaign scattered in other files and put them together to have a playable campaign.  Much more technical information about this file can be found in the [[CampaignWML]] entry.  What follows is a beginner-oriented description of each line of the campaign file and an explanation of what it does.
  
For our purposes I'll assume we've already created a campaign called simple_campaign with the directory structure outlined in [[BuildingCampaignsDirectoryStructure]].
+
For our purposes I'll assume we've already created a campaign called simple_campaign with the directory structure outlined in [[AddonStructure]].
 +
 
 +
==Step 1: The Text Domain==
 +
 
 +
The first line of the campaign file is the [textdomain] WML tag, which specifies where the game should look for translations to the strings in the campaign. The textdomain tag specifies a name for the textdomain, which is what is used in the [campaign] tag, and is used in campaign scenarios to connect the strings with translations. The textdomain should be the campaign's directory's name prefixed with "wesnoth-", to ensure that it does not conflict with other textdomains that might be specified on a given system and is compatible with [[WesCamp]].
  
The first line of the campaign file is the [textdomain] WML tag, which specifies where the game should look for translations to the strings in the campaign. The textdomain tag specifies a name for the textdomain, which is what is used in the [campaign] tag, and in f ex campaign scenarios to connect the strings with translations. The textdomain should be unique, and start with 'wesnoth-', to ensure that it does not conflict with other textdomains that might be specified on a given system.
 
 
The textdomain also specifies a path to the directory where the compiled translation files will be stored. This should be a file inside the campaign directory.
 
The textdomain also specifies a path to the directory where the compiled translation files will be stored. This should be a file inside the campaign directory.
  
Ex.
+
Example:
 
     [textdomain]
 
     [textdomain]
 
           name="wesnoth-Simple_Campaign"
 
           name="wesnoth-Simple_Campaign"
           path="data/campaigns/simple_campaign/translations"
+
           path="data/add-ons/Simple_Campaign/translations"
 
     [/textdomain]
 
     [/textdomain]
  
  
 +
==Step 2: The [campaign] Tag==
 +
Now we add the opening [campaign] WML tag that lets the game know this is a campaign:
  
Then follows the [campaign] WML tag that lets the game know this is a campaign:
+
    [campaign]
  
    [campaign]
+
==Step 3: Associating the Campaign with the Text Domain==
  
First associate the campaign with the textdomain you have just defined:
+
Next we must associate the campaign with the textdomain you have just defined:
 
     #textdomain wesnoth-Simple_Campaign
 
     #textdomain wesnoth-Simple_Campaign
 +
 +
==Step 4: The Campaign ''id'', ''name'', ''abbrev'' and ''define'' Keys==
  
 
The next group of lines uniquely identifies the campaign:
 
The next group of lines uniquely identifies the campaign:
  
 +
    id=CAMPAIGN_ID
 
     name= _ "A Simple Campaign"
 
     name= _ "A Simple Campaign"
     abbrev=ASC
+
     abbrev= _ "ASC"
 
     define=CAMPAIGN_SIMPLE_CAMPAIGN
 
     define=CAMPAIGN_SIMPLE_CAMPAIGN
  
[In earlier version, there was also ''id'' which was a unique identifier used for translation, but now has no effect.]
+
''id'' is the unique indentifier of the campaign. ''name'' is the name of your campaign that the user will see. The value of ''name'' must be in quotation marks and be preceded by an underscore to facilitate translation into other languages. ''abbrev'' defines a campaign abbreviation that will be used as a prefix for the names of save files from that campaign; its value should also be in quotation marks and preceded by an underscore. ''define'' creates a key that lets the game know when a user has selected to play a scenario from your campaign.  We'll discuss the ''define'' key in more detail in a bit.  Note that if you are missing the ''name'' or ''define'' keys, your campaign will not work correctly. ''abbrev'' is optional but recommended.
  
''name'' is the name of your campaign that the user will see.  It must be in quotation marks and be preceded by an underscore to facilitate translation. 
+
==Step 5: The Campaign Icon, Image, and Description==
''abbrev'' defines a campaign abbreviation that will be used as a prefix for the names of save files from that campaign (in 1.3.12 and later). ''define'' creates a key that lets the game know when a user has selected to play a scenario from your campaign.  More on it in a bit.  If you are missing the ''name'' or ''define'' keys of these your campaign will not work correctly; ''abbrev'' is optioal but recommended. 
 
  
 
The next group gives the user information about your campaign when he selects it from the campaign menu:
 
The next group gives the user information about your campaign when he selects it from the campaign menu:
Line 40: Line 47:
 
     description= _ "Some text about my campaign!"
 
     description= _ "Some text about my campaign!"
  
''icon'' is a reference to any of the standard Wesnoth images.  It will be displayed in the campaign selection menu. When appropriate, it should use [[ImagePathFunctionWML]] to give the icon a team color instead of magenta. ''image'' is an image that will be displayed when a user clicks on the campaign. ''description'' is a text description that will be shown to the user at the same time as ''image''. Note that none of these three are strictly necessary, but they do make your campaign look nice and professional.
+
''icon'' is a reference to any of the standard Wesnoth images.  It will be displayed in the campaign selection menu. When appropriate, it should use [[ImagePathFunctionWML]] to give the icon a team color instead of magenta. ''image'' is an image that will be displayed when a user clicks on the campaign. ''description'' is a text description that will be shown to the user at the same time as ''image''. Note that none of these three are strictly necessary, but they do make your campaign look nice and professional.
  
    difficulties=EASY,NORMAL,HARD
+
==Step 6: The Campaign Difficulties==
    difficulty_descriptions={MENU_IMG_TXT2 *&units/human-loyalists/peasant.png~TC(1,magenta) _"Civilian" _"(trivial)"} +
 
    ";" + {MENU_IMG_TXT2 units/human-loyalists/spearman.png~TC(1,magenta) _"Soldier" _"(simple)"} +
 
    ";" + {MENU_IMG_TXT2 units/human-loyalists/pikeman.png~TC(1,magenta) _"Veteran" _"(easy)"}
 
  
''difficulties'' creates three definitions for three different difficulty levels. For more information on difficulty levels and balancing see [[BuildingCampaignsBalancing]].
+
Use the ''CAMPAIGN_DIFFICULTY'' and ''DEFAULT_DIFFICULTY'' macros to let the player choose the difficulty. It's usual to have 3 difficulties, and in the WML to refer to them as EASY, NORMAL and HARD. For more information on difficulty levels and balancing see [[http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design HOWTO]].
  
    first_scenario=the_first_scenario
+
    {CAMPAIGN_DIFFICULTY EASY  "units/human-peasants/peasant.png~RC(magenta>red)" ( _ "Civilian") ( _ "Beginner")}
 +
    {CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/spearman.png~RC(magenta>red)" ( _ "Soldier") ( _ "Normal")} {DEFAULT_DIFFICULTY}
 +
    {CAMPAIGN_DIFFICULTY HARD  "units/human-loyalists/pikeman.png~RC(magenta>red)" ( _ "Veteran") ( _ "Challenging")}
 +
 
 +
==Step 7: The Campaign's First Scenario==
  
 
''first_scenario'' is a reference to the scenario ''id'' of the scenario that you intend to be loaded and played first.
 
''first_scenario'' is a reference to the scenario ''id'' of the scenario that you intend to be loaded and played first.
 
This line is essential.  Note that while you are debugging and testing your campaign, it's often useful to change this line to the scenario you're working on so you don't have to play through all
 
This line is essential.  Note that while you are debugging and testing your campaign, it's often useful to change this line to the scenario you're working on so you don't have to play through all
 
the scenarios that come before it.  (You could also just play through your campaign saving at each level.)
 
the scenarios that come before it.  (You could also just play through your campaign saving at each level.)
 +
 +
    first_scenario=the_first_scenario
 +
 +
==Step 8: The Closing [campaign] Tag==
 +
 +
The first_scenario key is the last thing that needs to be in the [campaign] tag, so now it's time to close the [campaign] tagset by writing the closing [campaign] tag (which is exactly the same as the opening [campaign] tag except for the forward slash immediately after the first bracket):
  
 
     [/campaign]
 
     [/campaign]
  
That's all that needs to be in the [campaign] tag, so we can close it here.
+
==Step 9: Including Directories==
  
There's more we want to do, though:  we've got to tell Wesnoth where our various
+
There's more we want to do, though:  we've got to tell Wesnoth where our various
 
additional files are located (i.e. our maps, scenarios, units, images, and sounds).
 
additional files are located (i.e. our maps, scenarios, units, images, and sounds).
  
You should put everything not in the [campaign] tag inside
+
You should put everything that does not belong in the [campaign] tag inside
 
   #ifdef CAMPAIGN_SIMPLE_CAMPAIGN
 
   #ifdef CAMPAIGN_SIMPLE_CAMPAIGN
 
   ...
 
   ...
Line 68: Line 82:
 
so that your custom macros, WML code, and inclusion of files do not affect other campaigns and slow the game down.  The only exception to this is the [binary_path] tag specifying the path to custom images in your campaign, but you should only put this outside the #ifdef if you need custom images for the campaign selection menu and the difficulty selection menu.  Otherwise even this belongs inside the #ifdef.
 
so that your custom macros, WML code, and inclusion of files do not affect other campaigns and slow the game down.  The only exception to this is the [binary_path] tag specifying the path to custom images in your campaign, but you should only put this outside the #ifdef if you need custom images for the campaign selection menu and the difficulty selection menu.  Otherwise even this belongs inside the #ifdef.
  
A fairly minimal #ifdef section might just contain a link to your scenarios.
+
A fairly minimal #ifdef section might just contain a link to your "scenarios" and your "maps" folders.
  
 
  #ifdef CAMPAIGN_SIMPLE_CAMPAIGN
 
  #ifdef CAMPAIGN_SIMPLE_CAMPAIGN
 
   
 
   
  {@campaigns/simple_campaign/scenarios}
+
  {~add-ons/Simple_Campaign/scenarios}
 +
{~add-ons/Simple_Campaign/maps}
 
   
 
   
 
  #endif
 
  #endif
  
The {@campaigns/simple_campaign/scenarios} line just looks in your campaign's "scenarios" directory and parses any .cfg files it finds there (see [[BuildingScenarios]] for information on making your scenario files). If you have any other .cfg files (macros, custom terrains, etc.), you can link them in a similar way. If you want to use custom units however, you will have to link them from inside a [+units] tag (using the "+" adds them to wesnoth's stored units - this is important) like so:
+
The {~add-ons/simple_campaign/scenarios} line just looks in your campaign's "scenarios" directory and parses any .cfg files it finds there (see [[BuildingScenarios]] for information on making your scenario files). If you have any other .cfg files (macros, custom terrains, etc.), you can link them in a similar way.
 +
 
 +
===Adding the Unit Directory===
 +
There is one special case when adding direcories, however: adding custom units. If you want to use custom units, you will have to link them from inside a [+units] tag (using the "+" adds them to wesnoth's stored units - this is important) like so:
 +
 
 +
    [+units]
 +
        {~add-ons/Simple_Campaign/units}
 +
    [/units]
 +
 
 +
This syntax applies only to including new units; if you need to include any other folder (macros, music, etc.), all you need to write is the one directory line, without any special tags.
 +
Note that you should only include lines to directories that actually exist in your campaign folder, otherwise you will get a nasty error when you try to play your campaign. So if you don't have a "macros" folder in your campaign folder, don't include a path in the _main.cfg to that non-existant folder!
 +
 
 +
==The Final Result==
  
 +
So once you're finished, the entire contents of _main.cfg should resemble this:
 +
 +
[textdomain]
 +
    name="wesnoth-Simple_Campaign"
 +
    path="data/add-ons/Simple_Campaign/translations"
 +
[/textdomain]
 +
   
 +
[campaign]
 +
      #textdomain wesnoth-Simple_Campaign
 +
   
 +
      id=CAMPAIGN_ID
 +
      name= _ "A Simple Campaign"
 +
      abbrev= _ "ASC"
 +
      define=CAMPAIGN_SIMPLE_CAMPAIGN
 +
   
 +
      icon=a_wesnoth_icon.png
 +
      image= simple_campaign_logo.png
 +
      description= _ "Some text about my campaign!"
 +
   
 +
      {CAMPAIGN_DIFFICULTY EASY  "units/human-peasants/peasant.png~RC(magenta>red)" ( _ "Civilian") ( _ "Beginner")}
 +
      {CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/spearman.png~RC(magenta>red)" ( _ "Soldier") ( _ "Normal")} {DEFAULT_DIFFICULTY}
 +
      {CAMPAIGN_DIFFICULTY HARD  "units/human-loyalists/pikeman.png~RC(magenta>red)" ( _ "Veteran") ( _ "Challenging")}
 +
   
 +
      first_scenario=the_first_scenario
 +
   
 +
[/campaign]
 +
   
 +
#ifdef CAMPAIGN_SIMPLE_CAMPAIGN
 +
   
 +
{~add-ons/Simple_Campaign/scenarios}
 +
{~add-ons/Simple_Campaign/maps}
 +
 
  [+units]
 
  [+units]
{@campaigns/simple_campaign/units}
+
    {~add-ons/Simple_Campaign/units}
 
  [/units]
 
  [/units]
 +
 
 +
#endif
 +
 +
 +
For more information, see the [[CampaignWML]] page.
  
 
== Next: ==
 
== Next: ==
* [[BuildingCampaignsThePBLFile]]
+
* [[PblWML]]
  
 
== See Also ==
 
== See Also ==
  
* [[BuildingCampaignsDirectoryStructure]]
+
* [[AddonStructure]]
 
* [[BuildingCampaigns]]
 
* [[BuildingCampaigns]]
 +
 +
[[Category:Create]]

Latest revision as of 20:00, 25 December 2018

Inside the campaign folder, each campaign must contain a WML file (usually named _main.cfg) which contains a [campaign] tag. In order for the campaign to be translatable, it must also contain a [textdomain] tag, which should precede the [campaign] tag.

This file contains the information the game needs to find the rest of the bits of your campaign scattered in other files and put them together to have a playable campaign. Much more technical information about this file can be found in the CampaignWML entry. What follows is a beginner-oriented description of each line of the campaign file and an explanation of what it does.

For our purposes I'll assume we've already created a campaign called simple_campaign with the directory structure outlined in AddonStructure.

Step 1: The Text Domain

The first line of the campaign file is the [textdomain] WML tag, which specifies where the game should look for translations to the strings in the campaign. The textdomain tag specifies a name for the textdomain, which is what is used in the [campaign] tag, and is used in campaign scenarios to connect the strings with translations. The textdomain should be the campaign's directory's name prefixed with "wesnoth-", to ensure that it does not conflict with other textdomains that might be specified on a given system and is compatible with WesCamp.

The textdomain also specifies a path to the directory where the compiled translation files will be stored. This should be a file inside the campaign directory.

Example:

    [textdomain]
         name="wesnoth-Simple_Campaign"
         path="data/add-ons/Simple_Campaign/translations"
    [/textdomain]


Step 2: The [campaign] Tag

Now we add the opening [campaign] WML tag that lets the game know this is a campaign:

    [campaign]

Step 3: Associating the Campaign with the Text Domain

Next we must associate the campaign with the textdomain you have just defined:

    #textdomain wesnoth-Simple_Campaign

Step 4: The Campaign id, name, abbrev and define Keys

The next group of lines uniquely identifies the campaign:

    id=CAMPAIGN_ID
    name= _ "A Simple Campaign"
    abbrev= _ "ASC"
    define=CAMPAIGN_SIMPLE_CAMPAIGN

id is the unique indentifier of the campaign. name is the name of your campaign that the user will see. The value of name must be in quotation marks and be preceded by an underscore to facilitate translation into other languages. abbrev defines a campaign abbreviation that will be used as a prefix for the names of save files from that campaign; its value should also be in quotation marks and preceded by an underscore. define creates a key that lets the game know when a user has selected to play a scenario from your campaign. We'll discuss the define key in more detail in a bit. Note that if you are missing the name or define keys, your campaign will not work correctly. abbrev is optional but recommended.

Step 5: The Campaign Icon, Image, and Description

The next group gives the user information about your campaign when he selects it from the campaign menu:

    icon=a_wesnoth_icon.png
    image= simple_campaign_logo.png
    description= _ "Some text about my campaign!"

icon is a reference to any of the standard Wesnoth images. It will be displayed in the campaign selection menu. When appropriate, it should use ImagePathFunctionWML to give the icon a team color instead of magenta. image is an image that will be displayed when a user clicks on the campaign. description is a text description that will be shown to the user at the same time as image. Note that none of these three are strictly necessary, but they do make your campaign look nice and professional.

Step 6: The Campaign Difficulties

Use the CAMPAIGN_DIFFICULTY and DEFAULT_DIFFICULTY macros to let the player choose the difficulty. It's usual to have 3 difficulties, and in the WML to refer to them as EASY, NORMAL and HARD. For more information on difficulty levels and balancing see [Campaign Design HOWTO].

   {CAMPAIGN_DIFFICULTY EASY   "units/human-peasants/peasant.png~RC(magenta>red)" ( _ "Civilian") ( _ "Beginner")}
   {CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/spearman.png~RC(magenta>red)" ( _ "Soldier") ( _ "Normal")} {DEFAULT_DIFFICULTY}
   {CAMPAIGN_DIFFICULTY HARD   "units/human-loyalists/pikeman.png~RC(magenta>red)" ( _ "Veteran") ( _ "Challenging")}

Step 7: The Campaign's First Scenario

first_scenario is a reference to the scenario id of the scenario that you intend to be loaded and played first. This line is essential. Note that while you are debugging and testing your campaign, it's often useful to change this line to the scenario you're working on so you don't have to play through all the scenarios that come before it. (You could also just play through your campaign saving at each level.)

    first_scenario=the_first_scenario

Step 8: The Closing [campaign] Tag

The first_scenario key is the last thing that needs to be in the [campaign] tag, so now it's time to close the [campaign] tagset by writing the closing [campaign] tag (which is exactly the same as the opening [campaign] tag except for the forward slash immediately after the first bracket):

    [/campaign]

Step 9: Including Directories

There's more we want to do, though: we've got to tell Wesnoth where our various additional files are located (i.e. our maps, scenarios, units, images, and sounds).

You should put everything that does not belong in the [campaign] tag inside

 #ifdef CAMPAIGN_SIMPLE_CAMPAIGN
 ...
 #endif

so that your custom macros, WML code, and inclusion of files do not affect other campaigns and slow the game down. The only exception to this is the [binary_path] tag specifying the path to custom images in your campaign, but you should only put this outside the #ifdef if you need custom images for the campaign selection menu and the difficulty selection menu. Otherwise even this belongs inside the #ifdef.

A fairly minimal #ifdef section might just contain a link to your "scenarios" and your "maps" folders.

#ifdef CAMPAIGN_SIMPLE_CAMPAIGN

{~add-ons/Simple_Campaign/scenarios}
{~add-ons/Simple_Campaign/maps}

#endif

The {~add-ons/simple_campaign/scenarios} line just looks in your campaign's "scenarios" directory and parses any .cfg files it finds there (see BuildingScenarios for information on making your scenario files). If you have any other .cfg files (macros, custom terrains, etc.), you can link them in a similar way.

Adding the Unit Directory

There is one special case when adding direcories, however: adding custom units. If you want to use custom units, you will have to link them from inside a [+units] tag (using the "+" adds them to wesnoth's stored units - this is important) like so:

   [+units]
       {~add-ons/Simple_Campaign/units}
   [/units]

This syntax applies only to including new units; if you need to include any other folder (macros, music, etc.), all you need to write is the one directory line, without any special tags. Note that you should only include lines to directories that actually exist in your campaign folder, otherwise you will get a nasty error when you try to play your campaign. So if you don't have a "macros" folder in your campaign folder, don't include a path in the _main.cfg to that non-existant folder!

The Final Result

So once you're finished, the entire contents of _main.cfg should resemble this:

[textdomain]
    name="wesnoth-Simple_Campaign"
    path="data/add-ons/Simple_Campaign/translations"
[/textdomain]
   
[campaign]
     #textdomain wesnoth-Simple_Campaign
    
     id=CAMPAIGN_ID
     name= _ "A Simple Campaign"
     abbrev= _ "ASC"
     define=CAMPAIGN_SIMPLE_CAMPAIGN
   
     icon=a_wesnoth_icon.png
     image= simple_campaign_logo.png
     description= _ "Some text about my campaign!"
    
     {CAMPAIGN_DIFFICULTY EASY   "units/human-peasants/peasant.png~RC(magenta>red)" ( _ "Civilian") ( _ "Beginner")}
     {CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/spearman.png~RC(magenta>red)" ( _ "Soldier") ( _ "Normal")} {DEFAULT_DIFFICULTY}
     {CAMPAIGN_DIFFICULTY HARD   "units/human-loyalists/pikeman.png~RC(magenta>red)" ( _ "Veteran") ( _ "Challenging")}
   
     first_scenario=the_first_scenario
    
[/campaign]
    
#ifdef CAMPAIGN_SIMPLE_CAMPAIGN
    
{~add-ons/Simple_Campaign/scenarios}
{~add-ons/Simple_Campaign/maps}

[+units]
    {~add-ons/Simple_Campaign/units}
[/units]
 
#endif


For more information, see the CampaignWML page.

Next:

See Also

This page was last edited on 25 December 2018, at 20:00.