CampaignWML - Revision history

Celtic Minstrel: /* The [campaign] Tag */ Add an anchor that can be linked to

2024-02-25T01:47:56Z

‎The [campaign] Tag: Add an anchor that can be linked to

Soliton: /* The [campaign] Tag */ mention difficulty order

2024-02-23T16:41:39Z

‎The [campaign] Tag: mention difficulty order

Soliton: /* The [campaign] Tag */

2024-02-23T16:39:41Z

‎The [campaign] Tag

Celtic Minstrel: Delete common keys and tags documented in AddonsWML

2023-03-26T17:54:45Z

Delete common keys and tags documented in AddonsWML

Toranks at 20:20, 3 February 2023

2023-02-03T20:20:32Z

Beetlenaut: /* The [campaign] Tag */

2022-09-13T18:27:05Z

‎The [campaign] Tag

Beetlenaut: /* Removed key */

2022-09-13T18:16:36Z

‎Removed key

Beetlenaut: /* The [campaign] Tag */

2022-09-12T14:28:31Z

‎The [campaign] Tag

Jarom at 19:42, 14 November 2021

2021-11-14T19:42:51Z

Shadowm: Update links to macro-reference.html

2021-08-24T08:11:18Z

Update links to macro-reference.html

@@ Line 24: / Line 24: @@
 * '''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 [https://www.wesnoth.org/macro-reference.html#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] description=
-* '''[difficulty]''':  {{DevFeature1.13|2}} specifies a single campaign difficulty. The difficulties are expected to be ordered from easiest to hardest. The following keys are accepted:
+* {{anchor|difficulty|'''[difficulty]'''}}:  {{DevFeature1.13|2}} specifies a single campaign difficulty. The difficulties are expected to be ordered from easiest to hardest. 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

@@ Line 24: / Line 24: @@
 * '''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 [https://www.wesnoth.org/macro-reference.html#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] description=
-* '''[difficulty]''':  {{DevFeature1.13|2}} specifies a single campaign difficulty. The following keys are accepted:
+* '''[difficulty]''':  {{DevFeature1.13|2}} specifies a single campaign difficulty. The difficulties are expected to be ordered from easiest to hardest. 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

@@ Line 23: / Line 23: @@
 * '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. (In the past, this tag was used to define common optional advancements, but that use is deprecated. There are now macros to add those advancements defined in [https://www.wesnoth.org/macro-reference.html#file:optional_unit_advancements.cfg data/core/macros/optional_unit_advancements.cfg].)
 * '''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 [https://www.wesnoth.org/macro-reference.html#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_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] description=
 * '''[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.

@@ Line 14: / Line 14: @@
 ==The [campaign] Tag==
-The following keys and tags are recognized in '''[campaign]''' tags:
+The following keys and tags are recognized in '''[campaign]''' tags, in addition to all the common [[AddonsWML|addon module keys and tags]]:
 * '''icon''': the image 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)
 * '''background''': {{DevFeature1.15|9}} the image used as a backdrop for the Campaigns menu (typically a high resolution image intended for displaying fullscreen in story screens). If blank or unspecified, a stock story background from core is used.
 * '''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".
 * '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. (In the past, this tag was used to define common optional advancements, but that use is deprecated. There are now macros to add those advancements defined in [https://www.wesnoth.org/macro-reference.html#file:optional_unit_advancements.cfg data/core/macros/optional_unit_advancements.cfg].)
 * '''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 [https://www.wesnoth.org/macro-reference.html#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=.
@@ Line 37: / Line 33: @@
 * '''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]]
 * '''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.
@@ Line 46: / Line 41: @@
 * '''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. {{DevFeature1.15|6}} This value is capped at 5000 (5 seconds).
 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.

@@ Line 24: / Line 24: @@
 * '''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.
+* '''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]''', '''[textdomain]''' 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. (In the past, this tag was used to define common optional advancements, but that use is deprecated. There are now macros to add those advancements defined in [https://www.wesnoth.org/macro-reference.html#file:optional_unit_advancements.cfg data/core/macros/optional_unit_advancements.cfg].)
 * '''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 [https://www.wesnoth.org/macro-reference.html#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=.

@@ Line 53: / Line 53: @@
 * '''allow_era_choice''': Whether to allow era selection (when set to ''yes'') or hide it and use a default one when creating a game (when set to ''no''). 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'.
 == See Also ==