Difference between revisions of "InterfaceActionsWML"

From The Battle for Wesnoth Wiki
 
m (fixed formatting)
Line 3: Line 3:
 
Interface actions are actions that do not have an effect on gameplay;
 
Interface actions are actions that do not have an effect on gameplay;
 
instead, they show something to the player.  The main interface tags
 
instead, they show something to the player.  The main interface tags
are '''[message]|| and ||[objectives]''', but several other tags affect
+
are '''[message]''' and '''[objectives]''', but several other tags affect
 
the interface also.
 
the interface also.
  
  
<H2>[message]</H2>
+
== [message] ==
The most commonly used interface action is [message],
+
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.
which displays a message to the user in a dialog box.
 
It can also be used to take input from the user.
 
  
 
The following key/tags are accepted for [message]:
 
The following key/tags are accepted for [message]:
* standard unit filter- the unit whose profile and name are displayed.
+
* standard unit filter - the unit whose profile and name are displayed. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).
If no unit matching this filter is found, the message is not displayed
+
 
(The unit has probably been killed).
+
'''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.
== [message] == elements should be constructed so that it is either guaranteed that a certain unit is alive,
 
or so that dialog flows smoothly even if the message isn't displayed.
 
 
* ''speaker'' an alternative to standard unit filter
 
* ''speaker'' an alternative to standard unit filter
 
** 'narrator' the dialog box is displayed without a caption for the unit speaking or a unit image
 
** 'narrator' the dialog box is displayed without a caption for the unit speaking or a unit image
Line 25: Line 21:
 
''message'' is sometimes multiple lines; if it is, be sure to use quotes(''''|| or ||"''')
 
''message'' is sometimes multiple lines; if it is, be sure to use quotes(''''|| or ||"''')
 
* ''image'' (default: profile image of speaker) the image to display next to the message.
 
* ''image'' (default: profile image of speaker) the image to display next to the message.
* ''caption'' (default: name of speaker) the caption to display under the image.
+
* ''caption'' (default: name of speaker) the caption to display under the image. Name to be displayed.
name to be displayed.
 
 
* ''sound'' a sound effect (wav file) to play as the message is displayed
 
* ''sound'' a sound effect (wav file) to play as the message is displayed
* '''[option]|| zero or more ||[option]''' elements may be present.
+
* '''[option]|| zero or more ||[option]''' elements may be present. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
If '''[option]''' elements are present,
 
then each option will be displayed in a menu for the user to select one option.
 
 
** ''message'' (translatable) the text displayed for the option (see [[DescriptionWML]])
 
** ''message'' (translatable) the text displayed for the option (see [[DescriptionWML]])
 
** '''[command]''' an element containing actions which are executed if the option is selected.
 
** '''[command]''' an element containing actions which are executed if the option is selected.
Line 42: Line 35:
  
  
<H2>[objectives]</H2>
+
== [objectives] ==
 
The other tag used for plot development is '''[objectives]'''.
 
The other tag used for plot development is '''[objectives]'''.
 
The '''[objectives]''' tag overwrites any previously set objectives,
 
The '''[objectives]''' tag overwrites any previously set objectives,
Line 52: Line 45:
 
scenario-specific information that the player may need to refer to during play.
 
scenario-specific information that the player may need to refer to during play.
  
This tag renders the ''objectives'' attribute of [scenario] obsolete
+
This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).
(see ''objectives'', [[ScenarioWML]]).
+
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives
 
inside a prestart event.
 
 
It can also be used to overwrite the starting objectives mid-scenario.
 
It can also be used to overwrite the starting objectives mid-scenario.
  
 
Attributes of '''[objectives]''':
 
Attributes of '''[objectives]''':
 
* ''side'' Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
 
