Difference between revisions of "CampaignWML"

From The Battle for Wesnoth Wiki
(The [binary_path] tag)
m (use 1.14 Template, which exists by now)
(63 intermediate revisions by 30 users not shown)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
  
Each campaign consists of several scenarios.
+
<!--
Those scenarios are described in their [[ScenarioWML|[scenario]]] tags.
 
Then, there is usually one campaign file containing information related to the whole campaign.
 
  
The [[#The_.5Btextdomain.5D_tag|[textdomain]]] tag specifies where to find translations of campaign texts.
+
Dacyn and/or Invisible Philosopher -- please be careful
 +
you don't reduce the signal-to-noise ratio on the WML pages
 +
when editing!  Eg. knowing that a tag is translatable is _important_
 +
for the 29 translations we have in progress. -- ott
  
The [[#The_.5Bbinary_data.5D_tag|[binary_data]]] tag specifies where to find campaign specific images, music and sounds; if there are any.
+
-->
  
The [[#The_.5Bcampaign.5D_tag|[campaign]]] tag contains general campaign information, that is for example:
+
This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.
  
* how campaign appears in the game campaign menu
+
==The [campaign] Tag==
* electable difficulties
 
* first scenario
 
* campaign specific credits
 
  
The [[#The_.5Babout.5D_tag|[about]]] tag in [campaign] tag is one section of campaign-specific credits.
+
The following keys and tags are recognized in '''[campaign]''' tags:
 +
* '''id''': the internal campaign identifier used to classify saved games
 +
* '''icon''': the image displayed in the campaign selection menu
 +
* '''name''': (translatable) name displayed in the campaign selection menu
 +
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign
 +
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)
 +
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
 +
* '''description_alignment''': {{DevFeature1.13|3}} The text alignment of the description. Choose between "left" (default), "center", or "right".
 +
* '''type''': campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".
 +
* '''define'''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''CAMPAIGN_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.
 +
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. Currently supported extra_defines are:
 +
<ul>
 +
;ENABLE_ARMAGEDDON_DRAKE
 +
:allows the advancement ''Inferno Drake'' -> ''Armageddon Drake''
 +
;ENABLE_DWARVISH_ARCANISTER
 +
:allows the advancement ''Dwarvish Runemaster'' -> ''Dwarvish Arcanister''
 +
;ENABLE_DWARVISH_RUNESMITH
 +
:allows the advancement ''Dwarvish Fighter'' -> ''Dwarvish Runesmith''
 +
;DISABLE_GRAND_MARSHAL
 +
:disallows the advancement ''General'' -> ''Grand Marshal''
 +
;ENABLE_ANCIENT_LICH
 +
:allows the advancement ''Lich'' -> ''Ancient Lich''
 +
;ENABLE_DEATH_KNIGHT
 +
:allows the advancement ''Revenant'' -> ''Death Knight'
 +
;ENABLE_TROLL_SHAMAN
 +
:allows the advancement ''Troll Whelp'' -> ''Troll Shaman''
 +
;ENABLE_WOLF_ADVANCEMENT
 +
:allows the advancements ''Wolf'' -> ''Great Wolf'' -> ''Direwolf''
 +
;ENABLE_NIGHTBLADE {{DevFeature1.13|0}}
 +
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''
 +
;ENABLE_PARAGON {{DevFeature1.15|1}}
 +
:allows the advancement ''Dune Blademaster'' -> ''Dune Paragon''
 +
;ENABLE_WOSE_SHAMAN {{DevFeature1.15|1}}
 +
:allows the advancement ''Wose'' -> ''Wose Shaman''
 +
</ul>
 +
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg| Macro Reference]) which check for these values to set WML keys to different values depending on difficulty.  If you use different difficulty symbols, you may need to define your own versions of these macros. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=.
 +
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=
 +
* '''[difficulty]''':  {{DevFeature1.13|2}} specifies a single campaign difficulty. The following keys are accepted:
 +
** '''define''': the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old ''difficulties'' list.
 +
** '''image''': the image to display for this difficulty in the selection menu
 +
** '''label''': a flavor label describing this difficulty. Displayed second after the image
 +
** '''description''': a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.
 +
** '''default''': whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.
 +
** '''auto_markup''': {{DevFeature1.15|0}} By default, the description is shown in small, gray text within parentheses. Setting '''auto_markup=no''' disables these, so no markup will be applied implicitly. Any markup in '''description''' will be honored regardless of this setting.
 +
* '''allow_difficulty_change''': Allows difficulty switching during an ongoing campaign. Default:yes
 +
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]
 +
* '''[options]''':  {{DevFeature1.13|1}} Allows configuration options to be displayed to  the user, see [[OptionWML]]
 +
* '''rank''': a number that determines the order of campaigns in the campaign selection menu.  Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400.  (Note: This replaces an older convention that topped out at 50.) {{DevFeature1.14|6}} a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
 +
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
 +
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.
 +
* '''year''': shortcut for specifying both '''start_year''' and '''end_year''', for campaigns that happen inside a single calendar year. Ignored if '''start_year''' is given.
 +
* '''[about]''': inserts your own credits into the game's list of credits. See below for syntax.
 +
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.
 +
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
 +
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500.
 +
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.
  
== The [textdomain] tag ==
+
The following keys are additionally recognized in multiplayer:
 +
* '''min_players''': Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.
 +
* '''max_players''': Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either '''min_players''' or 2, whichever is higher.
 +
* '''allow_era_choice''': Whether to hide era selection and use a default one when creating a game. Defaults to ''yes''.
 +
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.
  
Top-level tag; appears directly in [game].
+
== Campaign credits ==
  
Attributes:
+
The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of '''[about]''' tags inside a '''[campaign]''' tag. The '''[about]''' tag has the following keys:
* ''name'' -- symbol of text domain
+
* '''title''': (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
* ''path'' -- directory containing dictionaries
+
* '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names
 
+
* '''[entry]''': Contains information about a single contributor. Only the ''name'' key will be used in-game, the other three keys are for display on the [[Credits]] page ('''note:''' the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)
=== Text domains ===
+
** '''name''': The name of the contributor
 
+
** '''comment''': Optional short note about what that person did
All texts in game are written in English.
+
** '''email''': Optional email address
For displaying texts in other languages there are dictionary files: English to another language.
+
** '''wikiuser''': Optional, the user name on the wiki
(Dictionary source files have extension "po", compiled dictionaries have extension "mo".)
 
To make translating and translation maintenance easier, all texts in the game are divided to groups called text domains.
 
There is one dictionary per text domain per language.
 
Each campaign is a separate text domain; that is each campaign has its translations in its own files, one per language.
 
 
 
The ''name'' attribute specifies the name of dictionary files.
 
It should begin by "wesnoth-" followed by the name of campaign.
 
For example if the name of campaign is "My Campaign", the text domain name is "wesnoth-My_Campaign".
 
When a WML tag includes preprocessor instruction "#textdomain wesnoth-My_Campaign", it means that all translated texts in this tag (and its subtags) should be found a dictionary file "wesnoth-My_Campaign.mo".
 
(All [campaign] and [scenario] tags should specify their text domain.)
 
 
 
The ''path'' attribute specifies a directory that contains dictionary files.
 
A campaign called "My Campaign" could specify a [textdomain] tag like this:
 
 
 
[textdomain]
 
  name="wesnoth-My_Campaign"
 
  path="data/campaigns/My_Campaign/translations"
 
[/textdomain]
 
 
 
All [campaign] and [scenario] tags in this campaign should start like this:
 
 
 
[campaign]
 
  #textdomain wesnoth-My_Campaign
 
 
  #...
 
 
[/campaign]
 
 
 
[scenario]
 
  #textdomain wesnoth-My_Campaign
 
 
  #...
 
 
[/scenario]
 
 
 
When the game is played in English language, all translatable texts (those preceded by "_" mark) are displayed directly.
 
When the game is played in any other language, program will try to translate the texts by dictionary whose location is determined by:
 
* the ''path'' attribute of the current text domain
 
* the language code of the current language (usually in form "xx" or "xx_XX")
 
* the ''name'' attribute of the current text domain
 
 
 
For example, if the current language is Esperanto (language code: "eo"), the dictionary will be: (on MS Windows)
 
 
 
%ProgramFiles%\Wesnoth\userdata\data\campaigns\My_Campaign\translations\eo\LC_MESSAGES\wesnoth-My_Campaign.mo
 
 
 
== The [binary_path] tag ==
 
 
 
Top-level tag; appears directly in [game].
 
 
 
Attribute:
 
 
 
* ''path'' -- directory containg campaign-specific binary data
 
 
 
=== Binary files locations ===
 
 
 
Program looks for binary files (images, music, sounds) in the subdirectories of "$data" directory, that is:
 
* images in "$data/images/"
 
* music in "$data/music/"
 
* sounds in "$data/sounds"
 
 
 
Because user-contributed files are in different place, this tag makes program find binary files also in subdirectories of directory specified in ''path'' attribute.
 
(It means that images should not be in the "''path''" directory, but in "''path''/images/" directory; music in "''path''/music/" directory; sounds in "''path''/sounds/" directory.)
 
The directory must include the final slash ("/") symbol.
 
 
 
A campaign called "My Campaign" could specify a [binary_path] tag like this:
 
 
 
[binary_path]
 
  path=data/campaigns/My_Campaign/
 
[/binary_path]
 
 
 
Now when program looks for an image called "example.png", it will try to find the image in the following locations: (on MS Windows)
 
 
 
%ProgramFiles%\Wesnoth\images\example.png
 
%ProgramFiles%\Wesnoth\userdata\data\campaigns\My_Campaign\images\example.png
 
 
 
=== Binary file conflicts ===
 
 
 
As a matter of custom, user campaigns should avoid conflicts with other image and sound files.  If a user image has the same name as another file somewhere, unpredictable results will occur in that one of the files will be used in place of the other.
 
 
 
There are two ways to avoid this: unique filenames and isolation using #ifdef.
 
 
 
The first way is to give user campaign images, sounds, and music unique filename prefixes.  For example, a opening story logo called ''main.jpg'' could exist in several campaigns.  Give it a prefix like this: ''mycampaign_main.jpg'' where mycampaign is your campaign's name.
 
 
 
The second way is to place the [binary_path] statement inside your campaign #ifdef.  The statements inside #ifdef are only loaded if someone plays your campaign.  This is the best way to do it.  The custom images and sounds you use in your campaign will not be exposed to the game until you select the campaign from the menu.
 
 
 
If there are some images you want exposed to the game, use a 2nd [binary_path] tag.  This way you will have one public binary path and one private binary path.  Since there are probably only one or two images you want to be publicly visible (like the campaign menu icon and menu image), it is much easier to place unique prefixes on these public image files.
 
 
 
Make the second [binary_path] statement outside of the #ifdef that points to another subdirectory of your campaign such as ''./external_binary_data/''.  In that directory you would need to make ''images'', ''sounds'', and ''music'' subdirectories.  See the full example below.
 
 
 
== The [campaign] tag ==
 
 
 
Top-level tag; appears directly in [game].
 
 
 
Campaign menu attributes:
 
 
 
* ''rank'' -- order of campaign in the campaign selection menu
 
* ''icon'' -- small campaign image in the campaign selection menu
 
* ''name'' -- (translatable) campaign name in the campaign selection menu
 
* ''description'' -- (translatable) campaign description in the information pane of the campaign selection menu
 
* ''image'' -- larger campaign image in the information pane of the campaign selection menu
 
 
 
Difficulty attributes:
 
 
 
* ''difficulties'' -- comma-separated list of preprocessor symbols for difficulties
 
* ''difficulty_descriptions'' -- (partially translatable) menu of difficulties
 
 
 
Preprocessor attribute:
 
 
 
* ''define'' -- preprocessor symbol for campaign
 
 
 
First scenario attribute:
 
 
 
* ''first_scenario'' -- the ID of the first scenario in the campaign
 
 
 
Campaign credits subtag:
 
 
 
* [[#The_.5Babout.5D_tag|[about]]] -- credits for campaign {{DevFeature}}
 
 
 
Obsolete attributes: (do not use them)
 
 
 
* ''id'' -- the internationalization key for the campaign
 
 
 
=== Campaign selection menu ===
 
 
 
Campaign selection menu displays a list of mainline and user-contributed campaigns.
 
Campaigns are ordered by their ''rank'' attribute (lower to higher, unranked in the end).
 
Mainline campaigns use multiples of 10 from 10 to 50.
 
Your campaign's rank should be at least 51; but you do not have to specify it.
 
 
 
In the left part of dialog the ''icon'' and ''name'' of campaign are displayed.
 
When user selects a campaign, the ''description'' and ''image'' are displayed in the right part.
 
For example if [campaign] tag looks like this:
 
 
 
[campaign]
 
 
  icon=small.png
 
  name= _"My Campaign"
 
  description= _"Hero goes somewhere and does something."
 
  image=large.png
 
 
  #...
 
 
[/campaign]
 
 
 
Then the campaign selection menu will look like this:
 
 
 
+------------------------------+---------------------+
 
| Select a campaign:          |                    |
 
| [.....] Heir to the Throne  | Hero goes somewhere |
 
| [.....] Son of the Black Eye | and does something. |
 
| [.....] Eastern Invasion    |    [ large ]      |
 
| [.....] The Rise of Wesnoth  |    [  .png ]      |
 
| [small] My Campaign          |                [OK] |
 
+------------------------------+---------------------+
 
 
 
=== Difficulty menu ===
 
 
 
From campaign author's view, "difficulty" is a preprocessor symbol, which can be used in scenario script to make gameplay easier or harder.
 
This is typically done by making difficulty-dependent turn limits, starting gold for enemies, recruiting lists for enemies, AI commands,... but it can be anything.
 
Exactly one of difficulty symbols is defined during campaign.
 
 
 
Using difficulties in campaign in optional.
 
It is recommend to use standard symbols "EASY", "NORMAL", "HARD", because a few standard macros use them (file "utils.cfg"; see [[UtilWML]]).
 
The ''difficulties'' attribute is a comma-separated list of preprocessor symbols to be defined.
 
These symbols are used internally, and are never displayed to player.
 
(It means that campaign author can use the symbols "EASY", "NORMAL", "HARD", even if the selection box displays different names, e.g. "Hard", "Very hard", "Nightmare".)
 
The ''difficulty_descriptions'' is a formatted string that is best created using macros "MENU_IMG_TXT" and "MENU_IMG_TXT2" like this:
 
 
 
[campaign]
 
 
  #...
 
 
  difficulties=EASY,NORMAL,HARD
 
  difficulty_descriptions= {MENU_IMG_TXT2 elvish-fighter.png  _"Fighter"  _"(easiest)"} + ";"
 
                    + "*" + {MENU_IMG_TXT  elvish-hero.png    _"Hero"                } + ";"
 
                          + {MENU_IMG_TXT2 elvish-champion.png _"Champion" _"(hardest)"}
 
 
  #...
 
 
[/campaign]
 
 
 
The semicolon ";" separates items in menu, and the asterisk "*" specifies the default value (see [[DescriptionWML]]).
 
Number of rows in ''difficulty_descriptions'' must be the same as number of symbols in ''difficulties''.
 
The difficulty menu will look like this:
 
 
 
+-------------------------------+
 
| Choose a difficulty:          |
 
| [fighter.] Fighter  (easiest) |
 
| [hero.png] Hero              |
 
| [champion] Champion (hardest) |
 
+-------------------------------+
 
 
 
=== Campaign symbol ===
 
 
 
Each campaign must define a unique preprocessor symbol, to make program run efficiently (load data faster and use less memory).
 
This symbol is used to include campaign-specific WML files, that is scenario files and campaign-specific macros.
 
If you do not care about technical details, skip the following paragraph.
 
 
 
WML files include each other; starting with "$data/game.cfg" which includes some files that also include some files... and so on, up to all the units, campaigns, etc.
 
There are hundreds of WML files which must be read and parsed; they consume a lot of memory and make program start slowly.
 
To reduce this amount, scenario files are ''not'' loaded at the start of program; their inclusion is prevented by "#ifdef" preprocessor commands (see [[PreprocessorRef]]).
 
When starting a campaign (or loading a saved game from campaign), the campaign-specific preprocessor symbol is defined, and WML files are reloaded... now including also scenario files from the current campaign (but not from other campaigns).
 
Each campaign must define a unique preprocessor symbol, and conditionally include its campaign-specific files, to support this process.
 
Without it, the campaign would work anyway, but its files would consume memory also when not necessary, e.g. when playing some other campaign.
 
 
 
The ''define'' attribute must contain a unique preprocessor symbol.
 
It should start with "CAMPAIGN_" followed by the name of campaign.
 
For example if your campaign is called "My Campaign", you should write:
 
 
 
[campaign]
 
 
  #...
 
 
  define=CAMPAIGN_MY_CAMPAIGN
 
 
  #...
 
 
[/campaign]
 
 
 
Then, you have to use this symbol at the end of campaign WML file (after the end of [campaign] tag) to include campaign-specific files (e.g. scenarios) like this:
 
 
 
#ifdef CAMPAIGN_MY_CAMPAIGN
 
{@campaigns/My_Campaign/scenarios}
 
#endif
 
 
 
Only the tags [binary_path] and [campaign] should go outside the "#ifdef" section.
 
 
 
=== Selecting first scenario ===
 
 
 
Attribute ''first_scenario'' specifies which scenario should be started first.
 
Its value must be the same as the value of "id" attribute of the [[ScenarioWML|[scenario]]] tag for given scenario.
 
For example your campaign can contain:
 
 
 
[campaign]
 
 
  #...
 
 
  first_scenario=My_first_scenario
 
 
  #...
 
 
[/campaign]
 
 
 
And the corresponding scenario would contain:
 
 
 
[scenario]
 
 
  id=My_first_scenario
 
 
  #...
 
 
[/scenario]
 
 
 
Please note that the "id" attribute of the [scenario] tag does not have to be the same as the name of scenario file.
 
Attribute ''first_scenario'' refers to the "id" attribute of the [scenario] tag, ''not'' to the filename.
 
(However, you should include all scenario files in your campaign file; read the previous section.)
 
 
 
All scenarios must have unique IDs.
 
(That is: unique in scope of their campaign.
 
Because scenarios from different campaigns are never loaded together in memory.)
 
 
 
Campaign tag only specifies the first scenario of the campaign.
 
Then, each scenario specifies which one will follow.
 
 
 
== The [about] tag ==
 
 
 
{{DevFeature}}
 
 
 
Appears in [campaign] tag.
 
 
 
Attributes:
 
* ''title'' -- (translatable) title of credits section
 
* ''text'' -- names of campaign contributors
 
 
 
=== Campaign specific credits ===
 
 
 
A campaign can specify its own credits.
 
These will be included in the game credits; in the bottom if player has not completed this campaign, in the top if player has completed this campaign.
 
 
 
There can be any number of [about] tags inside a [campaign] tag.
 
Campaign-specific credits are preceded by the name of campaign.
 
Each [about] tag contains one section of credits.
 
Section title is in ''title'' attribute; it must be one of the following values:
 
* "Campaign Designer"
 
* "Current Maintainer"
 
* "Artwork and Graphics Designers"
 
* "Music"
 
* "Miscellaneous"
 
 
 
The ''text'' attribute contains the names of contributors, each on separate line.
 
Example:
 
 
 
#textdomain wesnoth
 
[about]
 
  title= _"Campaign Designer"
 
  text="Name Surname (nickname)"
 
[/about]
 
[about]
 
  title= _"Artwork and Graphics Designers"
 
  text="Artist One
 
Artist Two"
 
[/about]
 
 
 
Related forum thread: [http://www.wesnoth.org/forum/viewtopic.php?t=9720 9720].
 
 
 
== A complete example ==
 
 
 
This is a campaign file for campaign "My Campaign"; the file path is "$userdata/campaigns/My_Campaign.cfg".
 
 
 
# This is a main campaign file of campaign "My Campaign".
 
 
[textdomain]
 
  name="wesnoth-My_Campaign"
 
  path="data/campaigns/My_Campaign/translations"
 
[/textdomain]
 
 
[binary_path]
 
  path=data/campaigns/My_Campaign/
 
[/binary_path]
 
 
[campaign]
 
  #textdomain wesnoth-My_Campaign
 
 
  icon=small.png
 
  name= _"My Campaign"
 
  description= _"Hero goes somewhere and does something."
 
  image=large.png
 
 
 
  difficulties=EASY,NORMAL,HARD
 
  difficulty_descriptions= {MENU_IMG_TXT2 elvish-fighter.png  _"Fighter"  _"(easiest)"} + ";"
 
                    + "*" + {MENU_IMG_TXT  elvish-hero.png    _"Hero"                } + ";"
 
                          + {MENU_IMG_TXT2 elvish-champion.png _"Champion" _"(hardest)"}
 
 
  define=CAMPAIGN_MY_CAMPAIGN
 
 
  first_scenario=My_first_scenario
 
 
  # DEVELOPMENT BRANCH ONLY...
 
 
  #textdomain wesnoth
 
  [about]
 
    title= _"Campaign Designer"
 
    text="Name Surname (nickname)"
 
  [/about]
 
  [about]
 
    title= _"Artwork and Graphics Designers"
 
    text="Artist One
 
Artist Two"
 
  [/about]
 
 
  # ...DEVELOPMENT BRANCH ONLY
 
 
[/campaign]
 
 
#ifdef CAMPAIGN_MY_CAMPAIGN
 
 
  [+units]
 
    {@campaigns/My_Campaign/units}
 
  [/units]
 
 
  {@campaigns/My_Campaign/scenarios}
 
 
#endif
 
  
 
== See Also ==
 
== See Also ==
Line 400: Line 94:
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 
* [[PblWML]]
 
* [[PblWML]]
 +
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 03:23, 20 January 2020

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, credits_group, criteria;

D:

damage, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, found_item, for, foreach, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;


This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.

The [campaign] Tag

The following keys and tags are recognized in [campaign] tags:

  • id: the internal campaign identifier used to classify saved games
  • icon: the image displayed in the campaign selection menu
  • name: (translatable) name displayed in the campaign selection menu
  • abbrev: (translatable) abbreviation used as a prefix for savefile names made from this campaign
  • image: the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)
  • description: (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
  • description_alignment: (Version 1.13.3 and later only) The text alignment of the description. Choose between "left" (default), "center", or "right".
  • type: campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".
  • define=CAMPAIGN_SYMBOL when this campaign is started, the preprocessor symbol CAMPAIGN_SYMBOL will be defined. See #ifdef in PreprocessorRef for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags [campaign] and [binary_path] (see BinaryPathWML) should go outside of #ifdef CAMPAIGN_SYMBOL. This symbol will be defined before any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the #ifdef CAMPAIGN_SYMBOL block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.
  • extra_defines: a comma(,) separated list of preprocessor symbols. Those symbols will be defined before any .cfg is preprocessed. Currently supported extra_defines are:
    ENABLE_ARMAGEDDON_DRAKE
    allows the advancement Inferno Drake -> Armageddon Drake
    ENABLE_DWARVISH_ARCANISTER
    allows the advancement Dwarvish Runemaster -> Dwarvish Arcanister
    ENABLE_DWARVISH_RUNESMITH
    allows the advancement Dwarvish Fighter -> Dwarvish Runesmith
    DISABLE_GRAND_MARSHAL
    disallows the advancement General -> Grand Marshal
    ENABLE_ANCIENT_LICH
    allows the advancement Lich -> Ancient Lich
    ENABLE_DEATH_KNIGHT
    allows the advancement Revenant -> Death Knight'
    ENABLE_TROLL_SHAMAN
    allows the advancement Troll Whelp -> Troll Shaman
    ENABLE_WOLF_ADVANCEMENT
    allows the advancements Wolf -> Great Wolf -> Direwolf
    ENABLE_NIGHTBLADE (Version 1.13.0 and later only)
    allows the advancement Orcish Slayer -> Orcish Nightblade
    ENABLE_PARAGON (Version 1.15.1 and later only)
    allows the advancement Dune Blademaster -> Dune Paragon
    ENABLE_WOSE_SHAMAN (Version 1.15.1 and later only)
    allows the advancement Wose -> Wose Shaman
  • difficulties: a comma(,) separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols EASY, NORMAL, and HARD are usually used, and there are several macros in utils.cfg (see Macro Reference) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros. (Version 1.13.2 and later only) This key has been deprecated in favor of [difficulty] define=.
  • difficulty_descriptions: the menu of difficulties; this is a list of descriptions (see DescriptionWML) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the difficulties list. (Version 1.13.2 and later only) This key has been deprecated in favor of [difficulty] define=
  • [difficulty]: (Version 1.13.2 and later only) specifies a single campaign difficulty. The following keys are accepted:
    • define: the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old difficulties list.
    • image: the image to display for this difficulty in the selection menu
    • label: a flavor label describing this difficulty. Displayed second after the image
    • description: a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.
    • default: whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.
    • auto_markup: (Version 1.15.0 and later only) By default, the description is shown in small, gray text within parentheses. Setting auto_markup=no disables these, so no markup will be applied implicitly. Any markup in description will be honored regardless of this setting.
  • allow_difficulty_change: Allows difficulty switching during an ongoing campaign. Default:yes
  • first_scenario: the ID of the first scenario in the campaign; see id in ScenarioWML
  • [options]: (Version 1.13.1 and later only) Allows configuration options to be displayed to the user, see OptionWML
  • rank: a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.) (Version 1.14.6 and later only) a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
  • start_year: a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example 20 BW, 20 YW, 20 BF or 20 AF. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
  • end_year: a string that helps determine the order of campaigns when two campaigns have the same start_year. Ignored if start_year is not set.
  • year: shortcut for specifying both start_year and end_year, for campaigns that happen inside a single calendar year. Ignored if start_year is given.
  • [about]: inserts your own credits into the game's list of credits. See below for syntax.
  • end_credits: Whether to display the credits screen at the end of the campaign. Defaults to yes.
  • end_text: (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
  • end_text_duration: Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time end_text is displayed on screen. Defaults to 3500.
  • [event]: (Version 1.13.2 and later only) events placed here will be automatically inserted into all scenarios of the campaign.

The following keys are additionally recognized in multiplayer:

  • min_players: Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.
  • max_players: Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either min_players or 2, whichever is higher.
  • allow_era_choice: Whether to hide era selection and use a default one when creating a game. Defaults to yes.
  • require_campaign: Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.

Campaign credits

The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of [about] tags inside a [campaign] tag. The [about] tag has the following keys:

  • title: (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
  • text: (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names
  • [entry]: Contains information about a single contributor. Only the name key will be used in-game, the other three keys are for display on the Credits page (note: the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)
    • name: The name of the contributor
    • comment: Optional short note about what that person did
    • email: Optional email address
    • wikiuser: Optional, the user name on the wiki

See Also