ScenarioWML - Revision history

Soliton: /* The [scenario] tag */

2025-02-25T12:10:21Z

‎The [scenario] tag

Laela: /* The [multiplayer] tag */ fix example of more specific lock setting

2023-12-10T21:34:08Z

‎The [multiplayer] tag: fix example of more specific lock setting

Celtic Minstrel: /* The [scenario] tag */ document include_file binary_path behaviour

2023-07-23T15:44:09Z

‎The [scenario] tag: document include_file binary_path behaviour

Celtic Minstrel: /* The [scenario] tag */ document include_file

2023-07-23T14:15:08Z

‎The [scenario] tag: document include_file

Soliton: /* The [scenario] tag */ This feature should not be used and will be removed at some point.

2023-07-20T18:39:31Z

‎The [scenario] tag: This feature should not be used and will be removed at some point.

Octalot: /* The [test] tag */ Remove mention of macros, as their availability is based on the file inclusion order

2023-07-05T10:26:06Z

‎The [test] tag: Remove mention of macros, as their availability is based on the file inclusion order

Octalot: /* The [test] tag */ Link to TestWML

2023-07-05T10:19:03Z

‎The [test] tag: Link to TestWML

Celtic Minstrel: Delete common keys and tags documented in AddonsWML

2023-03-26T18:13:06Z

Delete common keys and tags documented in AddonsWML

Celtic Minstrel: Delete references to the [tutorial] tag

2023-03-26T18:03:30Z

Delete references to the [tutorial] tag

Celtic Minstrel: That header is pointless, go away

2023-03-26T18:02:42Z

That header is pointless, go away

@@ Line 22: / Line 22: @@
 The following keys and tags are recognized in '''[scenario]''' tags, in addition to all the common [[AddonsWML|addon module keys and tags]]:
 * '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.
 * '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.

@@ Line 66: / Line 66: @@
 The following keys and subtags are additionally recognized in '''[multiplayer]''' scenarios:
-* '''force_lock_settings''': provides a default value for [[SideWML]] ''lock'' attributes and forces the "Use map settings" to be checked and disabled. This is useful if author wants to limit game customization in order to keep the scenario/campaign balanced. Individual options can still be enabled if this key is set to '''yes'''. E.g. color selection can be enabled by explicitly setting ''color_lock=yes'' in [[SideWML]].
+* '''force_lock_settings''': provides a default value for [[SideWML]] ''lock'' attributes and forces the "Use map settings" to be checked and disabled. This is useful if author wants to limit game customization in order to keep the scenario/campaign balanced. Individual options can still be enabled if this key is set to '''yes'''. E.g. color selection can be enabled by explicitly setting ''color_lock=no'' in [[SideWML]].
 * '''new_game_title''': if provided will be used instead of '''name''' for campaign entry points.
 * '''allow_new_game''': (default=yes) allow/prevent the scenario to be listed in the game configuration screen. This is intended for multiplayer campaigns with multiple entry points.