* ''side'' Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
* ''summary'' Displayed first in the objectives text,
+
* ''summary'' Displayed first in the objectives text, this should describe the basic objective for the overall scenario.  Can be omitted.
this should describe the basic objective for the overall scenario.  Can be omitted.
+
* ''note'' Displayed last in the objectives text, this is sometimes used for hints or additional information.  Can be omitted.
* ''note'' Displayed last in the objectives text,
 
this is sometimes used for hints or additional information.  Can be omitted.
 
 
* ''victory_string'' Default ' _ "Victory:"', this text precedes the victory objectives.
 
* ''victory_string'' Default ' _ "Victory:"', this text precedes the victory objectives.
 
* ''defeat_string'' Default ' _ "Defeat:"', this text precedes the defeat objectives.
 
* ''defeat_string'' Default ' _ "Defeat:"', this text precedes the defeat objectives.
* ''silent'' Default: not present.
+
* ''silent'' Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
If set to "yes", the objectives are silently changed.
 
Else, they will be shown to the user when appropriate.
 
  
 
Tags of '''[objectives]''':
 
Tags of '''[objectives]''':
* '''[objective]''' describes a win or loss condition.
+
* '''[objective]''' describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
Most scenarios have multiple win or loss conditions,
 
so use a separate [objective] subtag for each line; this helps with translations.
 
 
** ''description'' text for the specific win or loss condition.
 
** ''description'' text for the specific win or loss condition.
** ''condition'' The color and placement of the text.
+
** ''condition'' The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
Values are 'win'(colored green, placed after ''victory_string'')
 
and 'lose'(colored red, placed after ''defeat_string'')
 
  
  
Line 83: Line 66:
  
 
The following tags are also action tags:
 
The following tags are also action tags:
* '''[item]''' makes a graphical item appear on a certain hex.
+
* '''[item]''' makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something.
Note this only places the graphics for an item.
+
** ''x'', ''y'' the location to place the item.
It does not make the item do anything.
 
Use a moveto event to make moving onto the item do something.
 
** ''x//,//y'' the location to place the item.
 
 
** ''image'' the image (in ''images/ ''as .png) to place on the hex.
 
** ''image'' the image (in ''images/ ''as .png) to place on the hex.
** ''halo'' an image to place centered on the hex.
+
** ''halo'' an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex.
Use this instead of ''image'' if the image is bigger than the hex.
 
 
* '''[removeitem]''' removes any graphical items on a given hex
 
* '''[removeitem]''' removes any graphical items on a given hex
 
** ''x//,//y'' the hex to remove items off
 
** ''x//,//y'' the hex to remove items off
* '''[print]''' displays a message across the screen.
+
* '''[print]''' displays a message across the screen. The message will disappear after a certain time.
The message will disappear after a certain time.
 
 
** ''text'' (translatable) the text to display.
 
** ''text'' (translatable) the text to display.
 
** ''size'' (default=12) the pointsize of the font to use
 
