InterfaceActionsWML

[edit]WML Tags

A: abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B: base_unit, background_layer, berserk, binary_path, break, brush;

C: campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D: damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E: editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F: facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G: game_config, get_global_variable, goal, gold, gold_carryover;

H: harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I: idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J: jamming_costs, join;

K: kill, killed;

L: label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M: male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N: not, note;

O: object, objective, objectives, on_undo, open_help, option, options, or;

P: part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R: race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S: save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T: target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U: unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V: value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W: while, wml_message, wml_schema;

Z: zoom;

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 " )
• side_for (default: all sides) comma seperated list of sides for who message is shown. Template:DevFeature
• 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.
• duration (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded. Template:DevFeature
• sound a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
• [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)
  • [show_if] if present then this option will only be displayed if the conditional statement in this tag is passed (see InternalActionsWML) Template:DevFeature
  • [command] an element containing actions which are executed if the option is selected.

Text formatting options for [message]. These can also be used in unit names (user_description), objectives, and such.

• 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.
• An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: message=_"<255,0,0>Red!"

[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)

[set_menu_item] Template:DevFeature

This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

• id the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
• description the in-game text that will appear for this item in the menu.
• image the image to display next to this item.
• needs_select if yes (default no), then the latest select event (see EventWML) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
• [show_if] If present, the menu item will only be available if the conditional statement (see InternalActionsWML) within evaluates to true. When this is evaluated, the WML variables $x1 and $y1 will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
• [filter_location] contains a location filter similar to the one found inside Single Unit Filters (see FilterWML). The menu item will only be available on matching locations.
• [command] contains the WML actions to be executed when the menu item is selected. Again, the WML variables $x1 and $y1 will point to the location on which the context menu was invoked on.

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. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
  • 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)
  • side the side of the fake unit, used for team colouring the fake unit
• [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
  • x, y the hex to scroll to
  • check_fogged whether to scroll even to locations covered in fog or shroud. Possible values true (don't scroll to fog) and false (scroll even to fog), with false as the default.
• [scroll_to_unit] Scroll to a given unit
  • standard unit filter
  • check_fogged whether to scroll even to locations covered in fog or shroud. Possible values true (don't scroll to fog) and false (scroll even to fog), with false as the default.
• [sound] Plays a sound
  • name the filename of the sound to play (in sounds/ as .wav or .ogg)
  • repeat Template:DevFeature repeats the sound for a specified additional number of times (default=0)
• [sound_source] Template:DevFeature Creates a sound source. "Sound sources" is a general name for a mechanism, which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
  • id a unique identification key of the sound source
  • sounds a list of comma separated, randomly played sounds associated with the sound source
  • delay a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
  • chance a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
  • check_fogged possible values "true" and "false" - if true the source will not play if its locations are fogged/shrouded
  • x,y a standard location filter for the locations associated with the sound source
• [remove_sound_source] Template:DevFeature Removes a previously defined sound source.
  • id the identification key of the sound source to remove
• [music] Switches to playing different music
  • name the filename of the music to play (in music/ as .ogg)
  • see MusicListWML for the correct syntax
• [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).
  • side if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
• [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
• [animate_unit] uses the custom animation of a unit to animate it on screen (if the unit has the corresponding animation)
  • flag the key to find the good custom animation in the unit description see the [extra_anim] description in AnimationWML
  • [filter] a standard unit filter see FilterWML by default, the unit at the event location will be animated. You can use this tag to choose what unit to animate
• [label] places a label on the map.
  • x, y the location of the label
  • text what the label should say
  • team_name if specified, the label will only be visible to the given team.
• [deprecated_message] Template:DevFeature shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
  • message the message to show.
• [debug_message] Template:DevFeature outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting.
  • message the message to show
  • logger the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

See Also

• DirectActionsWML
• InternalActionsWML
• EventWML
• ReferenceWML