IntroWML - Revision history

Bssarkar: /* Main text keys */ add more info to text_layout

2025-10-26T02:23:03Z

Main text keys: add more info to text_layout

← Older revision		Revision as of 02:23, 26 October 2025
Line 19:		Line 19:
	* '''story''': (translatable) the text to display below the image.		* '''story''': (translatable) the text to display below the image.
	* '''text_alignment''': specifies the alignment of the story text. It must be one of ''left'' (default), ''center'' or ''right''.		* '''text_alignment''': specifies the alignment of the story text. It must be one of ''left'' (default), ''center'' or ''right''.
	* '''text_layout''': specifies the vertical portion of the screen where the story text will be displayed. It must be one of ''top'', ''middle'' or ''bottom'' (default).		* '''text_layout''': specifies the vertical portion of the screen where the story panel with the story text will be displayed. It must be one of ''top'', ''middle'' or ''bottom'' (default). This includes the Next/Previous/Skip button.

	=== Title text keys ===		=== Title text keys ===

Bssarkar: /* Title text keys */ title_position: add more info.

2025-10-26T02:17:16Z

Title text keys: title_position: add more info.

← Older revision		Revision as of 02:17, 26 October 2025
Line 26:		Line 26:
	* '''title''': specifies a custom title to display instead of the name of the scenario. If specified, it implies '''show_title=yes'''. If parent the '''[story]''' is used through [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]] with '''show_title=yes''', the '''title''' key must be explicitly specified as it does not default to the scenario title and leads to a missing title error if omitted.		* '''title''': specifies a custom title to display instead of the name of the scenario. If specified, it implies '''show_title=yes'''. If parent the '''[story]''' is used through [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]] with '''show_title=yes''', the '''title''' key must be explicitly specified as it does not default to the scenario title and leads to a missing title error if omitted.
	* '''title_alignment''': specifies the alignment of the title box. It must be one of ''left'' (default), ''center'' or ''right''.		* '''title_alignment''': specifies the alignment of the title box. It must be one of ''left'' (default), ''center'' or ''right''.
	* '''title_position''': {{DevFeature1.19\|17}} specifies the position of the title text. Can be a pair of string positions separated by comma, like ''left,top'', where the first is the horizontal position and the second is the vertical position or the special single value ''centered''. The allowed horizontal and vertical position values are:		* '''title_position''': {{DevFeature1.19\|17}} specifies the position of the title text. Can be a pair of string positions separated by comma, like ''left,top'', where the first is the horizontal position and the second is the vertical position or any one of the positions, like ''left'' or the special single value ''centered''. If a single position is specified, like ''title_position=left'', the other is assumed to be the default. ''title_position=centered'' is equivalent to ''title_position=center,middle''. If the vertical position is the same that of the ''text_layout'' key, title text's position will be changed internally to a more suitable location to avoid overlap. The allowed horizontal and vertical position values are:
	** horizontal: ''left'', ''center'', ''right''		** horizontal: ''left'' (default), ''center'', ''right''
	** vertical: ''top'', ''middle'', ''bottom''		** vertical: ''top'' (default), ''middle'', ''bottom''
	~~''title_position=centered'' is equivalent to ''title_position=center,middle''.~~

	=== Image and sound keys ===		=== Image and sound keys ===

Bssarkar: Add title_position key (PR 10621)

2025-10-26T02:12:59Z

Add title_position key (PR 10621)