** ''size'' (default=12) the pointsize of the font to use
** ''duration'' (default=50) the length of time to display the text for.
+
** ''duration'' (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
This is measured in the number of 'frames'.
+
** ''red//,//green//,//blue'' (default=0,0,0) the color to display the text in. Values vary from 0-255.
A frame in Wesnoth is usually displayed for around 30ms.
 
** ''red//,//green//,//blue'' (default=0,0,0) the color to display the text in.
 
Values vary from 0-255.
 
 
* '''[move_unit_fake]''' moves an image of a unit along a certain path on the map.
 
* '''[move_unit_fake]''' moves an image of a unit along a certain path on the map.
 
** ''type'' the type of the unit whose image to use
 
** ''type'' the type of the unit whose image to use
 
** ''x'' a comma-seperated list of x locations to move along
 
** ''x'' a comma-seperated list of x locations to move along
 
** ''y'' a comma-seperated list of y locations to move along (x and y values are matched pairs)
 
** ''y'' a comma-seperated list of y locations to move along (x and y values are matched pairs)
* '''[hide_unit]''' makes the given unit become invisible.
+
* '''[hide_unit]''' makes the given unit become invisible. Useful in conjunction with '''[move_unit_fake]''' to move a leader unit into position on-screen. Only one unit may be hidden at a time.
Useful in conjunction with '''[move_unit_fake]''' to move
+
** ''x'', ''y'' location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
a leader unit into position on-screen.
 
Only one unit may be hidden at a time.
 
** ''x//,//y'' location of the unit to be hidden.
 
(NOT a standard unit filter! Just x and y.)
 
 
* '''[unhide_unit]''' stops the currently hidden unit from being hidden.
 
* '''[unhide_unit]''' stops the currently hidden unit from being hidden.
* '''[scroll]''' Scroll a certain number of pixels in a given direction.
+
* '''[scroll]''' Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
Useful for earthquake/shaking effects.
+
** ''x'', ''y'' the number of pixels to scroll along the x and y axis
** ''x//,//y'' the number of pixels to scroll along the x and y axis
 
 
* '''[scroll_to]''' Scroll to a given hex (new in 0.9.2)
 
* '''[scroll_to]''' Scroll to a given hex (new in 0.9.2)
** ''x//,//y'' the hex to scroll to
+
** ''x'', ''y'' the hex to scroll to
 
* '''[scroll_to_unit]''' Scroll to a given unit
 
* '''[scroll_to_unit]''' Scroll to a given unit
 
** standard unit filter
 
** standard unit filter
Line 125: Line 95:
 
** ''name'' the filename of the music to play (in ''music/'' as .ogg)
 
** ''name'' the filename of the music to play (in ''music/'' as .ogg)
 
* '''[colour_adjust]''' tints the colour of the screen.
 
* '''[colour_adjust]''' tints the colour of the screen.
** ''red//,//green//,//blue'' values from -255 to 255, the amount to tint by for each colour
+
** ''red'', ''green'', ''blue'' values from -255 to 255, the amount to tint by for each colour
 
* '''[delay]''' pauses the game
 
* '''[delay]''' pauses the game
 
** ''time'' the time to pause in milliseconds
 
** ''time'' the time to pause in milliseconds
* '''[redraw]''' redraws the screen (this normally isn't done during events,
+
* '''[redraw]''' redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn)
although some of the other interface actions
+
* '''[unit_overlay]''' sets an image that will be drawn over a particular unit, and follow it around
cause the screen or parts of it to be redrawn)
+
** ''x'', ''y'' the location of the unit to overlay on
* '''[unit_overlay]''' sets an image that will be drawn over a particular unit,
 
and follow it around
 
** ''x//,//y'' the location of the unit to overlay on
 
 
** ''image'' the image to place on the unit
 
** ''image'' the image to place on the unit
 
* '''[remove_unit_overlay]''' removes a particular overlayed image from a unit
 
* '''[remove_unit_overlay]''' removes a particular overlayed image from a unit
** ''x//,//y'' the location of the unit to remove an overlay from
+
** ''x'', ''y'' the location of the unit to remove an overlay from
 
** ''image'' the image to remove from the unit
 
** ''image'' the image to remove from the unit
  
Line 145: Line 112:
 
* [[EventWML]]
 