@@ Line 26: / Line 26: @@
 * '''map_file''': {{DevFeature1.14|3}} path to a file containing Wesnoth map data. This is the recommended way to reference a map in a scenario. The version number 1.14.3 is not a typo; it was included but buggy in earlier 1.14.x releases.
 ** {{DevFeature1.15|3}} the file can be found via [binary_path], as documented for [[DirectActionsWML#.5Breplace_map.5D|[replace_map]]].
-* '''include_file''': {{DevFeature1.17|19}} path to a WML file; the contents of this file is merged into the scenario tag. This can be used for scenario files created by the map editor prior to version 1.17.19, for example.
+* '''include_file''': {{DevFeature1.17|19}} path to a WML file; the contents of this file is merged into the scenario tag. This can be used for scenario files created by the map editor prior to version 1.17.19, for example. As with '''map_file''', the binary path is searched for this file, but it looks in the ''scenarios'' directory instead of the ''maps'' directory.
 * '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit. Default value is ''-1'' on wesnoth-1.13 and ''100'' on wesnoth-1.12. See also [[EventWML]]
 * '''turn_at''': the turn to start on (default=1)

@@ Line 26: / Line 26: @@
 * '''map_file''': {{DevFeature1.14|3}} path to a file containing Wesnoth map data. This is the recommended way to reference a map in a scenario. The version number 1.14.3 is not a typo; it was included but buggy in earlier 1.14.x releases.
 ** {{DevFeature1.15|3}} the file can be found via [binary_path], as documented for [[DirectActionsWML#.5Breplace_map.5D|[replace_map]]].
 * '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit. Default value is ''-1'' on wesnoth-1.13 and ''100'' on wesnoth-1.12. See also [[EventWML]]
 * '''turn_at''': the turn to start on (default=1)

@@ Line 26: / Line 26: @@
 * '''map_file''': {{DevFeature1.14|3}} path to a file containing Wesnoth map data. This is the recommended way to reference a map in a scenario. The version number 1.14.3 is not a typo; it was included but buggy in earlier 1.14.x releases.
 ** {{DevFeature1.15|3}} the file can be found via [binary_path], as documented for [[DirectActionsWML#.5Breplace_map.5D|[replace_map]]].
 * '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit. Default value is ''-1'' on wesnoth-1.13 and ''100'' on wesnoth-1.12. See also [[EventWML]]
 * '''turn_at''': the turn to start on (default=1)

@@ Line 88: / Line 88: @@
 * '''is_unit_test''': {{DevFeature1.13|8}} If set to 'yes', this scenario will not appear in the list of test scenarios.  The list of test scenarios can be reached from the titlescreen via the Start Test Scenario hotkey.  This hotkey is not set by default.
-The tags and macros documented in [[TestWML]] are recognized when '''#ifdef TEST''' is true. It's a reasonable assumption that any '''[test]''' tag will itself be inside an '''#ifdef TEST''' conditional.
+The tags documented in [[TestWML]] are enabled by an #ifdef TEST conditional, and it's a reasonable assumption that any [test] tag will itself be inside an #ifdef TEST conditional.
 == Defining the Map ==

← Older revision		Revision as of 10:19, 5 July 2023
Line 87:		Line 87:

	* '''is_unit_test''': {{DevFeature1.13\|8}} If set to 'yes', this scenario will not appear in the list of test scenarios. The list of test scenarios can be reached from the titlescreen via the Start Test Scenario hotkey. This hotkey is not set by default.		* '''is_unit_test''': {{DevFeature1.13\|8}} If set to 'yes', this scenario will not appear in the list of test scenarios. The list of test scenarios can be reached from the titlescreen via the Start Test Scenario hotkey. This hotkey is not set by default.
		+
		+	The tags and macros documented in [[TestWML]] are recognized when '''#ifdef TEST''' is true. It's a reasonable assumption that any '''[test]''' tag will itself be inside an '''#ifdef TEST''' conditional.

	== Defining the Map ==		== Defining the Map ==

@@ Line 1: / Line 1: @@
 {{WML Tags}}
-The top level tags '''[multiplayer]''', '''[test]''', and '''[scenario]''' are all formatted the same way.
+The top level tags '''[multiplayer]''', '''[test]''', and '''[scenario]''' are [[AddonsWML|addon module]] tags that are all formatted the same way.
 The difference between these tags is the way that the scenarios they describe are accessed.
@@ Line 20: / Line 20: @@
 == The [scenario] tag ==
-The following keys and tags are recognized in '''[scenario]''' tags:
+The following keys and tags are recognized in '''[scenario]''' tags, in addition to all the common [[AddonsWML|addon module keys and tags]]:
 * '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.
 * '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.
 * '''map_file''': {{DevFeature1.14|3}} path to a file containing Wesnoth map data. This is the recommended way to reference a map in a scenario. The version number 1.14.3 is not a typo; it was included but buggy in earlier 1.14.x releases.
@@ Line 59: / Line 56: @@
 ** time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See [[DirectActionsWML]].
 * '''[side]''': describes one player. See [[SideWML]]
 * '''map_generation''': another way to generate a map. The map will be generated randomly
 ** '''default''': the default random map generator
@@ Line 65: / Line 61: @@
 * [[TerrainGraphicsWML]]: Scenarios can define custom terrain rules for the rendering of the map.
 * [[GameConfigWML#Color_Palettes|Color palettes]]
 == The [multiplayer] tag ==
@@ Line 82: / Line 76: @@
 * '''ignore_incompatible_modification''': same as ignore_incompatible_era, but for modifications.
 * '''force_modification''': a list of modification ids (id key in [modification]). The specified modifications must be enabled to play this scenario.
 * '''require_scenario''': {{DevFeature1.13|0}} In a multiplayer scenario, this indicates that the scenario file is not enough (you have custom assets like terrain or additional unit art) and other player must download the full add-on not just the scenario WML to join a game. This will also mean that the '''addon_min_version''' attribute will control the minimum version number of your add-on which is compatible with this version.
 * '''mp_village_gold''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
@@ Line 88: / Line 81: @@
 * '''mp_shroud''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
 * '''mp_fog''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
 == The [test] tag ==

@@ Line 1: / Line 1: @@
 {{WML Tags}}
-The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.
+The top level tags '''[multiplayer]''', '''[test]''', and '''[scenario]''' are all formatted the same way.
 The difference between these tags is the way that the scenarios they describe are accessed.
@@ Line 16: / Line 16: @@
 * All '''[multiplayer]''' scenarios (without ''allow_new_game=no'') are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).
 * Any '''[test]''' scenario is an initial scenario. A test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test followed by an optional scenario ID which defaults to 'test'.) {{DevFeature1.13|8}} It can also be accessed by assigning a hotkey to the "Test Scenario" command in hotkey preferences, then pressing that hotkey at the title screen. This will bring up a list of interactive test scenarios to choose from. (Automated test scenarios used for unit testing are excluded from this list but can still be run from the command-line.)
 * Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.
@@ Line 69: / Line 67: @@
 * '''[lua]''': code in Lua, to be executed before the prestart event. See [[LuaWML]]
 * '''define''': {{DevFeature1.13|0}} the scenario is preprocessed with this additional '''#define'''
 == The [multiplayer] tag ==

← Older revision		Revision as of 18:02, 26 March 2023
Line 1:		Line 1:
	{{WML Tags}}		{{WML Tags}}
−	~~== the toplevel tags [multiplayer], [test], [tutorial], [scenario] ==~~

	The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.		The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.