← Older revision		Revision as of 02:12, 26 October 2025
Line 26:		Line 26:
	* '''title''': specifies a custom title to display instead of the name of the scenario. If specified, it implies '''show_title=yes'''. If parent the '''[story]''' is used through [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]] with '''show_title=yes''', the '''title''' key must be explicitly specified as it does not default to the scenario title and leads to a missing title error if omitted.		* '''title''': specifies a custom title to display instead of the name of the scenario. If specified, it implies '''show_title=yes'''. If parent the '''[story]''' is used through [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]] with '''show_title=yes''', the '''title''' key must be explicitly specified as it does not default to the scenario title and leads to a missing title error if omitted.
	* '''title_alignment''': specifies the alignment of the title box. It must be one of ''left'' (default), ''center'' or ''right''.		* '''title_alignment''': specifies the alignment of the title box. It must be one of ''left'' (default), ''center'' or ''right''.
			* '''title_position''': {{DevFeature1.19\|17}} specifies the position of the title text. Can be a pair of string positions separated by comma, like ''left,top'', where the first is the horizontal position and the second is the vertical position or the special single value ''centered''. The allowed horizontal and vertical position values are:
			** horizontal: ''left'', ''center'', ''right''
			** vertical: ''top'', ''middle'', ''bottom''
			''title_position=centered'' is equivalent to ''title_position=center,middle''.

	=== Image and sound keys ===		=== Image and sound keys ===

Shadowm: linkies

2024-03-06T04:37:17Z

linkies