* [[EventWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 

Revision as of 10:33, 23 August 2005

Interface actions

Interface actions are actions that do not have an effect on gameplay; instead, they show something to the player. The main interface tags are [message] and [objectives], but several other tags affect the interface also.


[message]

The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:

  • standard unit filter - the unit whose profile and name are displayed. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).

[message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

  • speaker an alternative to standard unit filter
    • 'narrator' the dialog box is displayed without a caption for the unit speaking or a unit image
    • 'unit' the primary unit for the event is speaking
    • 'second_unit' the secondary unit for the event is speaking
  • message (translatable) the text to display to the right of the image.

message is sometimes multiple lines; if it is, be sure to use quotes('|| or ||")

  • image (default: profile image of speaker) the image to display next to the message.
  • caption (default: name of speaker) the caption to display under the image. Name to be displayed.
  • sound a sound effect (wav file) to play as the message is displayed
  • [option]|| zero or more ||[option] elements may be present. If [option] elements are present, then each option will be displayed in a menu for the user to select one option.
    • message (translatable) the text displayed for the option (see DescriptionWML)
    • [command] an element containing actions which are executed if the option is selected.

Text formatting options for [message]

  • An asterisk (*) as the first character causes the line to be boldfaced.
  • An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
  • A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
  • A backquote (`) as the first character causes the line to be smaller.
  • If used, the caption key text is boldfaced.


[objectives]

The other tag used for plot development is [objectives]. The [objectives] tag overwrites any previously set objectives, and displays text which should describe the objectives of the scenario. Scenario objectives are displayed on the player's first turn after the tag is used, or as part of the event if it triggers during that player's turn. Objectives can also be accessed at any time in a scenario using the "Scenario Objectives" game menu option, making this tag useful for scenario-specific information that the player may need to refer to during play.

This tag renders the objectives attribute of [scenario] obsolete (see objectives, ScenarioWML). Instead of using objectives, use [objectives] to set scenario objectives inside a prestart event. It can also be used to overwrite the starting objectives mid-scenario.

Attributes of [objectives]:

  • side Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
  • summary Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
  • note Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
  • victory_string Default ' _ "Victory:"', this text precedes the victory objectives.
  • defeat_string Default ' _ "Defeat:"', this text precedes the defeat objectives.
  • silent Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of [objectives]:

  • [objective] describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
    • description text for the specific win or loss condition.
    • condition The color and placement of the text. Values are 'win'(colored green, placed after victory_string) and 'lose'(colored red, placed after defeat_string)


Other interface tags

The following tags are also action tags:

  • [item] makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something.
    • x, y the location to place the item.
    • image the image (in images/ as .png) to place on the hex.
    • halo an image to place centered on the hex. Use this instead of image if the image is bigger than the hex.
  • [removeitem] removes any graphical items on a given hex
    • x//,//y the hex to remove items off
  • [print] displays a message across the screen. The message will disappear after a certain time.
    • text (translatable) the text to display.
    • size (default=12) the pointsize of the font to use
    • duration (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
    • red//,//green//,//blue (default=0,0,0) the color to display the text in. Values vary from 0-255.
  • [move_unit_fake] moves an image of a unit along a certain path on the map.
    • type the type of the unit whose image to use
    • x a comma-seperated list of x locations to move along
    • y a comma-seperated list of y locations to move along (x and y values are matched pairs)
  • [hide_unit] makes the given unit become invisible. Useful in conjunction with [move_unit_fake] to move a leader unit into position on-screen. Only one unit may be hidden at a time.
    • x, y location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
  • [unhide_unit] stops the currently hidden unit from being hidden.
  • [scroll] Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
    • x, y the number of pixels to scroll along the x and y axis
  • [scroll_to] Scroll to a given hex (new in 0.9.2)
    • x, y the hex to scroll to
  • [scroll_to_unit] Scroll to a given unit
    • standard unit filter
  • [sound] Plays a sound
    • name the filename of the sound to play (in sounds/ as .wav)
  • [music] Switches to playing different music
    • name the filename of the music to play (in music/ as .ogg)
  • [colour_adjust] tints the colour of the screen.
    • red, green, blue values from -255 to 255, the amount to tint by for each colour
  • [delay] pauses the game
    • time the time to pause in milliseconds
  • [redraw] redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn)
  • [unit_overlay] sets an image that will be drawn over a particular unit, and follow it around
    • x, y the location of the unit to overlay on
    • image the image to place on the unit
  • [remove_unit_overlay] removes a particular overlayed image from a unit
    • x, y the location of the unit to remove an overlay from
    • image the image to remove from the unit


See Also