ScenarioWML - Revision history

Soliton: /* The [scenario] tag */

2025-02-25T12:10:21Z

The [scenario] tag

← Older revision		Revision as of 12:10, 25 February 2025
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]]:		The following keys and tags are recognized in '''[scenario]''' tags, in addition to all the common [[AddonsWML\|addon module keys and tags]]:

			* '''id''': The id of this scenario. Can be referenced in '''next_scenario''' of another scenario.
	* '''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.		* '''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_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.

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

← Older revision		Revision as of 21:34, 10 December 2023
Line 66:		Line 66:
	The following keys and subtags are additionally recognized in '''[multiplayer]''' scenarios:		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.		* '''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.		* '''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.

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

← Older revision		Revision as of 15:44, 23 July 2023
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.		* '''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]]].		** {{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]]		* '''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)		* '''turn_at''': the turn to start on (default=1)

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

2023-07-23T14:15:08Z

The [scenario] tag: document include_file

← Older revision		Revision as of 14:15, 23 July 2023
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.		* '''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]]].		** {{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.
	* '''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]]		* '''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)		* '''turn_at''': the turn to start on (default=1)

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.

← Older revision		Revision as of 18:39, 20 July 2023
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.		* '''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]]].		** {{DevFeature1.15\|3}} the file can be found via [binary_path], as documented for [[DirectActionsWML#.5Breplace_map.5D\|[replace_map]]].
	** {{DevFeature1.15\|4}} the file can be a WML file with the contents of a '''[scenario]''' tag, which will be merged in to the current scenario. For example, the map file can include named '''[time_area]'''s. There's more detail in PR #4999.
	* '''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]]		* '''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)		* '''turn_at''': the turn to start on (default=1)

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

← Older revision		Revision as of 10:26, 5 July 2023
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.		* '''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 ==		== Defining the Map ==

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

2023-07-05T10:19:03Z

The [test] tag: Link to TestWML

← 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 ==

Celtic Minstrel: Delete common keys and tags documented in AddonsWML

2023-03-26T18:13:06Z

Delete common keys and tags documented in AddonsWML

← Older revision		Revision as of 18:13, 26 March 2023
Line 1:		Line 1:
	{{WML Tags}}		{{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.		The difference between these tags is the way that the scenarios they describe are accessed.

Line 20:		Line 20:
	== The [scenario] tag ==		== 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]]:

	* '''id''': A unique identifier for this scenario. All scenarios must have an id. Can't clash with '''id''' used in '''[multiplayer]''' 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.		* '''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.
	* '''description''': (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen.
	* '''name''': (translatable) is shown in several places in the level, including the intro screen. It is also the default name for saves on the level.
	* '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.		* '''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.		* '''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]].		** 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]]		* '''[side]''': describes one player. See [[SideWML]]
	* '''[event]''': describes an event that may be triggered at a certain point of the scenario. See [[EventWML]]
	* '''map_generation''': another way to generate a map. The map will be generated randomly		* '''map_generation''': another way to generate a map. The map will be generated randomly
	** '''default''': the default random map generator		** '''default''': the default random map generator
Line 65:		Line 61:
	* [[TerrainGraphicsWML]]: Scenarios can define custom terrain rules for the rendering of the map.		* [[TerrainGraphicsWML]]: Scenarios can define custom terrain rules for the rendering of the map.
	* [[GameConfigWML#Color_Palettes\|Color palettes]]		* [[GameConfigWML#Color_Palettes\|Color palettes]]
	* '''[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 ==		== The [multiplayer] tag ==
Line 82:		Line 76:
	* '''ignore_incompatible_modification''': same as ignore_incompatible_era, but for modifications.		* '''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.		* '''force_modification''': a list of modification ids (id key in [modification]). The specified modifications must be enabled to play this scenario.
	* '''[options]''': custom options. See [[OptionWML]] for details.
	* '''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.		* '''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]'''		* '''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_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]'''		* '''mp_fog''': {{DevFeature1.13\|9}} default value for the corresponding attribute in '''[side]'''
	* '''define''': {{DevFeature1.13\|0}} the scenario is preprocessed with this additional '''#define'''

	== The [test] tag ==		== The [test] tag ==

Celtic Minstrel: Delete references to the [tutorial] tag

2023-03-26T18:03:30Z

Delete references to the [tutorial] tag

← Older revision		Revision as of 18:03, 26 March 2023
Line 1:		Line 1:
	{{WML Tags}}		{{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.		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).		* 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 '''[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.)
	* The '''[tutorial]''' scenario with the attribute '''id=tutorial''' is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.
	** {{DevFeature1.15\|3}} the tutorial's scenarios now use '''[scenario]''' instead of tutorial '''[tutorial]'''.
	* 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.		* 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]]		* '''[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'''		* '''define''': {{DevFeature1.13\|0}} the scenario is preprocessed with this additional '''#define'''

	~~== The [tutorial] tag ==~~

	~~The only difference between '''[tutorial]''' and '''[scenario]''' is the name of the tag. They are not interchangeable because the C++ code looks for the specific tag name.~~

	~~{{DevFeature1.15\|3}} Tutorial scenarios use '''[scenario]''', and that's the tag name the C++ code looks for. There is no '''[tutorial]''' tag any more.~~

	== The [multiplayer] tag ==		== The [multiplayer] tag ==

Celtic Minstrel: That header is pointless, go away

2023-03-26T18:02:42Z

That header is pointless, go away

← 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.