← Older revision		Revision as of 04:37, 6 March 2024
Line 3:		Line 3:
	The '''[story]''' tag is a series of images and text to display as the first part of the intro screen. It can appear in [[ScenarioWML]] or {{DevFeature1.13\|8}} as [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]].		The '''[story]''' tag is a series of images and text to display as the first part of the intro screen. It can appear in [[ScenarioWML]] or {{DevFeature1.13\|8}} as [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]].

	The '''[deprecated_message]''', '''[wml_message]''', and '''[insert_tag]''' tags are allowed beneath '''[story]'''. Most other WML tags will not be recognized in this context. Note, however, that messages produced by the first two tags will not appear in the game interface until the actual game map appears.		The [[InterfaceActionsWML#.5Bdeprecated_message.5D\|'''[deprecated_message]''']], [[InterfaceActionsWML#.5Bwml_message.5D\|'''[wml_message]''']], and [[VariablesWML#.5Binsert_tag.5D\|'''[insert_tag]''']] tags are allowed beneath '''[story]'''. Most other WML tags will not be recognized in this context. Note, however, that messages produced by the first two tags will not appear in the game interface until the actual game map appears.

	The only other tags currently recognized within '''[story]''' and '''[part]''' are '''[if]'''/'''[then]'''/'''[else]''' ({{DevFeature1.13\|0}}: also '''[elseif]''') and '''[switch]'''/'''[case]'''. These can be used to show parts conditionally on the values of variables.		The only other tags currently recognized within '''[story]''' and '''[part]''' are [[ConditionalActionsWML#.5Bif.5D\|'''[if]'''/'''[then]'''/'''[else]''']] ({{DevFeature1.13\|0}}: also [[ConditionalActionsWML#.5Bif.5D\|'''[elseif]''']]) and [[ConditionalActionsWML#.5Bswitch.5D\|'''[switch]'''/'''[case]''']]. These can be used to show parts conditionally on the values of variables.

	See also the journey and battle macros, in the [https://www.wesnoth.org/macro-reference.html#file:image-utils.cfg Macro Reference]		See also the journey and battle macros, in the [https://www.wesnoth.org/macro-reference.html#file:image-utils.cfg Macro Reference]

Shadowm: [image] has never been a direct descendant of [story]

2024-03-06T04:33:50Z

[image] has never been a direct descendant of [story]

← Older revision		Revision as of 04:33, 6 March 2024
Line 3:		Line 3:
	The '''[story]''' tag is a series of images and text to display as the first part of the intro screen. It can appear in [[ScenarioWML]] or {{DevFeature1.13\|8}} as [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]].		The '''[story]''' tag is a series of images and text to display as the first part of the intro screen. It can appear in [[ScenarioWML]] or {{DevFeature1.13\|8}} as [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]].

	The '''[deprecated_message]''', '''[wml_message~~]''', '''[image~~]''', and '''[insert_tag]''' tags are allowed beneath '''[story]'''. Most other WML tags will not be recognized in this context. Note, however, that messages produced by the first two tags will not appear in the game interface until the actual game map appears.		The '''[deprecated_message]''', '''[wml_message]''', and '''[insert_tag]''' tags are allowed beneath '''[story]'''. Most other WML tags will not be recognized in this context. Note, however, that messages produced by the first two tags will not appear in the game interface until the actual game map appears.

	The only other tags currently recognized within '''[story]''' and '''[part]''' are '''[if]'''/'''[then]'''/'''[else]''' ({{DevFeature1.13\|0}}: also '''[elseif]''') and '''[switch]'''/'''[case]'''. These can be used to show parts conditionally on the values of variables.		The only other tags currently recognized within '''[story]''' and '''[part]''' are '''[if]'''/'''[then]'''/'''[else]''' ({{DevFeature1.13\|0}}: also '''[elseif]''') and '''[switch]'''/'''[case]'''. These can be used to show parts conditionally on the values of variables.

Shadowm: /* [part] */

2024-03-06T04:28:03Z

[part]

← Older revision		Revision as of 04:28, 6 March 2024
Line 11:		Line 11:
	== [part] ==		== [part] ==

	'''[part]''' is a ~~special tag recognized only beneath~~ '''~~[story]~~'''~~. Each~~ '''[part]''' ~~represents~~ one ~~image~~ and ~~text.~~		Each '''[part]''' tag represents one "page" of a story sequence, with its own text and images. The player advances through parts by clicking on the '''Next'''/'''→''' button to advance one part, the '''Back'''/'''←''' button to go back one part, and the '''Skip''' button to leave the story sequence and start/return to the game.
	~~The part is displayed until~~ the ~~user clicks on~~ the ~~"Next>>>" button~~.

	The following ~~key~~/tags are recognized for '''[part]''':		The following keys/tags are recognized for '''[part]'''.

	=== Main text ~~options~~ ===		=== Main text keys ===

	* '''story''': (translatable) the text to display below the image.		* '''story''': (translatable) the text to display below the image.
Line 22:		Line 21:
	* '''text_layout''': specifies the vertical portion of the screen where the story text will be displayed. It must be one of ''top'', ''middle'' or ''bottom'' (default).		* '''text_layout''': specifies the vertical portion of the screen where the story text will be displayed. It must be one of ''top'', ''middle'' or ''bottom'' (default).

	=== Title text ~~options~~ ===		=== Title text keys ===

	* '''show_title''': whether to display the title of the scenario at the top		* '''show_title''': whether to display the title of the scenario at the top
Line 28:		Line 27:
	* '''title_alignment''': specifies the alignment of the title box. It must be one of ''left'' (default), ''center'' or ''right''.		* '''title_alignment''': specifies the alignment of the title box. It must be one of ''left'' (default), ''center'' or ''right''.

	=== Image and sound ~~options~~ ===		=== Image and sound keys ===

	* '''background''': the image to display. Story images are usually created specially for this purpose, except for the map.		* '''background''': the image to display. Story images are usually created specially for this purpose, except for the map.

Shadowm: Various documentation changes to reflect 1.16 and 1.18 WML better, including fixing misinformation regarding text_alignment and text_layout that was never true (my bad)

2024-03-06T04:24:03Z

Various documentation changes to reflect 1.16 and 1.18 WML better, including fixing misinformation regarding text_alignment and text_layout that was never true (my bad)

← Older revision		Revision as of 04:24, 6 March 2024
Line 1:		Line 1:
	{{WML Tags}}		{{WML Tags}}
	~~== IntroWML ==~~

	The '''[story]''' tag is a series of images and text to display as the first part of the intro screen. It can appear in [[ScenarioWML]] or {{DevFeature1.13\|8}} as [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]].		The '''[story]''' tag is a series of images and text to display as the first part of the intro screen. It can appear in [[ScenarioWML]] or {{DevFeature1.13\|8}} as [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]].
Line 10:		Line 9:
	See also the journey and battle macros, in the [https://www.wesnoth.org/macro-reference.html#file:image-utils.cfg Macro Reference]		See also the journey and battle macros, in the [https://www.wesnoth.org/macro-reference.html#file:image-utils.cfg Macro Reference]

	~~=== [story] ===~~		== [part] ==

	* '''text_layout''': specifies the area of the screen where the story text will be displayed. It allows the ''top'', ''middle'' and ''bottom'' values; the latter is used by default.
	* '''title_alignment''': specifies the alignment of the title box. It allows the ''left'', ''center'' and ''right'' values; the first is used by default.

	=== [part] ===

	'''[part]''' is a special tag recognized only beneath '''[story]'''. Each '''[part]''' represents one image and text.		'''[part]''' is a special tag recognized only beneath '''[story]'''. Each '''[part]''' represents one image and text.
Line 21:		Line 15:

	The following key/tags are recognized for '''[part]''':		The following key/tags are recognized for '''[part]''':

			=== Main text options ===

			* '''story''': (translatable) the text to display below the image.
			* '''text_alignment''': specifies the alignment of the story text. It must be one of ''left'' (default), ''center'' or ''right''.
			* '''text_layout''': specifies the vertical portion of the screen where the story text will be displayed. It must be one of ''top'', ''middle'' or ''bottom'' (default).

			=== Title text options ===

			* '''show_title''': whether to display the title of the scenario at the top
			* '''title''': specifies a custom title to display instead of the name of the scenario. If specified, it implies '''show_title=yes'''. If parent the '''[story]''' is used through [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]] with '''show_title=yes''', the '''title''' key must be explicitly specified as it does not default to the scenario title and leads to a missing title error if omitted.
			* '''title_alignment''': specifies the alignment of the title box. It must be one of ''left'' (default), ''center'' or ''right''.

			=== Image and sound options ===

	* '''background''': the image to display. Story images are usually created specially for this purpose, except for the map.		* '''background''': the image to display. Story images are usually created specially for this purpose, except for the map.
	* '''scale_background''': Whether to scale the background, default yes.		* '''scale_background''': Whether to scale the background, default yes.
	* '''story''': (translatable) the text to display below the image.
	* '''show_title''': whether to display the title of the scenario at the top
	* '''title''': specifies a custom title to display instead of the name of the scenario. If specified, it implies '''show_title=yes'''. If parent '''[story]''' is used through [[InterfaceActionsWML#.5Bstory.5D\|ActionWML]] with '''show_title=yes''', the '''title''' key must be explicitly specified, it does not default to scenario title and leads to missing-title error if omitted.
	* '''music''': change to this music		* '''music''': change to this music
	* '''sound''': a list of sound files; the engine will choose one at random and play it once while displaying the story part.		* '''sound''': a list of sound files; the engine will choose one at random and play it once while displaying the story part.
			* '''voice''': a list of sound files; the engine will choose one at random and play it on a sound channel intended for voice overs once while displaying the story part.

	=== [background_layer] ===		=== [background_layer] ===

Shadowm: Update links to macro-reference.html

2021-08-24T08:08:57Z

Update links to macro-reference.html

← Older revision		Revision as of 08:08, 24 August 2021
Line 8:		Line 8:
	The only other tags currently recognized within '''[story]''' and '''[part]''' are '''[if]'''/'''[then]'''/'''[else]''' ({{DevFeature1.13\|0}}: also '''[elseif]''') and '''[switch]'''/'''[case]'''. These can be used to show parts conditionally on the values of variables.		The only other tags currently recognized within '''[story]''' and '''[part]''' are '''[if]'''/'''[then]'''/'''[else]''' ({{DevFeature1.13\|0}}: also '''[elseif]''') and '''[switch]'''/'''[case]'''. These can be used to show parts conditionally on the values of variables.

	See also the journey and battle macros, in the [~~http~~://www.wesnoth.org/macro-reference.~~xhtml~~#file:image-utils.cfg Macro Reference]		See also the journey and battle macros, in the [https://www.wesnoth.org/macro-reference.html#file:image-utils.cfg Macro Reference]

	=== [story] ===		=== [story] ===

Octalot: /* [image] */ Add resize_with_background

2020-11-04T15:59:41Z

[image]: Add resize_with_background

← Older revision		Revision as of 15:59, 4 November 2020
Line 51:		Line 51:
	* '''file''': the image to display.		* '''file''': the image to display.
	* '''delay''': the time to delay drawing this image.		* '''delay''': the time to delay drawing this image.
			* '''resize_with_background''': {{DevFeature1.15\|7}} if "yes", apply the same scaling as applied to the '''base_layer'''

	Each image is placed using the pixels of the background_layer as the coordinate system; each image's location moves to compensate when the background image is scaled. Example: my background image is a map with a city at pixel 160,100; I put a battle marker on that city using '''x,y,centered=160,100,yes'''. When a user plays the game they will see the map enlarged to fill the window (regardless of its size), and the battle marker will still be on top of the city.		Each image is placed using the pixels of the background_layer as the coordinate system; each image's location moves to compensate when the background image is scaled. Example: my background image is a map with a city at pixel 160,100; I put a battle marker on that city using '''x,y,centered=160,100,yes'''. When a user plays the game they will see the map enlarged to fill the window (regardless of its size), and the battle marker will still be on top of the city.

Octalot: /* [image] */ Rewrite the explanation of the coordinate system

2020-10-28T15:15:21Z

[image]: Rewrite the explanation of the coordinate system

← Older revision		Revision as of 15:15, 28 October 2020
Line 47:		Line 47:
	An image to display.		An image to display.

	* '''x''', '''y''': the location ~~in pixels~~ to draw the image~~. The x~~,~~y pixel location is relative to~~ the image specified in background, but not in a normal way. The background image is scaled up or down to fill the screen resolution, but images are never scaled in size. Their coordinates, however, are scaled. It's basically a big pain in the rear. Example: I have a background image at 640x480 and an overlay at 640x480. To horizontally center the overlay on a 1024x768 screen, I want to position it at x=192. This is because 1024-640 = 384 total extra pixel space, then 384/2 = 192. This results in equal space on both sides of the overlay. However, now you have to account for the background scaling. The background image at 640 is scaled up to 1024, a scaling factor of 1.6. All image locations are also scaled up, so the overlay is not drawn at x=192, rather it is drawn at x=192*1.6 or x=307! To compensate for this, divide the desired pixel location by the scaling factor. In the example, x_compensated=192/1.6 or x_compensated=120. You can specify which background overlay you want to use as a base for the ~~coordinates. See~~ '''~~[background_layer]~~''' ~~for details~~.		* '''x''', '''y''': the location to draw the image, using the pixels of the '''base_layer''' background image as the coordinate system.
	* '''centered''': If "yes", use the center of the image when placing at the x,y coordinates, ~~which is useful since this image is not scaled like~~ the ~~background is (and by centering no need to worry about this)~~.		* '''centered''': If "yes", use the center of the image as the anchor point when placing at the x,y coordinates, if "no" then use the top-left corner.
	* '''file''': the image to display.		* '''file''': the image to display.
	* '''delay''': the time to delay drawing this image.		* '''delay''': the time to delay drawing this image.

			Each image is placed using the pixels of the background_layer as the coordinate system; each image's location moves to compensate when the background image is scaled. Example: my background image is a map with a city at pixel 160,100; I put a battle marker on that city using '''x,y,centered=160,100,yes'''. When a user plays the game they will see the map enlarged to fill the window (regardless of its size), and the battle marker will still be on top of the city.

	== See Also ==		== See Also ==