The Battle for Wesnoth Wiki - User contributions [en]

DirectActionsWML

2023-07-09T23:51:43Z

Toranks: /* [harm_unit] */ Experience= default

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [[SingleUnitWML|filter_recall]] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
* '''location_id''': This key sets a string as a way to mark the hex or hexes for later reference. It is very similar to the leader starting position, and can also be set that way in the map editor.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|[modify_ai]]]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements, and will potentially overwrite existing modifications.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit (saved inside the unit's [variables] tag); uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]'''
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points. Regardless of anything else, the unit will be rebuilt. Thus, transforming a unit to its current type is a way to force a rebuild, for example after manually removing a modification.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it tries to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.
* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' [event] in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an '''enter_hex'''/'''exit_hex''' [event], interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an '''enter_hex''' [event] on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an enter_hex [event] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': (default yes) If there is a harmer, experience will be attributed like in regular combat. Set it to no so that it does not generate experience.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

=== [set_sub_achievement] ===

{{DevFeature1.17|17}}

Sets the specified sub-achievement as completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

=== [progress_achievement] ===

{{DevFeature1.17|13}}

Progress an achievement by the specified amount, with an optional limit for how far the achievement can be progressed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''amount''': The amount to increment the achievement.
* '''limit''': (optional) Using this attribute will prevent achievements from progressing past this value.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

InterfaceActionsWML

2023-05-16T02:45:56Z

Toranks: /* [label] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [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]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. 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. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''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 ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''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.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'. The full list of color names may be found in Pango's [https://github.com/GNOME/pango/blob/main/tools/rgb.txt rgb.txt] file.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''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'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
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. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''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. All menus will be sorted lexicographically by the id string. The ordering is underscores, digits, and finally letters.
* '''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. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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 [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[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.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [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. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [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-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [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
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
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 ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
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

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say. If you put an empty string <code>""</code> as an argument, the label will be completely removed. Use this method if you want to remove a specific label from any location.
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter] unless you intend to match one or more units).
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
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.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
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. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''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.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor, measured as a multiple of the base zoom.
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

InterfaceActionsWML

2023-04-27T00:09:43Z

Toranks: /* [set_menu_item] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [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]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. 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. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''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 ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''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.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'. The full list of color names may be found in Pango's [https://github.com/GNOME/pango/blob/main/tools/rgb.txt rgb.txt] file.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''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'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
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. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''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. All menus will be sorted first numerically and then alphabetically by id string.
* '''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. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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 [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[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.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [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. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [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-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [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
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
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 ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
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

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say. If you put an empty space <code>""</code> as an argument, the label will be completely removed. Use this method if you want to remove a specific label from any location.
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter] unless you intend to match one or more units).
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
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.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
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. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''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.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor, measured as a multiple of the base zoom.
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

InterfaceActionsWML

2023-04-27T00:06:54Z

Toranks: /* [set_menu_item] */ Ordered by id

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [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]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. 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. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''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 ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''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.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'. The full list of color names may be found in Pango's [https://github.com/GNOME/pango/blob/main/tools/rgb.txt rgb.txt] file.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''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'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
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. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''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. All menus will be sorted numerically and alphabetically by id string.
* '''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. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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 [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[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.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [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. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [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-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [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
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
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 ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
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

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say. If you put an empty space <code>""</code> as an argument, the label will be completely removed. Use this method if you want to remove a specific label from any location.
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter] unless you intend to match one or more units).
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
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.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
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. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''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.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor, measured as a multiple of the base zoom.
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

InterfaceActionsWML

2023-04-09T18:13:00Z

Toranks: /* [label] */ How to remove label

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [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]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. 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. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''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 ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''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.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'. The full list of color names may be found in Pango's [https://github.com/GNOME/pango/blob/main/tools/rgb.txt rgb.txt] file.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''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'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
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. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''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. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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 [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[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.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [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. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [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-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [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
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
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 ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
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

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say. If you put an empty space <code>""</code> as argument, the label will be completely removed; use this method if you want to remove a specific label in any location.
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter] unless you intend to match one or more units).
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
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.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
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. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''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.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor, measured as a multiple of the base zoom.
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

SingleUnitWML

2023-04-05T19:06:18Z

Toranks: /* Unit State */ Added more reliable statuses (with unit test), and better description of the others

{{WML Tags}}
The '''[unit]''' tag describes a single unit on the map or in memory, for example Konrad.
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)

This contains keys and tags which describe the unit's [[#Unit Data|persistent data]], as well as certain [[#Unit State|state variables]] which will also persist with the unit but will change frequently as gameplay progresses. Finally, there are some keys to set certain [[#Creation Options|one-time options]] for how the unit will be initially created, which will ''not'' persist beyond initial creation.

== Unit Data ==
The following keys and tags describe the unit itself, and will persist with the unit (though some may change automatically when the unit advances):
* '''type''': the ID of the unit's unit type. This key is mandatory. See [[UnitTypeWML]].

* '''variation''': the [variation] of the [unit_type] as which the unit will appear.

* '''parent_type''': overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable. Defaults to 1, except when the [unit] tag appears inside a [side], in which case the unit always belongs to that side, and this key is ignored.

* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified, a random one will be generated for the unit to ensure that each unit has a unique '''id''' attribute (as will happen when a unit is recruited normally). In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.) Note: While it IS technically possible to create multiple units with the same ID, doing so may produce unpredictable results in many cases. WML should therefore be structured in such a way that no two units in existence ever end up with the same ID.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male (unless [[#random_gender|'''random_gender''']] is set to "yes"), but if the unit has only a female variant it will be female.

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set). Although this is a translated string, see [[GettextForWesnothDevelopers#Proper_nouns_in_strings|proper nouns in strings]] before using it in a translatable string.

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit= (only relevant for units with '''canrecruit=yes''').

* '''[filter_recall]''' A leader can only recall those units which pass the SUF. (Meaningful only if canrecruit=yes.)
**'''[[StandardUnitFilter]]''' tags and keys

* '''level''': the unit's current level. Defaults to the level of the [unit_type] described by [[#type|'''type''']]. This is generally not set manually.

* '''upkeep''': the amount of upkeep the unit will require each turn.
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''free''': synonymous with "loyal".
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.
** {{DevFeature1.15|0}} This key is supported when creating a unit from WML, but will be empty when writing the unit back to WML; the overlays will instead be stored as [modifications].

* '''max_hitpoints''': The maximum hitpoints the unit has when at full health. Default is the max HP set for the [unit_type] described by [[#type|'''type''']].

* '''max_experience''': The experience the unit needs to advance. Default is the experience required for the [unit_type] described by [[#type|'''type''']].

* '''max_moves''': The maximum number of movement points the unit has. Default is the number of movement specified for the [unit_type] described by [[#type|'''type''']].

* '''vision''': The the number of vision points to calculate the unit's sight range. Default is the number of vision points specified for the [unit_type] described by [[#type|'''type''']].

* '''jamming''': {{DevFeature1.15|0}} The number of jamming points for the unit. Default is the number of jamming points specified for the [unit_type] described by [[#type|'''type''']].

* '''flying''': 'yes' if the unit's [[UnitsWML#.5Bmovetype.5D|movetype]] has flying=yes. For units that don't fly, the '''flying''' attribute is generally omitted rather than being recorded as 'no'. In SingleUnitWML, this attribute has been called '''flying''' since it was added in 1.11.2, it was never called 'flies'.

* '''max_attacks''': The number of attacks the unit can have per turn. Default is the number of attacks specified for the [unit_type] described by [[#type|'''type''']].

* '''profile''': sets a portrait image for this unit. Default is the portrait image set for the [unit_type] described by [[#type|'''type''']]. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.

* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]). The subnode '''mods''' is special as it is deleted on every unit rebuild (for example when the unit advances or when an [object] is removed). This makes it possible to implement [effect]s that change variables, as those will also be reapplied whenever the unit is reset. (so in particular if your effect changes the variables mods.<whatever> [remove_object] will work properly for those objects.) For example the following code will define a apply_to=moves_on_recruits effect that gives units with that effect full movement when recruited

<syntaxhighlight lang='lua'>
function wesnoth.effects.move_on_recruit(u, cfg)
-- maybe better use a status than a variable ?
u.variables["mods.move_on_recruit"] = true
end
on_event("recruit,recall", function(ec)
local unit = wesnoth.get_unit(ec.x1, ec.y1)
if unit and unit.variables["mods.move_on_recruit"] then
unit.attacks_left = 1
unit.moves = unit.max_moves
end
end)
</syntaxhighlight>
And since we used the mods subtable, [remove_object] will work properly for objects that give this effect.

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [[UnitsWML#.5Btrait.5D|[trait], UnitsWML]].
** '''[object]''' an object the unit has. Same format as [[DirectActionsWML#.5Bobject.5D|[object], DirectActionsWML]].
** '''[advance]''' an advancement that has already been applied to the unit. Same format as [[UnitTypeWML#After max level advancement (AMLA)|AMLA [advancement], UnitTypeWML]]. These are automatically added as the unit has AMLA advancements applied to it, but can also be specified manually to indicate that the unit already has a particular advancement applied, or to disable certain advancements (by ID). {{DevFeature1.13|2}} In 1.13.2 and later this has been renamed to [advancement], to match the UnitTypeWML tag of the same name.

* '''[event]''' The event is copied from this unit's WML description into the scenario. The event is carried along with the unit (even during advancement) and inserted into a scenario whenever this unit is first included. A [unit][event] requires a non-empty id= attribute.

* '''description''': overrides the unit type description for this unit. Note that this will be reset when the unit advances. To avoid this, one can either set up a ''post_advance'' [[EventWML|event]] to override the default description after promotion, or use an [object] with a profile [[EffectWML|effect]] to change the unit description.

* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes]].

* '''ai_special''': causes the unit to act differently
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''[status] guardian = 'yes''''.

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details
** {{DevFeature1.15|?}} '''[candidate_action]''': Add a candidate action that only applies to this unit; see [[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|here]] for details. The [filter_own] tag is not supported.
*** '''stage''': If specified, the candidate action is added to the stage with the given ID, instead of the default stage (which is main_loop).
** {{DevFeature1.15|?}} '''[micro_ai]''': Add a micro AI that only applies to this unit; see [[Micro AIs]] for details. This tag does not support side, action, or [filter].

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

*'''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is the alignment of the [unit_type] described by [[#type|'''type''']]. This is generally not set manually.

*'''advances_to''': comma-separated list of unit types to which this unit can advance. Will override the default provided by the [unit_type]. This is generally not set manually.

*'''race''': See {{tag|UnitsWML|race}}. Will override the default provided by the [unit_type]. This is generally not set manually.

*'''undead_variation''': Will override the default provided by the [unit_type]. This is generally not set manually.

*'''usage''': Will override the default provided by the [unit_type]. This is generally not set manually.

*'''zoc''': whether the unit has a zone of control. Will override the default provided by the [unit_type]. This is generally not set manually.

*'''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''': Can be used to modify [[UnitsWML#.5Bmovetype.5D|existing values]].

*'''[attack]''': Takes the same syntax as [[UnitTypeWML#Attacks|[unit_type][attack]]]. By default, the attacks from the [unit_type] will be included. '''Note:''' using this tag will replace ''all'' [attack] tags with the new one.

*'''hidden''': Implementation detail of [[InterfaceActionsWML#%5Bhide_unit%5D|[hide_unit]]]. This should not be set manually.

== Unit State ==
The following keys and tags describe the current state of the unit, and will change regularly as gameplay progresses:
* '''x''', '''y''': the location of the unit. By default (unless modified by [[#placement|'''placement''']] below) if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list. The recall list can also be explicitly specified as the location with "recall,recall".

* '''location_id''': {{DevFeature1.13|8}} the location of the unit, referencing one of the special locations defined by the map. This overrides '''x''' and '''y''' if present but otherwise has the same effect and can be modified by the placement options.

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Note that some unit types may not have distinct animations for each direction.

* '''goto_x''':, '''goto_y''': the unit's current movement destination. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default [[#max_hitpoints|'''max_hitpoints''']].

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is [[#max_moves|'''max_moves''']].
: '''Note:''' Do not assume that moves=max_moves on turns when the unit doesn't move. The wesnoth AIs sometimes manipulate the moves variable during its turn, for internal reasons.

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give the unit rest healing. Note that this can be true even if moves is not equal to max_moves.

* '''attacks_left''': number of attacks the unit has left. Default is '''max_attacks'''.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, '''slowed''' is set to 'no'.
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn. For cutscenes, it may be useful to set this manually.
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''ai_special = "guardian"'''.
** '''unhealable''': if set to 'yes', the unit cannot be healed. This includes the healing by resting.
** '''unpoisonable''': if set to 'yes', the unit cannot be poisoned.
** '''undrainable''': if set to 'yes', the attacker can't gain health with drain ability attacking this unit.
** '''unplagueable''': if set to 'yes', the unit cannot be affected by plague attack.
** '''unslowable''': if set to 'yes', the unit cannot be slowed.
** '''unpetrifiable''': if set to 'yes', the unit cannot be petrified.
** '''not_living''': Deprecated, this is automatically set when all three above are set and vice versa.
** '''invulnerable''': {{DevFeature1.13|6}} if 'yes', attacks can't hit the unit. The AI and the attack dialog take it into account.
** One can add other keys to [status], but they must have boolean values, and they will not do anything meaningful on their own (but can be checked from events and acted upon accordingly). For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.

* '''invulnerable''': {{DevFeature1.13|6}} a shorthand to set the ''invulnerable'' status. Useful in [[CommandMode]] for debugging purposes. It's recommended to use [status] in written code instead.

== Creation Options ==
In addition to the unit's persistent data itself, there are several options for controlling how the unit will be created, as follows:
* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y (or location_id) are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y (or location_id) are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events. {{DevFeature1.13|8}} Deprecated, use placement=map and overwrite=yes instead.
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex. {{DevFeature1.13|8}} Deprecated, use placement=map and passable=yes instead.
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed. {{DevFeature1.13|8}} Deprecated, use placement=leader and passable=yes instead.
* '''passable''': {{DevFeature1.13|8}} (default=no) If yes, and the specified location is of an impassable terrain for the unit being placed, the new unit will be placed in the nearest hex that is of a passable terrain for it.
* '''overwrite''': {{DevFeature1.13|8}} (default=no) If yes, always place the unit at the exact specified location, overwriting the existing unit if there is one. Generally you don't want to use this together with placement=leader.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.
* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give the unit fewer traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''to_variable''': (only for [event][unit]) creates the unit into the given variable instead of placing it on the map.

* '''animate''': whether to display the recruitment animation for this unit as if it were being recruited/recalled. Defaults to "no". Irrelevant when the [unit] tag appears inside a [side].

== See Also ==

* [[UnitTypeWML]]
* [[InternalActionsWMLUnitTags]]
* [[ReferenceWML]]

[[Category:WML Reference]]

StandardUnitFilter

2023-03-24T14:17:22Z

Toranks:

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering units.

When a unit filter is applied to a map, first it applies to all units on the field,
based on their coordinates.
Next it applies to units in the recall list.
This is important to remember as it means, for example,
that the tag '''[kill]''' can be used to kill units in the recall list.

You can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables

The term [[StandardUnitFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardUnitFilter]] needs to be included in a [filter] tag. But many tags take the [[StandardUnitFilter]] directly as an argument, like [kill] and [have_unit]. See [[Special:WhatLinksHere/StandardUnitFilter]] for tags which can contain a StandardUnitFilter.

__TOC__

The following attributes and sub-tags are allowed:

* '''id''': unit matches the given id. This is the same as ''id'' in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this (see [[SingleUnitWML]]). id= can be a comma-separated list, every unit with one of these ids matches.
* '''speaker''': alias for id (no comma-separated list supported)
* '''type''': matches the unit's type name (can be a list of types)
* '''type_adv_tree''': {{DevFeature1.13|7}} matches the type name of the unit and all its advancements (can be a list)
* '''race''': the race of the unit type. This can be a comma-separated list; the unit's race must match one of the given races. Mainline races are listed in data/core/units.cfg 
* '''variation''': the unit type variation id (can be a list of variation ids)
* '''has_variation''': matches if the unit type for the unit defines at least one of the variation ids provided as a comma-separated list
* '''upkeep''': {{DevFeature1.15|3}} The upkeep of the unit. Can be either a non-negative number or one of the special values ''loyal'', ''free'', ''full''. Note that while ''loyal'' and ''free'' are synonymous with an upkeep of 0, the value ''full'' is not synonymous with any single numeric value – it is equivalent to <code>$this_unit.level</code>.
* '''ability''': unit has an ability with the given id; see [[AbilitiesWML]]. This can be a comma-separated list. The unit must have at least one of the specified abilities.
* '''ability_type''': {{DevFeature1.13|7}} unit has an ability with the given type (tag name) - eg, ''ability_type=heals'' will match a unit with any healing ability.
* '''ability_type_active''': {{DevFeature1.13|8}} unit has an ''active'' ability with the given type (tag name).
* '''ability_id_active''': {{DevFeature1.15|13}} unit has an ''active'' ability with the given id; see [[AbilitiesWML]]
* '''trait''': {{DevFeature1.13|8}} This can be a comma-separated list. The unit must have at least one of the specified traits.
* '''status''': {{DevFeature1.13|0}} matches if the unit has the specified status active. This can be a comma-separated list, in which case the unit will match as long as it has one of the listed statuses active (note: possible statuses are listed on the [[SingleUnitWML]] page).
* '''side''': the unit is on the given side (can be a list)
* '''has_weapon''': the unit has a weapon with the given name {{DevFeature1.13|5}} Now deprecated
* '''[has_attack]''': {{DevFeature1.13|5}} the unit has a weapon matching the [[StandardWeaponFilter]]. If this is present, '''has_weapon''' is ignored.
* '''canrecruit''': yes if the unit can recruit (i.e. is a leader)
* '''gender''': female if the unit is female rather than the default of male
* '''role''': the unit has been assigned the given role; see '''[role]''', [[InternalActionsWML]]
* '''level''': the level of the unit (this can be a comma-separated list).
* '''defense''': current defense of the unit on current tile (chance to hit %, like in movement type definitions)
* '''movement_cost''': current movement cost of the unit on current tile. Can be a number, range, or comma separated range.
* '''x,y''': the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
* '''find_in''': name of an array or container variable; if present, the unit will not match unless a unit with the same '''id''' is already stored in the variable
* '''[filter_vision]''': this tests whether or not the unit is currently visible
** '''visible''': yes or no, default yes. When "yes", this matches units that are not obscured by fog or shroud, and that are not hiding (via the {{tag|AbilitiesWML|hides}} ability). When "no", this matches units that are obscured by fog or shroud, or that are hiding.
** [[StandardSideFilter]] tags and keys. Filter for who may be able to see (or not see) the unit. If there is *at least one* matching side which can see the unit then the filter matches, and otherwise it fails to match.
* '''[filter_wml]''': Converts the unit to WML (as if by '''[store_unit]''') and tests it against a [[FilterWML#Filtering_on_WML_data|WML filter]]. For a list of things in the WML that could be filtered on, see [[SingleUnitWML]] or open a saved game in a text editor. Note that this is slower than other methods, so if possible it's better to use other filter keys and tags; however, if the WML filter contains only a child '''[variables]''', then the unit is not converted to WML and the filter is matched only against the unit's variables (which are already WML).
* '''[and]''': an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. ''Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.''
* '''[or]''': an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
* '''[filter_adjacent]''' with a StandardUnitFilter as argument; do not use a [filter] tag. If present the correct number of adjacent units must match this filter.
**'''StandardUnitFilter''' tags and keys
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[StandardLocationFilter#Directions|notes]])
** '''is_enemy''': a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
** '''$other_unit''': {{DevFeature1.13|2}} Within [filter_adjacent], the special variable $other_unit refers to the filtered unit from the enclosing filter, while $this_unit refers (as with all StandardUnitFilters) to the unit being filtered on.
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
*'''[filter_side]''': The currently filtered unit's side must match this [[StandardSideFilter]] for the unit to match.
**[[StandardSideFilter]] tags and keys
* '''formula''': A formula using [[Wesnoth Formula Language]]. The <tt>self</tt> variable is set to the current $this_unit, and the formula should return a boolean. If it returns 0, the filter does not match. Otherwise, the filter does match. {{DevFeature1.13|5}} If the filter has a secondary unit, the formula can access it using the <code>other</code> variable. Both the unit and the secondary unit are a '''unit object''', with keys documented [[#Wesnoth_Formula_Language|below]]. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
* '''lua_function''': the name of a [[LuaWML|Lua]] function in the global environment that takes a unit as an argument and returns true if the given unit matches the filter. {{DevFeature1.13|5}} Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

== Wesnoth Formula Language ==

When using the '''formula''' key, the '''self''' and (if present) '''other''' objects support the following keys:

* '''x''', '''y''', '''loc''' - the latter is a '''location object''' such as what would be returned from [[Wesnoth_Formula_Language#loc|loc()]].
* '''id'''
* '''type'''
* '''name'''
* '''usage'''
* '''canrecruit''', '''leader'''
* '''undead''' - true if the unit has the ''not_living'' status
* '''attacks''' - a list of '''[[FilterWML#Filtering_Weapons|weapon objects]]'''
* '''abilities''' - a list of the ability IDs the unit possesses
* '''hitpoints''', '''max_hitpoints'''
* '''experience''', '''max_experience'''
* '''moves''', '''max_moves'''
* '''attacks_left''', '''max_attacks'''
* '''level''', '''full''' - '''full''' refers to the unit's level to support the formula <syntaxhighlight lang=wfl inline>upkeep = full</syntaxhighlight>
* '''traits''' - a list of the trait IDs
* '''extra_recruit'''
* '''advances_to'''
* '''status''' - a list of active statuses
* '''side_number'''
* '''cost'''
* '''upkeep'''
* '''loyal''' - a constant 0 to support the formula <syntaxhighlight lang=wfl inline>upkeep = loyal</syntaxhighlight>
* '''hidden'''
* '''petrified''' - true if the unit has the '''petrified''' status
* '''resting'''
* '''role'''
* '''race'''
* '''gender'''
* '''variation'''
* '''zoc'''
* '''alignment'''
* '''facing'''
* '''resistance''', '''movement_cost''', '''vision_cost''', '''jamming_cost''', '''defense''' - {{DevFeature1.15|3}} Maps containing the basic movetype data. The '''defense''' and '''resistance''' maps contain the actual defense and resistance values, rather than the values specified in the WML, so you do not need to subtract them from 100.
* '''flying''' {{DevFeature1.15|3}}
* '''vars''' - WFL variables owned by the unit, which can be set and used by FormulaAI
* '''wml_vars''' - the WML variables stored in the unit
* '''n''', '''s''', '''ne''', '''se''', '''nw''', '''sw''', '''lawful''', '''chaotic''', '''neutral''', '''liminal''', '''male''', '''female''' - these are all defined to be the equivalent string so that, for example, you can write a formula like <syntaxhighlight lang=wfl inline>alignment = liminal and gender = female</syntaxhighlight> without needing to quote the alignment and gender strings.

== A Note about Re-Using the Same Attribute ==
You are limited to having each attribute, such as '''id''', appear once or less in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:

<syntaxhighlight lang='wml'>
[kill]
[not]
id=Gwiti Ha'atel
[/not]
[not]
id=Tanar
[/not]
[/kill]
</syntaxhighlight>

And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:

<syntaxhighlight lang='wml'>
[kill]
id=Gwiti Ha'atel
[or]
id=Tanar
[/or]
[/kill]
</syntaxhighlight>

== Tutorial ==

* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

StandardUnitFilter

2023-03-24T14:06:36Z

Toranks: ability support commas

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering units.

When a unit filter is applied to a map, first it applies to all units on the field,
based on their coordinates.
Next it applies to units in the recall list.
This is important to remember as it means, for example,
that the tag '''[kill]''' can be used to kill units in the recall list.

You can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables

The term [[StandardUnitFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardUnitFilter]] needs to be included in a [filter] tag. But many tags take the [[StandardUnitFilter]] directly as an argument, like [kill] and [have_unit]. See [[Special:WhatLinksHere/StandardUnitFilter]] for tags which can contain a StandardUnitFilter.

__TOC__

The following attributes and sub-tags are allowed:

* '''id''': unit matches the given id. This is the same as ''id'' in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this (see [[SingleUnitWML]]). id= can be a comma-separated list, every unit with one of these ids matches.
* '''speaker''': alias for id (no comma-separated list supported)
* '''type''': matches the unit's type name (can be a list of types)
* '''type_adv_tree''': {{DevFeature1.13|7}} matches the type name of the unit and all its advancements (can be a list)
* '''race''': the race of the unit type. This can be a comma-separated list; the unit's race must match one of the given races. Mainline races are listed in data/core/units.cfg 
* '''variation''': the unit type variation id (can be a list of variation ids)
* '''has_variation''': matches if the unit type for the unit defines at least one of the variation ids provided as a comma-separated list
* '''upkeep''': {{DevFeature1.15|3}} The upkeep of the unit. Can be either a non-negative number or one of the special values ''loyal'', ''free'', ''full''. Note that while ''loyal'' and ''free'' are synonymous with an upkeep of 0, the value ''full'' is not synonymous with any single numeric value – it is equivalent to <code>$this_unit.level</code>.
* '''ability''': unit has an ability with the given id; see [[AbilitiesWML]]. This can be a comma-separated list.
* '''ability_type''': {{DevFeature1.13|7}} unit has an ability with the given type (tag name) - eg, ''ability_type=heals'' will match a unit with any healing ability.
* '''ability_type_active''': {{DevFeature1.13|8}} unit has an ''active'' ability with the given type (tag name).
* '''ability_id_active''': {{DevFeature1.15|13}} unit has an ''active'' ability with the given id; see [[AbilitiesWML]]
* '''trait''': {{DevFeature1.13|8}} This can be a comma-separated list. The unit must have at least one of the specified traits.
* '''status''': {{DevFeature1.13|0}} matches if the unit has the specified status active. This can be a comma-separated list, in which case the unit will match as long as it has one of the listed statuses active (note: possible statuses are listed on the [[SingleUnitWML]] page).
* '''side''': the unit is on the given side (can be a list)
* '''has_weapon''': the unit has a weapon with the given name {{DevFeature1.13|5}} Now deprecated
* '''[has_attack]''': {{DevFeature1.13|5}} the unit has a weapon matching the [[StandardWeaponFilter]]. If this is present, '''has_weapon''' is ignored.
* '''canrecruit''': yes if the unit can recruit (i.e. is a leader)
* '''gender''': female if the unit is female rather than the default of male
* '''role''': the unit has been assigned the given role; see '''[role]''', [[InternalActionsWML]]
* '''level''': the level of the unit (this can be a comma-separated list).
* '''defense''': current defense of the unit on current tile (chance to hit %, like in movement type definitions)
* '''movement_cost''': current movement cost of the unit on current tile. Can be a number, range, or comma separated range.
* '''x,y''': the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
* '''find_in''': name of an array or container variable; if present, the unit will not match unless a unit with the same '''id''' is already stored in the variable
* '''[filter_vision]''': this tests whether or not the unit is currently visible
** '''visible''': yes or no, default yes. When "yes", this matches units that are not obscured by fog or shroud, and that are not hiding (via the {{tag|AbilitiesWML|hides}} ability). When "no", this matches units that are obscured by fog or shroud, or that are hiding.
** [[StandardSideFilter]] tags and keys. Filter for who may be able to see (or not see) the unit. If there is *at least one* matching side which can see the unit then the filter matches, and otherwise it fails to match.
* '''[filter_wml]''': Converts the unit to WML (as if by '''[store_unit]''') and tests it against a [[FilterWML#Filtering_on_WML_data|WML filter]]. For a list of things in the WML that could be filtered on, see [[SingleUnitWML]] or open a saved game in a text editor. Note that this is slower than other methods, so if possible it's better to use other filter keys and tags; however, if the WML filter contains only a child '''[variables]''', then the unit is not converted to WML and the filter is matched only against the unit's variables (which are already WML).
* '''[and]''': an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. ''Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.''
* '''[or]''': an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
* '''[filter_adjacent]''' with a StandardUnitFilter as argument; do not use a [filter] tag. If present the correct number of adjacent units must match this filter.
**'''StandardUnitFilter''' tags and keys
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[StandardLocationFilter#Directions|notes]])
** '''is_enemy''': a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
** '''$other_unit''': {{DevFeature1.13|2}} Within [filter_adjacent], the special variable $other_unit refers to the filtered unit from the enclosing filter, while $this_unit refers (as with all StandardUnitFilters) to the unit being filtered on.
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
*'''[filter_side]''': The currently filtered unit's side must match this [[StandardSideFilter]] for the unit to match.
**[[StandardSideFilter]] tags and keys
* '''formula''': A formula using [[Wesnoth Formula Language]]. The <tt>self</tt> variable is set to the current $this_unit, and the formula should return a boolean. If it returns 0, the filter does not match. Otherwise, the filter does match. {{DevFeature1.13|5}} If the filter has a secondary unit, the formula can access it using the <code>other</code> variable. Both the unit and the secondary unit are a '''unit object''', with keys documented [[#Wesnoth_Formula_Language|below]]. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
* '''lua_function''': the name of a [[LuaWML|Lua]] function in the global environment that takes a unit as an argument and returns true if the given unit matches the filter. {{DevFeature1.13|5}} Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

== Wesnoth Formula Language ==

When using the '''formula''' key, the '''self''' and (if present) '''other''' objects support the following keys:

* '''x''', '''y''', '''loc''' - the latter is a '''location object''' such as what would be returned from [[Wesnoth_Formula_Language#loc|loc()]].
* '''id'''
* '''type'''
* '''name'''
* '''usage'''
* '''canrecruit''', '''leader'''
* '''undead''' - true if the unit has the ''not_living'' status
* '''attacks''' - a list of '''[[FilterWML#Filtering_Weapons|weapon objects]]'''
* '''abilities''' - a list of the ability IDs the unit possesses
* '''hitpoints''', '''max_hitpoints'''
* '''experience''', '''max_experience'''
* '''moves''', '''max_moves'''
* '''attacks_left''', '''max_attacks'''
* '''level''', '''full''' - '''full''' refers to the unit's level to support the formula <syntaxhighlight lang=wfl inline>upkeep = full</syntaxhighlight>
* '''traits''' - a list of the trait IDs
* '''extra_recruit'''
* '''advances_to'''
* '''status''' - a list of active statuses
* '''side_number'''
* '''cost'''
* '''upkeep'''
* '''loyal''' - a constant 0 to support the formula <syntaxhighlight lang=wfl inline>upkeep = loyal</syntaxhighlight>
* '''hidden'''
* '''petrified''' - true if the unit has the '''petrified''' status
* '''resting'''
* '''role'''
* '''race'''
* '''gender'''
* '''variation'''
* '''zoc'''
* '''alignment'''
* '''facing'''
* '''resistance''', '''movement_cost''', '''vision_cost''', '''jamming_cost''', '''defense''' - {{DevFeature1.15|3}} Maps containing the basic movetype data. The '''defense''' and '''resistance''' maps contain the actual defense and resistance values, rather than the values specified in the WML, so you do not need to subtract them from 100.
* '''flying''' {{DevFeature1.15|3}}
* '''vars''' - WFL variables owned by the unit, which can be set and used by FormulaAI
* '''wml_vars''' - the WML variables stored in the unit
* '''n''', '''s''', '''ne''', '''se''', '''nw''', '''sw''', '''lawful''', '''chaotic''', '''neutral''', '''liminal''', '''male''', '''female''' - these are all defined to be the equivalent string so that, for example, you can write a formula like <syntaxhighlight lang=wfl inline>alignment = liminal and gender = female</syntaxhighlight> without needing to quote the alignment and gender strings.

== A Note about Re-Using the Same Attribute ==
You are limited to having each attribute, such as '''id''', appear once or less in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:

<syntaxhighlight lang='wml'>
[kill]
[not]
id=Gwiti Ha'atel
[/not]
[not]
id=Tanar
[/not]
[/kill]
</syntaxhighlight>

And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:

<syntaxhighlight lang='wml'>
[kill]
id=Gwiti Ha'atel
[or]
id=Tanar
[/or]
[/kill]
</syntaxhighlight>

== Tutorial ==

* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

DebuggingCampaigns

2023-03-23T03:30:51Z

Toranks: /* Things to check when your scenario doesn't load */

"Debugging" means to fix by removing errors. Here are some ideas to help you when you are building a campaign (or other add-on) and need to fix it.

== Instructions also useful for users reporting bugs ==

=== Fully clearing a corrupted cache ===

Sometimes the cache can get corrupted, in Wesnoth 1.14 this seems to be the cause of `Undefined macro in #ifver/#ifnver first argument: 'WESNOTH_VERSION'` errors. In this case, please purge the cache with the button in Preferences, General, Cache (at the bottom of the General tab), labelled Purge.

== Tips ==

Use F5 in main game menu to reload WML code and invalidate cache. By this way you save time on rebooting game each time you change map or WML code.

Always backup your work. Use a DVCS (for example Git), so that you can revert any added or deleted code, and to check the differences between versions. Even without a DVCS, you can comment out part of the WML code by prefixing it with "#", and later uncomment it again.

== Things to check when your scenario doesn't load ==

*Do the id tags match exactly? Does the id in the caller script have the same case (lowercase/uppercase) as the scenario's id?

*Is the ".cfg" extension appended to the script filename?

*Is the script in the right location (usually ~add-ons/YOUR_ADDON/scenarios)

*Is it really a scenario load problem? Maybe the _main.cfg file isn't being loaded correctly.

*Are all the linking tags spelled correctly? (first_scenario=???, next_scenario=???, id=???)

*If you're using the template, did you remember to change all include and file paths to match your setup?

*Is another downloaded add-on breaking your version of the game or conflicting with your content?

*Do you have read permissions on your scripts?

== Other tips ==

A recommended approach by zookeeper is to remove half your code, and try to load your add-on. If the error is gone, you know it's in the half you removed. Take whichever half has the error, and keep removing half of what remains until you isolate the error.

== See Also: ==

*[[BuildingCampaigns]]
*[[AddonStructure]]

[[Category:Create]]

LuaWML/Reorganization

2023-03-20T19:50:20Z

Toranks: errata unit > units

This is a proposal to clean up and reorganize the existing set of Lua functions, helpers, tables, and proxy tables into a coherent, organized API, separated by category. The global wesnoth table would be the access point for the API categories, with subtables for each category within it from which the specific API item can be accessed (these subtables will essentially each represent a namespace). The idea would be to deprecate, but not immediately remove, the old access points, keeping them as valid aliases for a few versions to ensure backwards compatibility for developers and content creators and allowing them time to switch over.

The status of this document is currently an unapproved draft proposal pending discussion, consensus, and implementation. If and when these changes are implemented, [[LuaWML]] should be kept intact to (a) temporarily serve as documentation for the deprecated access points and (b) permanently describe the [lua] tag and its usage. The new "Lua API" should then be documented on its own page by the same name.

Some portions of the original proposal have already been implemented (though not always in precisely the proposed manner). These portions have been removed from this document; see the page history for more information on removed portions.

Most names will remain the same, but some will be changed for consistency (ex: anything previously referring to a "tile" now refers to a "hex"), accuracy (ex: "theme_items" has nothing to do with themes or items), or because their category makes part of their name redundant (ex: "wesnoth.get_unit" is now "wesnoth.units.get")

Note also that the metatable functions are planned to be modified to no longer require a table to be passed in for use, and simply return a proxy table for whatever kind of metatable is being created, and as such, their names will be radically changed in this proposal to reflect their primary purpose (to get a proxy table which behaves a certain way). This also raises the question of why exactly certain data need to have a proxy returned from some creation function (such as the proxy for working with WML variables), and certain others are available through direct access to proxy tables (such as sides, game config, current, etc.), and others yes are modified through getters and/or setters despite being heavily id-based and thus prime candidates for proxy table usage (such as traits and eras). There is also the question of missing functionality and providing access to data which should be available but is not. These topics can and should be discussed and fleshed out as well, but are beyond the current scope of this document, which is to perform a one-to-one reorganization of existing functionality.

In addition, the author of this proposal is very much aware that there are likely to be a great deal of differing opinions on how such a reorganization should take place, and therefore a [https://forums.wesnoth.org/viewtopic.php?f=10&t=44792 discussion has been opened on the forum]. Specific topics that are not set in stone are:
*Whether ALL API items should be within a category
*Whether the wesnoth table should, indeed, be the ONLY global table in the API
*Whether there should be a "misc" category for stuff that doesn't fit nicely anywhere else
*The specific names and categorizations of each specific API item
*Should the scope be expanded to drop functions and proxies which no longer make sense?
*Should the scope be expanded to modify the behavior of existing functions or proxies to make things more consistent?
*Pretty much anything and everything else about this proposal, indeed, all the way down to "should we even DO this at all?"

The categories and names being proposed are as follows:

== string ==
APIs for manipulation of strings
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.textdomain
|wesnoth.string.textdomain
|
|}

== output ==
APIs for the output of text messages
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.message
|wesnoth.output.message
|
|-
|wesnoth.clear_messages
|wesnoth.output.clear_messages
|
|-
|wesnoth.log
|wesnoth.output.log
|
|}

== sound ==
APIs relating to sound
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.play_sound
|wesnoth.sound.play
|
|-
|wesnoth.set_music
|wesnoth.sound.set_music
|wesnoth.music.set or wesnoth.music.play?
|-
|wesnoth.add_sound_source
|wesnoth.sound.add_source
|
|-
|wesnoth.remove_sound_source
|wesnoth.sound.remove_source
|
|-
|wesnoth.get_sound_source
|wesnoth.sound.get_source
|
|}

== map ==
APIs for working with the game map
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_map_size
|wesnoth.map.get_size
|
|-
|wesnoth.get_terrain
|wesnoth.map.get_terrain
|
|-
|wesnoth.set_terrain
|wesnoth.map.set_terrain
|
|-
|wesnoth.get_locations
|wesnoth.map.get_locations
|
|-
|wesnoth.get_villages
|wesnoth.map.get_villages
|
|-
|wesnoth.get_village_owner
|wesnoth.map.get_village_owner
|
|-
|wesnoth.set_village_owner
|wesnoth.map.set_village_owner
|
|-
|wesnoth.match_location
|wesnoth.map.location_matches
|
|-
|wesnoth.add_fog
|wesnoth.map.add_fog
|
|-
|wesnoth.remove_fog
|wesnoth.map.remove_fog
|
|-
|wesnoth.get_time_of_day
|wesnoth.map.get_time_of_day
|
|-
|wesnoth.add_time_area
|wesnoth.map.add_time_area
|
|-
|wesnoth.remove_time_area
|wesnoth.map.remove_time_area
|
|-
|wesnoth.get_starting_location
|wesnoth.map.get_side_starting_location
|
|-
|wesnoth.find_path
|wesnoth.map.find_path
|
|-
|wesnoth.find_vacant_tile
|wesnoth.map.find_vacant_hex
|
|-
|wesnoth.find_reach
|wesnoth.map.find_reach
|
|-
|wesnoth.find_cost_map
|wesnoth.map.find_cost_map
|
|-
|helper.distance_between
|wesnoth.map.distance_between
|
|-
|helper.adjacent_tiles
|wesnoth.map.adjacent_hex_iterator
|
|}

== file ==
APIs for working with files
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.dofile
|wesnoth.file.run
|Should this remain as "dofile", which is the standard name used by lua?
|-
|wesnoth.require
|wesnoth.file.require
|
|-
|wesnoth.read_file
|wesnoth.file.read
|
|-
|wesnoth.get_image_size
|wesnoth.file.image_size
|
|-
|wesnoth.have_file
|wesnoth.file.exists
|
|}

== game ==
APIs for working with game states and data
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.game_config
|wesnoth.game.config
|
|-
|wesnoth.get_era
|wesnoth.game.get_era
|Should this be somewhere else? If so, where?
|-
|wesnoth.current
|wesnoth.game.current
|
|-
|wesnoth.synchronize_choice
|wesnoth.game.synchronize
|
|-
|wesnoth.set_next_scenario
|wesnoth.game.set_next_scenario
|Should this be somewhere else? If so, where?
|-
|wesnoth.name_generator
|wesnoth.game.name_generator
|Should this be somewhere else? If so, where?
|-
|wesnoth.compare_versions
|wesnoth.game.compare_versions
|Should this be somewhere else? If so, where?
|-
|wesnoth.get_time_stamp
|wesnoth.game.get_time_stamp
|Should this be somewhere else? If so, where?
|-
|wesnoth.get_terrain_info
|wesnoth.game.get_terrain_info
|Should this be in map?
|-
|wesnoth.simulate_combat
|wesnoth.game.simulate_combat
|Should this be in unit?
|-
|wesnoth.get_traits
|wesnoth.game.get_traits
|Should this be in unit?
|-
|wesnoth.races
|wesnoth.game.races
|Should this be somewhere else? If so, where?
|-
|wesnoth.game_events
|wesnoth.game.events
|Should this be somewhere else? If so, where?
|}

== formula ==
APIs for working with [[Wesnoth Formula Language]]
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.eval_formula
|wesnoth.formula.evaluate
|
|-
|wesnoth.compile_formula
|wesnoth.formula.compile
|
|}

== math ==
Mathematical APIs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.random
|wesnoth.math.random
|
|-
|helper.rand
|wesnoth.math.randvar
|
|-
|helper.round
|wesnoth.math.round
|
|-
|helper.shuffle
|wesnoth.math.shuffle
|
|}

== action ==
APIs for working with [[ActionWML|WML actions]]
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.fire
|wesnoth.action.execute
|
|-
|wesnoth.wml_actions
|wesnoth.action.tags
|
|-
|helper.set_wml_action_metatable
|wesnoth.action.get_execution_table
|
|}

== event ==
APIs for working with [[EventWML|WML events]]
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.fire_event
|wesnoth.event.fire
|
|-
|wesnoth.fire_event_by_id
|wesnoth.event.fire_by_id
|
|-
|wesnoth.add_event_handler
|wesnoth.event.add_handler
|
|-
|wesnoth.remove_event_handler
|wesnoth.event.remove_handler
|
|}

== conditional ==
APIs for working with [[ConditionalActionsWML|WML conditionals]]
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.wml_conditionals
|wesnoth.conditional.tags
|
|-
|wesnoth.eval_conditional
|wesnoth.conditional.evaluate
|
|}

== effect ==
APIs for working with [[EffectWML|WML effects]]
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.effects
|wesnoth.effect.types
|
|}

InterfaceActionsWML

2023-03-07T09:53:58Z

Toranks: /* [set_menu_item] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [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]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. 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. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''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 ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''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.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'. The full list of color names may be found in Pango's [https://github.com/GNOME/pango/blob/main/tools/rgb.txt rgb.txt] file.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''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'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
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. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''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. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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 [[StandardLocationFilter]] similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[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.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [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. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [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-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [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
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
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 ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
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

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter]).
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
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.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
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. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''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.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor, measured as a multiple of the base zoom.
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

StandardUnitFilter

2023-02-27T08:16:13Z

Toranks: movement_cost support list and range

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering units.

When a unit filter is applied to a map, first it applies to all units on the field,
based on their coordinates.
Next it applies to units in the recall list.
This is important to remember as it means, for example,
that the tag '''[kill]''' can be used to kill units in the recall list.

You can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables

The term [[StandardUnitFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardUnitFilter]] needs to be included in a [filter] tag. But many tags take the [[StandardUnitFilter]] directly as an argument, like [kill] and [have_unit]. See [[Special:WhatLinksHere/StandardUnitFilter]] for tags which can contain a StandardUnitFilter.

__TOC__

The following attributes and sub-tags are allowed:

* '''id''': unit matches the given id. This is the same as ''id'' in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this (see [[SingleUnitWML]]). id= can be a comma-separated list, every unit with one of these ids matches.
* '''speaker''': alias for id (no comma-separated list supported)
* '''type''': matches the unit's type name (can be a list of types)
* '''type_adv_tree''': {{DevFeature1.13|7}} matches the type name of the unit and all its advancements (can be a list)
* '''race''': the race of the unit type. This can be a comma-separated list; the unit's race must match one of the given races. Mainline races are listed in data/core/units.cfg 
* '''variation''': the unit type variation id (can be a list of variation ids)
* '''has_variation''': matches if the unit type for the unit defines at least one of the variation ids provided as a comma-separated list
* '''upkeep''': {{DevFeature1.15|3}} The upkeep of the unit. Can be either a non-negative number or one of the special values ''loyal'', ''free'', ''full''. Note that while ''loyal'' and ''free'' are synonymous with an upkeep of 0, the value ''full'' is not synonymous with any single numeric value – it is equivalent to `$this_unit.level`.
* '''ability''': unit has an ability with the given id; see [[AbilitiesWML]]
* '''ability_type''': {{DevFeature1.13|7}} unit has an ability with the given type (tag name) - eg, ''ability_type=heals'' will match a unit with any healing ability.
* '''ability_type_active''': {{DevFeature1.13|8}} unit has an ''active'' ability with the given type (tag name).
* '''ability_id_active''': {{DevFeature1.15|13}} unit has an ''active'' ability with the given id; see [[AbilitiesWML]]
* '''trait''': {{DevFeature1.13|8}} This can be a comma-separated list. The unit must have at least one of the specified traits.
* '''status''': {{DevFeature1.13|0}} matches if the unit has the specified status active. This can be a comma-separated list, in which case the unit will match as long as it has one of the listed statuses active (note: possible statuses are listed on the [[SingleUnitWML]] page).
* '''side''': the unit is on the given side (can be a list)
* '''has_weapon''': the unit has a weapon with the given name {{DevFeature1.13|5}} Now deprecated
* '''[has_attack]''': {{DevFeature1.13|5}} the unit has a weapon matching the [[StandardWeaponFilter]]. If this is present, '''has_weapon''' is ignored.
* '''canrecruit''': yes if the unit can recruit (i.e. is a leader)
* '''gender''': female if the unit is female rather than the default of male
* '''role''': the unit has been assigned the given role; see '''[role]''', [[InternalActionsWML]]
* '''level''': the level of the unit (this can be a comma-separated list).
* '''defense''': current defense of the unit on current tile (chance to hit %, like in movement type definitions)
* '''movement_cost''': current movement cost of the unit on current tile. Can be a number, range, or comma separated range.
* '''x,y''': the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
* '''find_in''': name of an array or container variable; if present, the unit will not match unless a unit with the same '''id''' is already stored in the variable
* '''[filter_vision]''': this tests whether or not the unit is currently visible
** '''visible''': yes or no, default yes. When "yes", this matches units that are not obscured by fog or shroud, and that are not hiding (via the {{tag|AbilitiesWML|hides}} ability). When "no", this matches units that are obscured by fog or shroud, or that are hiding.
** [[StandardSideFilter]] tags and keys. Filter for who may be able to see (or not see) the unit. If there is *at least one* matching side which can see the unit then the filter matches, and otherwise it fails to match.
* '''[filter_wml]''': Converts the unit to WML (as if by '''[store_unit]''') and tests it against a [[FilterWML#Filtering_on_WML_data|WML filter]]. For a list of things in the WML that could be filtered on, see [[SingleUnitWML]] or open a saved game in a text editor. Note that this is slower than other methods, so if possible it's better to use other filter keys and tags; however, if the WML filter contains only a child '''[variables]''', then the unit is not converted to WML and the filter is matched only against the unit's variables (which are already WML).
* '''[and]''': an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. ''Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.''
* '''[or]''': an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
* '''[filter_adjacent]''' with a StandardUnitFilter as argument; do not use a [filter] tag. If present the correct number of adjacent units must match this filter.
**'''StandardUnitFilter''' tags and keys
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[StandardLocationFilter#Directions|notes]])
** '''is_enemy''': a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
** '''$other_unit''': {{DevFeature1.13|2}} Within [filter_adjacent], the special variable $other_unit refers to the filtered unit from the enclosing filter, while $this_unit refers (as with all StandardUnitFilters) to the unit being filtered on.
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
*'''[filter_side]''': The currently filtered unit's side must match this [[StandardSideFilter]] for the unit to match.
**[[StandardSideFilter]] tags and keys
* '''formula''': A formula using [[Wesnoth Formula Language]]. The <tt>self</tt> variable is set to the current $this_unit, and the formula should return a boolean. If it returns 0, the filter does not match. Otherwise, the filter does match. {{DevFeature1.13|5}} If the filter has a secondary unit, the formula can access it using the <code>other</code> variable. Both the unit and the secondary unit are a '''unit object''', with keys documented [[#Wesnoth_Formula_Language|below]]. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
* '''lua_function''': the name of a [[LuaWML|Lua]] function in the global environment that takes a unit as an argument and returns true if the given unit matches the filter. {{DevFeature1.13|5}} Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

== Wesnoth Formula Language ==

When using the '''formula''' key, the '''self''' and (if present) '''other''' objects support the following keys:

* '''x''', '''y''', '''loc''' - the latter is a '''location object''' such as what would be returned from [[Wesnoth_Formula_Language#loc|loc()]].
* '''id'''
* '''type'''
* '''name'''
* '''usage'''
* '''canrecruit''', '''leader'''
* '''undead''' - true if the unit has the ''not_living'' status
* '''attacks''' - a list of '''[[FilterWML#Filtering_Weapons|weapon objects]]'''
* '''abilities''' - a list of the ability IDs the unit possesses
* '''hitpoints''', '''max_hitpoints'''
* '''experience''', '''max_experience'''
* '''moves''', '''max_moves'''
* '''attacks_left''', '''max_attacks'''
* '''level''', '''full''' - '''full''' refers to the unit's level to support the formula <syntaxhighlight lang=wfl inline>upkeep = full</syntaxhighlight>
* '''traits''' - a list of the trait IDs
* '''extra_recruit'''
* '''advances_to'''
* '''status''' - a list of active statuses
* '''side_number'''
* '''cost'''
* '''upkeep'''
* '''loyal''' - a constant 0 to support the formula <syntaxhighlight lang=wfl inline>upkeep = loyal</syntaxhighlight>
* '''hidden'''
* '''petrified''' - true if the unit has the '''petrified''' status
* '''resting'''
* '''role'''
* '''race'''
* '''gender'''
* '''variation'''
* '''zoc'''
* '''alignment'''
* '''facing'''
* '''resistance''', '''movement_cost''', '''vision_cost''', '''jamming_cost''', '''defense''' - {{DevFeature1.15|3}} Maps containing the basic movetype data. The '''defense''' and '''resistance''' maps contain the actual defense and resistance values, rather than the values specified in the WML, so you do not need to subtract them from 100.
* '''flying''' {{DevFeature1.15|3}}
* '''vars''' - WFL variables owned by the unit, which can be set and used by FormulaAI
* '''wml_vars''' - the WML variables stored in the unit
* '''n''', '''s''', '''ne''', '''se''', '''nw''', '''sw''', '''lawful''', '''chaotic''', '''neutral''', '''liminal''', '''male''', '''female''' - these are all defined to be the equivalent string so that, for example, you can write a formula like <syntaxhighlight lang=wfl inline>alignment = liminal and gender = female</syntaxhighlight> without needing to quote the alignment and gender strings.

== A Note about Re-Using the Same Attribute ==
You are limited to having each attribute, such as '''id''', appear once or less in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:

<syntaxhighlight lang='wml'>
[kill]
[not]
id=Gwiti Ha'atel
[/not]
[not]
id=Tanar
[/not]
[/kill]
</syntaxhighlight>

And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:

<syntaxhighlight lang='wml'>
[kill]
id=Gwiti Ha'atel
[or]
id=Tanar
[/or]
[/kill]
</syntaxhighlight>

== Tutorial ==

* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

Talk:SyntaxWML

2023-02-24T21:14:13Z

Toranks: /* Empty Values */

== Empty Values ==

The workaround I posted was helpful to check whether a variable is initialized:

[variable]
name=to_be_tested
equals=$empty
[/variable]

(tested with wesnoth 1.2.5)

Interesting it doesn't work with [set_variable]format=.

[[User:Meriton|Meriton]] 15:49, 15 July 2007 (CEST)

In fact, as long as there's whitespace after it, no pipes would also be fine.

The pipe is an optional part of the syntax used to disambiguate where the variable name ends if it's not otherwise clear.

What should happen when the game processes $metal_reserve$attacker_side|| is:

1. Substitute in $attacker_side| to get eg $metal_reserve4|

2. Substitute in $metal_reserve4| to get 12 or whatever.

Substitutions always happen from right to left.

And if there's a pipe, the substitution removes it.

So having only 1 pipe would mean that $metal_reserve|stuff tries to read the variable metal_reserve4stuff instead of metal_reserve4 which is likely not the intention. Thus, always better to match the number of pipes to the number of $'s in this type of situation, unless you know that's not what you want.

https://discord.com/channels/231976805987385345/442775044590927873/1078750511475470396

Talk:SyntaxWML

2023-02-24T21:13:39Z

Toranks: /* Empty Values */

== Empty Values ==

The workaround I posted was helpful to check whether a variable is initialized:

[variable]
name=to_be_tested
equals=$empty
[/variable]

(tested with wesnoth 1.2.5)

Interesting it doesn't work with [set_variable]format=.

[[User:Meriton|Meriton]] 15:49, 15 July 2007 (CEST)

In fact, as long as there's whitespace after it, no pipes would also be fine.
The pipe is an optional part of the syntax used to disambiguate where the variable name ends if it's not otherwise clear.
What should happen when the game processes $metal_reserve$attacker_side|| is:
1. Substitute in $attacker_side| to get eg $metal_reserve4|
2. Substitute in $metal_reserve4| to get 12 or whatever.
Substitutions always happen from right to left.
And if there's a pipe, the substitution removes it.
So having only 1 pipe would mean that $metal_reserve|stuff tries to read the variable metal_reserve4stuff instead of metal_reserve4 which is likely not the intention. Thus, always better to match the number of pipes to the number of $'s in this type of situation, unless you know that's not what you want.

https://discord.com/channels/231976805987385345/442775044590927873/1078750511475470396

CampaignWML

2023-02-03T20:20:32Z

Toranks:

{{WML Tags}}



This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.

==The [campaign] Tag==

The following keys and tags are recognized in '''[campaign]''' tags:
* '''id''': the internal campaign identifier used to classify saved games
* '''icon''': the image displayed in the campaign selection menu
* '''name''': (translatable) name displayed in the campaign selection menu
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)
* '''background''': {{DevFeature1.15|9}} the image used as a backdrop for the Campaigns menu (typically a high resolution image intended for displaying fullscreen in story screens). If blank or unspecified, a stock story background from core is used.
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
* '''description_alignment''': {{DevFeature1.13|3}} The text alignment of the description. Choose between "left" (default), "center", or "right".
* '''type''': campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".
* '''define'''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''', '''[textdomain]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''CAMPAIGN_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. (In the past, this tag was used to define common optional advancements, but that use is deprecated. There are now macros to add those advancements defined in [https://www.wesnoth.org/macro-reference.html#file:optional_unit_advancements.cfg data/core/macros/optional_unit_advancements.cfg].)
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [https://www.wesnoth.org/macro-reference.html#file:utils.cfg| Macro Reference]) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=.
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=
* '''[difficulty]''': {{DevFeature1.13|2}} specifies a single campaign difficulty. The following keys are accepted:
** '''define''': the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old ''difficulties'' list.
** '''image''': the image to display for this difficulty in the selection menu
** '''label''': a flavor label describing this difficulty. Displayed second after the image
** '''description''': a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.
** '''default''': whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.
** '''auto_markup''': {{DevFeature1.15|0}} By default, the description is shown in small, gray text within parentheses. Setting '''auto_markup=no''' disables these, so no markup will be applied implicitly. Any markup in '''description''' will be honored regardless of this setting.
* '''allow_difficulty_change''': Allows difficulty switching during an ongoing campaign. Default:yes
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]
* '''[options]''': {{DevFeature1.13|1}} Allows configuration options to be displayed to the user, see [[OptionWML]]
* '''rank''': a number that determines the order of campaigns in the campaign selection menu. Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.) {{DevFeature1.14|6}} a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.
* '''year''': shortcut for specifying both '''start_year''' and '''end_year''', for campaigns that happen inside a single calendar year. Ignored if '''start_year''' is given.
* '''[about]''': inserts your own credits into the game's list of credits. See [[CreditsWML]] for syntax.
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. {{DevFeature1.15|6}} This value is capped at 5000 (5 seconds).
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.
* '''[modify_unit_type]''': {{DevFeature1.15|2}} Applies minor modifications to existing unit types when this campaign is active. See entry in [[ModificationWML]] for list of possible attributes.
The following keys are additionally recognized in multiplayer:
* '''min_players''': Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.
* '''max_players''': Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either '''min_players''' or 2, whichever is higher.
* '''allow_era_choice''': Whether to allow era selection (when set to ''yes'') or hide it and use a default one when creating a game (when set to ''no''). Defaults to ''yes''.
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.

== See Also ==

* [[PreprocessorRef]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[PblWML]]

[[Category: WML Reference]]

ModificationWML

2023-02-03T20:20:16Z

Toranks:

{{WML Tags}}
== The [modification] toplevel tag ==

This tag describes an SP or MP modification. A modification is, practically speaking, a bunch of events which get included into the scenario if the modification is enabled.

The following keys/tags are recognized for '''[modification]''':

* '''id''': identifier for the modification. Must be unique.
* '''name''': the name of the modification, as displayed to the user.
* '''type''': where the modification will be available for playing. Possible values are ''sp'', ''mp'', and ''hybrid''.
* '''description''': a brief description for the modification.
* '''define'''='''''MODIFICATION_SYMBOL''''' when this addon is active, the preprocessor symbol '''''MODIFICATION_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the modification file from other modifications or campaigns. Only the tags '''[modification]''', '''[textdomain]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''MODIFICATION_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''MODIFICATION_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this modification.
* '''disallow_scenario''': a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this modification. Cannot be used in parallel with allow_scenario.
* '''allow_era''': same as allow_scenario, but for eras.
* '''disallow_era''': same as disallow_scenario, but for eras. Can't be used with allow_era.
* '''allow_modification''': same as allow_scenario, but for modifications.
* '''disallow_modification''': same as disallow_scenario, but for modifications. Can't be used with allow_modification.
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this modification regardless their dependencies.
* '''ignore_incompatible_era''': same as ignore_incompatible_scenario, but for eras.
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
* '''require_modification''': a boolean value; if set to yes, all players have to have this modification installed to join the game. Default no.
* '''addon_min_version''': {{DevFeature1.13|0}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
* '''[event]''': any [event] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled. See [[EventWML]].
* '''[lua]''': any [lua] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled.
* '''[options]''': custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.
* '''[modify_unit_type]''' {{DevFeature1.15|2}}: Changes a unit type while this modification is active. This tag is also supported in [campaign] and [era]. The supported attributes are:
** '''type''' : the id of the unit type to change.
** '''set_experience''' : changes the unit type's max experience.
** '''set_cost''' : changes the unit type's recruit cost.
** '''set_advances_to''' : changes the unit type's advancements.
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

== The [resource] toplevel tag ==

{{DevFeature1.13|2}}

The '''[resource]''' toplevel tag is similar to [modification] in that it contains [event] and [lua] tags which are then copied into the scenario. However, unlike [modification], resources defined this way are completely hidden from the user. To load a resource, use '''[load_resource] id=<resource id>''' in [scenario], [multiplayer], [era], [campaign], [modification], or [resource].

WML Abilities

2023-02-02T12:11:40Z

Toranks: Changed unnecessary things, as [leadership] and [unstore_unit], to keep it simple and understandable

The more complex abilities and weapon specials often consist of two parts:
* The ability / weapon special, which is only a dummy to provide a description and to see whether a unit has this ability. It is something one gives to a unit. Mainline abilities / weapon specials only need this part.
* One or multiple [event]s, which make things happen. These [event]s must be added to the game ''explicitly'', in addition to the unit with the ability / weapon special!

How to include [event]s?
* Add it directly to the scenario file.
* Add it directly to the [era].
* Add it inside a [unit_type] definition.
If you add it both via an [era] and and the scenario, they are added twice … i.e. the pickpocket ability would give the gold twice! To avoid that, give each event an '''id'''. This is even mandatory when adding it in a [unit_type].

Even better would be to use a [resource]. Resources have also an id, so there will never be duplicates:
* Instead of adding it to the scenario / era, you add the event code inside a [resource].
* The same way you read the scenario / era file, you also read the file containing the [resource] tag.
* In the scenario / era, use [[ModificationWML#The_.5Bresource.5D_toplevel_tag|load_resource]].

=== Knockback ===

When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense.

Use this to display the special correctly on the attacks you want:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense."
active_on=offense
[/dummy]
#enddef
</syntaxhighlight>

And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
<syntaxhighlight lang='wml'>
[event]
name=attacker hits
first_time_only=no

[filter_attack]
special_id=knockback
[/filter_attack]

[filter_second]
[not]
[filter_location]
terrain=*^V*
[/filter_location]
[/not]
[/filter_second]

[if]
[variable]
name=second_unit.hitpoints
greater_than=0
[/variable]

[store_locations]
[not]
[filter]
[/filter]
[/not]

[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$unit.facing
[/filter_adjacent_location]

variable=knockback_target_hex
[/store_locations]

[if]
[variable]
name=knockback_target_hex.length
greater_than=0
[/variable]

[then]
[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$knockback_target_hex.x,$knockback_target_hex.y
ignore_passability=no
[/teleport]

[if]
[have_unit]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/have_unit]

[then]
[sound]
name=fist.ogg
[/sound]

# the knockbacked unit doesn't seem to receive experience by default,
# so we need to add it manually
[store_unit]
[filter]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/filter]

kill=yes
variable=knockbacked
[/store_unit]

{VARIABLE_OP knockbacked.experience add $unit.level}

[unstore_unit]
variable=knockbacked
text= _ "knockback"
{COLOR_HARM}
advance=true
[/unstore_unit]

{CLEAR_VARIABLE knockbacked}
[/then]
[/if]
[/then]
[/if]

{CLEAR_VARIABLE knockback_direction,knockback_target_hex}
[/then]
[/if]
[/event]
</syntaxhighlight>

=== Charm ===

When a unit is hit with a ''charm'' attack, it instantly jumps to the attacker's side, and returns to its original side at the end of the turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

<syntaxhighlight lang='wml'>
#define CHARM FILTER WEAPON
[event]
name=attacker hits
# Works only as attacker.
# If you want to make a weapon special for this event, set:
# [dummy]active_on=offense, then the engine greys out the weapon special on defense.
first_time_only=no
id=charm_as_attacker

[filter]
{FILTER}
[/filter]

[filter_attack]
name={WEAPON}
# or special_id=charm, if you create a [dummy] weapon special
[/filter_attack]

[filter_second]
# If the leader is charmed, it might end the scenario,
# as the other side is now considered defeated without a leader.
# Better exclude leaders.
canrecruit=no
# If the unit would die from the damage,
# we should not interfere with the event.
formula="self.hitpoints > 0"
[/filter_second]

# Charm the unit
# Changing the side will also immediately stop the combat and grant both units XP
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[variables]
# to remember the original side
real_side=$second_unit.side
[/variables]
[status]
# optional, just to easier find the unit in the other event
charmed=yes
[/status]
side=$unit.side
moves=1
attacks_left=1
[/modify_unit]

[floating_text]
x,y=$x2,$y2
# po: short text, only displayed for a moment
text="" + _ "charm" + ""
[/floating_text]
[/event]

[event]
name=side turn end, scenario end
# Releasing the unit in the same turn has a few reasons:
# - a charmed unit cannot be charmed again
# - if the scenario ends, we can still correct the ownership
# - things like healing by allies work the usual way
first_time_only=no
id=charm_release

[store_unit]
[filter]
side=$side_number
status=charmed
[/filter]
variable=charmed_units
[/store_unit]

[foreach]
array=charmed_units
[do]
{VARIABLE this_item.side $this_item.variables.real_side}
{CLEAR_VARIABLE this_item.variables.real_side}
{CLEAR_VARIABLE this_item.status.charmed}
[unstore_unit]
variable=this_item
[/unstore_unit]
[/do]
[/foreach]

{CLEAR_VARIABLE charmed_units}
[/event]
#enddef
</syntaxhighlight>

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit having bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

<syntaxhighlight lang='wml'>
#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
moves=0
attacks_left=1
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special successfully hits an enemy unit, it gains a certain amount of gold.

To do this, use this code:

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_PICKPOCKET
# Canned definition of the pickpocket ability to be included in a
# [specials] clause.
# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_pickpocket
name= _ "pickpocket"
description= _ "Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
active_on=offense
[/dummy]
[/specials]
[/attack]

# event that creates a "pickpocket has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_pickpocket
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_pickpocket.variables.pickpocket_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_pickpocket
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_pickpocket}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=pickpocketer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=pickpocketed
mode=append
[/store_unit]
[if]
[variable]
name=pickpocketer.variables.pickpocket_has_worked
boolean_equals=yes
[/variable]
[then]
[gold]
side=$side_number
amount=2
[/gold]
[unstore_unit]
variable=pickpocketed
text="!"
{COLOR_HEAL}
[/unstore_unit]
[/then]
[/if]
{CLEAR_VARIABLE pickpocketer,pickpocketed}
[/event]
[+attack]
[+specials]
#enddef
</syntaxhighlight>

It can be placed after the [unit_type] tag, or in its own .cfg file.

To change the amount of gold given per hit, change
[gold]
side=$side_number
amount='''X'''
[/gold]
Where '''X''' is the amount of gold you want.

If you want the gold to be constant, given at the end of the turn if at least one of the attack hits, instead of '''X''' amount of gold per hit, change
[event]
'''name=attacker_hits'''
first_time_only=no</code>

to

[event]
'''name=attack_end'''
first_time_only=no

=== Soultaker ===

Any unit with this ability will gain an additional point of damage per strike every time it kills an enemy. Coder(s) unknown, made for Melon's Youkai faction (https://r.wesnoth.org/t20100).

To give a unit the ability, place the following in any .cfg file loaded by the campaign or era:

<syntaxhighlight lang='wml'>
#define ABILITY_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "This unit gains an additional point added to its melee damage whenever it kills a living unit."
[/dummy]
[/abilities]

[event]
name=die
first_time_only=no
[filter]
[not]
status=not_living
[/not]
[/filter]

[filter_second]
ability=soultaker
[/filter_second]

[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
[/unstore_unit]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
range=melee
increase_damage=1
[/effect]
[/object]
[/event]

[+abilities]
#enddef
</syntaxhighlight>

And the following in the unit's [abilities] tag:

{ABILITY_SOULTAKER}

=== Soultaker (weapon special) ===

Unit with this weapon special will gain an additional point of damage per strike for that weapon every time it kills an enemy with this attack. Coder Ravana, made for ageless era (https://r.wesnoth.org/t25274) based on previous ability.

To give a unit the weapon special, load the following code:

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_"This unit gains an additional point added to its damage whenever it kills a living unit."
[/dummy]
[/specials]
[/attack]

[event]
name=die
first_time_only=no
id=soultaker_event
[filter]
[not]
status=not_living
[/not]
[/filter]
[filter_second_attack]
special_id=soultaker
[/filter_second_attack]

[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
[/unstore_unit]
[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]
[effect]
apply_to=attack
name=$second_weapon.name
increase_damage=1
[/effect]
[/object]
[/event]
[+attack]
[+specials]
#enddef
</syntaxhighlight>

And the following in the attack's [specials] tag:

{WEAPON_SPECIAL_SOULTAKER}

=== Charm (Type 2) ===

An attack special. If the attack hits, and the target is level 0 or 1, the target is converted to the attacker's side. However, if it misses, the attacker is converted to the defender's side. Maintainer is krotop, made for Melon's Youkai faction (https://r.wesnoth.org/t22539)

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_CHARM
# Canned definition of the Charm ability to be included in a
# [specials] clause.

# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_charm
name= _ "charm"
description= _ "Turns a living level 1 or level 0 unit to your side. Beware, if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an enemy leader or a non-living creature."
apply_to=opponent
active_on=offense
[/dummy]

[/specials]
[/attack]

# event that creates a variable at the beginning of the fight to check if the attacker hit at least once by the end.
[event]
name=attack
first_time_only=no

[filter_attack]
special_id=weapon_charm
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=no
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}
[/event]

# event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no

[filter_attack]
special_id=weapon_charm
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}
[/event]

# event that shifts a unit to the other side
# if the defending unit
# - was not lvl1 or lvl0
# - and was not a recruiting unit
# - and was a not a "non-living" creature
# then :
# -> if the attacker missed all attacks, it goes to the defender side.
# -> if the attacker hit once at least, the defender goes to the attacker side.
[event]
name=attack_end
first_time_only=no

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=not_living
[/not]
[/filter_second]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=charmer
mode=append
[/store_unit]

[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=charmed
mode=append
[/store_unit]

[if]
[variable]
name=charmer.variables.charm_has_worked
boolean_equals=no
[/variable]
[then]
[set_variable]
name=charmer.side
value=$charmed.side
[/set_variable]
[unstore_unit]
variable=charmer
text="Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
[set_variable]
name=charmed.side
value=$charmer.side
[/set_variable]
[unstore_unit]
variable=charmed
text="Charmed!"
{COLOR_HEAL}
[/unstore_unit]
[/else]
[/if]

{CLEAR_VARIABLE charmer,charmed}
[/event]

[+attack]
[+specials]
#enddef
</syntaxhighlight>

== Works ==

Unit with ability ''works'' will produce 1 gold per turn.

Put this macro into you code before the last piece of code.
<syntaxhighlight lang='wml'>
#define ABILITY_WORKS
[works]
id=peasant_works
name="works"
description= _ "This unit produces 1 gold per turn."
[/works]
#enddef
</syntaxhighlight>

Put this event into your code.
<syntaxhighlight lang='wml'>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
ability=peasant_works
side=$side_number
[/filter]
variable=workers
[/store_unit]

[foreach]
array=workers
[do]
[gold]
side=$this_item.side
amount=1
[/gold]
[floating_text]
x,y=$this_item.x,$this_item.y
text=""+_"+1 gold"+""
[/floating_text]
[/do]
[/foreach]

{CLEAR_VARIABLE workers}
[/event]
</syntaxhighlight>

And give the unit the ability like this:
<syntaxhighlight lang='wml'>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</syntaxhighlight>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_MIND_FLAY
[mindflay]
id=mind_flay
name= _ "Mind Flay"
description= _ "When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
active_on=offense
[/mindflay]
#enddef
</syntaxhighlight>

Include these events into your scenario:
<syntaxhighlight lang='wml'>
[event]
name=attack
first_time_only=no
[filter_attack]
special_id=mind flay
[/filter_attack]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=mind flay
[/filter_attack]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[filter_attack]
special_id=mind flay
[/filter_attack]
{VARIABLE_OP second_unit.experience add -$hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]
</syntaxhighlight>

== Initiative ==

Initiative is an aura ability. Much like leadership, it affects adjacent allies but not the unit itself.

The ability is used in HttT by Li’sar, you can copy the code from [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Heir_To_The_Throne/utils/abilities.cfg data/campaigns/Heir_To_The_Throne/utils/abilities.cfg]

== Blitz ==

UtBS and TroW have with ''distract'' an ability, which lets adjacent units ignore the ZoC. It works similar to leadership and initiative, the bonus is valid ''while'' the unit is adjacent.

This ability does the same, but it works similar to healing: The bonus is applied at the beginning of the turn and still valid when not anymore being adjacent.

But it also differs from the way healing works for allied units:
* With healing, it is useful if you move your injured unit to an ally, so that it is adjacent at the healing time.
* With this ability, the unit who wants the bonus must be adjacent at the start of his own turn.

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ
[dummy]
id=blitz
name= _ "blitz"
description= _ "Allies that start their turn adjacent to this unit are granted skirmisher for that turn."
special_note= _ "Instead of healing other units, this unit grants temporarily skirmisher for allied units at the beginning of their turn."
active_on=offense
affect_self=no
affect_allies=yes
[affect_adjacent][/affect_adjacent]
[/dummy]
#enddef
</syntaxhighlight>

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ_EVENT
[event]
name=side turn
first_time_only=no

[modify_unit]
# The units adjacent to a unit with the blitz ability …
[filter]
side=$side_number
[filter_adjacent]
is_enemy=no
ability=blitz
[/filter_adjacent]
[/filter]

# … receive temporarily this ability.
[object]
duration=turn end
[effect]
apply_to=new_ability
[abilities]
{ABILITY_SKIRMISHER}
[/abilities]
[/effect]
[/object]
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

== Immune to drain or plague or poison ==

To make a unit immune to plague, poison or/and draining of life force, set the right [status] for this unit: One or multiple of '''unpoisonable''', '''undrainable''', '''unplagueable'''.

There are many ways to change a status, it can be set directly with [modify_unit], at recruitment via a [trait], or by giving the unit an [object]. In mainline, a [trait] is used to make undead units immune. Traits also have a name and description, which can be used to make it visible to the player that this unit is immune.

<syntaxhighlight lang='wml'>
#define TRAIT_UNDRAINABLE
# We make vampires undrainable with a trait.
# Traits show up in the help browser, thus they should have proper descriptions.
[trait]
id=undrainable
availability=musthave
male_name= _ "vampire"
female_name= _ "female^vampire"
description= _ "This unit’s life force cannot be drained."
help_text= _ "Vampires are like Undead immune to drain and plague, but still susceptible to poison. While this trait is usually seen among vampire units, other mythical beings have also been seen with it. Even some Mages managed to acquire it."
# vampire is not a good name for a trait, as you can give the trait to anybody
[effect]
apply_to=status
add=undrainable
[/effect]
[effect]
apply_to=status
add=unplagueable
[/effect]
[/trait]
#enddef
</syntaxhighlight>

When you define a new [unit'''_type'''], add to it:
{TRAIT_UNDRAINABLE}
num_traits=3 # if you still want it to get 2 other traits

In other cases, if you want to make unit immune, i.e. one from mainline, give it the trait another way:
<syntaxhighlight lang='wml'>
[event]
name=prerecruit
first_time_only=no
[filter]
type_adv_tree=Mage
[or]
race=elf
side=2
[/or]
[/filter]

[modify_unit]
[filter]
id=$unit.id
[/filter]
{TRAIT_UNDRAINABLE}

# Or without trait / object:
# [status]
# undrainable=yes
# [/status]
[/modify_unit]
[/event]
</syntaxhighlight>

== Whirlwind Attack ==

This attack is supposed to be an attack when you spin with your weapons in arms, hitting all nearby enemies, while they cannot counter. It should be used with the magical weapon special, because the spinning weapons are not easy to dodge and the player would pick to attack the unit with the lowest defence without it. It works with drain, slow and poison weapon specials. The attack is supposed to be attack-only, but it can be easily edited to work also on defence.

This is a pair of two macros, one is a weapon special that makes the enemy unable to counter (lowers the number of attacks by 10; for the case if there was a boss or something). The other one is an event that damages the units, that should be placed into every scenario where the unit appears (or the era), preferably through a macro.

This is the part that is the weapon special that marks it:
<syntaxhighlight lang='wml'>
[attacks] #This can be changed to a dummy tag if you don't want it to do anything.
id=whirlwind
name= _ "whirlwind"
description= _ "When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
value=0
apply_to=opponent
active_on=offense
[/attacks]
</syntaxhighlight>

This is the event:
<syntaxhighlight lang='wml'>
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=whirlwind
[/filter_attack]
{VARIABLE has_drain 0} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
{FOREACH weapon.specials.damage i}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain 1}
[/then]
[/if]
{NEXT i}
[if]
[variable]
name=weapon.specials.poison.id
equals=poison
[/variable]
[then]
{VARIABLE has_poison yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.slow.id
equals=slow
[/variable]
[then]
{VARIABLE has_slow yes}
[/then]
[/if]
[if]
[variable]
name=has_drain
equals=0
[/variable]
[else]
[store_unit] #We need to know how many units were drained, and what were their resistances
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not] #Undead are undrainable
race=undead
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
{FOREACH units i}
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($units[$i].resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($units[$i].resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($units[$i].resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($units[$i].resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($units[$i].resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($units[$i].resistance.impact*$weapon.damage)"}
[/case]
[/switch]
{NEXT i}
[store_unit] #Float the healed amount over the unit, like if it had drained
[filter] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1
[/filter]
variable=FLOATING_TEXT_temp
[/store_unit]
[unstore_unit]
variable=FLOATING_TEXT_temp
red,green,blue=0,255,0
text=$($healed_amount/200) #Operating with huge numbers because rounding is a problem
[/unstore_unit]
{CLEAR_VARIABLE FLOATING_TEXT_temp}
[heal_unit]
[filter]
x,y=$x1,&y1
[/filter]
amount=$($healed_amount/200)
animate=no
[/heal_unit]
{CLEAR_VARIABLE units,healed_amount}
[/else]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #If you want to use it in an era, use side=$unit.side instead
x,y=$x2,$y2
[/not]
[/filter]
[filter_second]
x,y=$x1,$y1
[/filter_second]
amount=$weapon.damage
damage_type=$weapon.type
fire_event=yes
experience=yes #You will have to think about this
poisoned=$has_poison #We have detected these two effects before
slowed=$has_slow
[/harm_unit]
{CLEAR_VARIABLE has_slow,has_poison,has_drain}
[/event]
</syntaxhighlight>

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

InterfaceActionsWML

2023-02-02T12:08:08Z

Toranks: /* [floating_text] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [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]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. 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. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''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 ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''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.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'. The full list of color names may be found in Pango's [https://github.com/GNOME/pango/blob/main/tools/rgb.txt rgb.txt] file.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''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'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
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. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''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. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[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.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [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. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [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-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [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
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
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 ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
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

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter]).
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
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.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
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. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''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.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

DirectActionsWML

2023-02-01T05:36:27Z

Toranks: /* [cancel_action] */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/SingleUnitWML filter_recall] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]''' (not sure on this one)
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' [event] in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an '''enter_hex'''/'''exit_hex''' [event], interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an '''enter_hex''' [event] on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an enter_hex [event] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

DirectActionsWML

2023-02-01T05:36:07Z

Toranks: /* [cancel_action] */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/SingleUnitWML filter_recall] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]''' (not sure on this one)
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' [event] in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an '''enter_hex'''/'''exit_hex''' event, interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an '''enter_hex''' [event] on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an enter_hex [event] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

DirectActionsWML

2023-02-01T05:34:58Z

Toranks: /* [cancel_action] */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/SingleUnitWML filter_recall] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]''' (not sure on this one)
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' events in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an '''enter_hex'''/'''exit_hex''' event, interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an [enter_hex] event on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an [enter_hex] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

DirectActionsWML

2023-02-01T05:32:27Z

Toranks: /* [cancel_action] */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/SingleUnitWML filter_recall] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]''' (not sure on this one)
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{EventWML|enter_hex}}/{{EventWML|exit_hex}} events in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an {{EventWML|enter_hex}}/{{EventWML|exit_hex}} event, interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an [enter_hex] event on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an [enter_hex] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

DirectActionsWML

2023-02-01T05:29:02Z

Toranks: /* [cancel_action] */ error on tag or old tag name

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/SingleUnitWML filter_recall] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]''' (not sure on this one)
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{tag|EventWML|enter_hex}}/{{tag|EventWML|exit_hex}} events in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an {{tag|EventWML|enter_hex}}/{{tag|EventWML|exit_hex}} event, interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an [enter_hex] event on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an [enter_hex] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

EffectWML

2023-01-31T18:01:07Z

Toranks: max_experience can use set key

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaWML/Units#wesnoth.effects]].
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
* '''max_attacks''': {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* '''vision''': {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* '''jamming''': {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* '''experience''': affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''vision_costs''': vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[vision_costs]''': a subtag that describes the new vision costs just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''jamming_costs''': jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''defense''': Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved.
** '''[defense]''': a subtag that describes the new defense just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''resistance''': Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage.
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''variation''': switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement], and cannot be combined with '''type''' in the same object due to a bug.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (boolean).
* '''profile''': customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster.
* '''image_mod''': modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* '''ellipse''': Change the image used for the unit's ellipse.
** '''ellipse''' : the new image to use. Can be set to "none" to disable the ellipse.
* '''halo''': Change the image used for the unit's halo.
** '''halo''': the new image to use.
* '''overlay''': Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* '''recall_cost''': {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* '''alignment''': {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* '''new_advancement''': {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* '''remove_advancement''': {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

=== Examples ===
== Effect: apply_to = new_animation ==
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.

[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y = 1,5
[/filter]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]

If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable = stored_unit
[/store_unit]
[set_variables]
name = stored_unit.modifications.object
[value]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable = stored_unit
[/unstore_unit]
[/event]

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

ReplayWML

2023-01-31T15:05:26Z

Toranks: Doesn't support standard location filter, only x,y position. I got confused with [find_path]

{{WML Tags}}
== The [command] tag ==

The '''[command]''' tag is used to specify an action in a replay. It has the following attributes:

* '''dependent''' if true, this command is not a lone-standing command and instead belongs to an earlier command, for example an advancement choice for an earlier attack command which issued an advancement.
* '''from_side''' the side which issued the command. Only present for dependent commands.
* '''sent''' used internally in networked mp, to know which commands were already sent to the other clients.
The following tags are recognized for dependent=no(default):
* '''[start]''': is used to initialize the replay so that generated random numbers can be saved.
* '''[move]''': the player moved a unit.
** '''x,y''': the path the unit walks.
** '''skip_sighted''': whether the unit doesn't stop when discovering another unit, possible values are 'only_ally', 'all' or no, (default no).
* '''[recruit]''': the player recruited a unit.
** '''type''': the id of the type of unit recruited.
** '''x''' and '''y''': the castle tile the unit is recruited on.
** '''[from]'''
*** '''x''' and '''y''': the keep tile the unit is recruited from.
* '''[recall]''': the player recalled a unit. Same keys as [recruit], except that '''value''' is the id of the unit being recalled.
* '''[attack]''': the player attacked.
** '''weapon''': the index number of the weapon. Weapons are indexed by the unit designer.
** '''defender_weapon''': the index number of the defenders weapon. Weapons are indexed by the unit designer, '-1' to choose the best weapon locally. The '-1' option is deprecated because it can cause OOS.
** '''[source]''': the location of the attacking unit.
** '''[destination]''': the location of the defending unit.
* '''[disband]''': the player removes a unit from his recall list.
** '''value''' the id of the removed unit.
* '''[end_turn]''': the player ended his turn.
* '''[init_side]''': new turn is starting for a side. This fires begin of turn events.
* '''[fire_event]''': a specific event was raised. This is mainly used for right-click menu items. ([set_menu_item])
** '''raise''': the name of the event
** '''[source]''': the location of the event
** '''[set_variable]''' (deprecated): set WML variable(s) before firing.
*** '''name''': the name of the variable
*** '''value''': a string value (literal)
* '''[lua_ai]''' {{DevFeature1.13|12}} This has been removed.
** '''code''' the lua code that is executed.
* '''[custom_command]''' {{DevFeature1.13|12}} Executes a custom command registered by Lua code
** '''name''': The name of the custom command to run.
** '''[data]''': Arbitrary data to be passed to the custom command.
* '''[auto_shroud]''' a player toggled delayed shroud update
** '''active''' whether automatic shroud updates will be active.
* '''[update_shroud]''' a player manually updated shroud.

Non dependent commands can have a [checkup] tag which is used to check whether the data generated in the replay matches the data generated during the original game, The [checkup] tag can contain different [result] tags whose content is different for the different actions.
For [attack] commands the [result]s give information about the single hits and can have the following attributes:
** '''chance''': the percent chance that the attack had to hit.
** '''damage''': the amount of damage that the attack would do if it hits.
** '''hits''': whether the attack hits.
Or
** '''dies''': whether the defender dies from the hit.

The following tags are recognized for dependent=true:
* '''[choose]''': the player was given an option by the scenario or for an advancement path.
** '''value''': the index number of the option chosen. Index numbers are given by the scenario designer.
* '''[input]''': if a lua code used [[LuaWML:Misc#wesnoth.synchronize_choice]] this tag contains the returned table.
* '''[global_variable]''' a WML code used with [get_global_variable]
* '''[random_seed]''' A user actions uses the rng and thus new random seed is needed.

== See Also ==
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

ReplayWML

2023-01-31T14:41:37Z

Toranks: Specifies that it supports StandardLocationFilter with all its capabilities, although normally only x,y is used

{{WML Tags}}
== The [command] tag ==

The '''[command]''' tag is used to specify an action in a replay. It has the following attributes:

* '''dependent''' if true, this command is not a lone-standing command and instead belongs to an earlier command, for example an advancement choice for an earlier attack command which issued an advancement.
* '''from_side''' the side which issued the command. Only present for dependent commands.
* '''sent''' used internally in networked mp, to know which commands were already sent to the other clients.
The following tags are recognized for dependent=no(default):
* '''[start]''': is used to initialize the replay so that generated random numbers can be saved.
* '''[move]''': the player moved a unit.
** '''x,y''': the path the unit walks.
** '''skip_sighted''': whether the unit doesn't stop when discovering another unit, possible values are 'only_ally', 'all' or no, (default no).
* '''[recruit]''': the player recruited a unit.
** '''type''': the id of the type of unit recruited.
** '''x''' and '''y''': the castle tile the unit is recruited on.
** '''[from]'''
*** '''x''' and '''y''': the keep tile the unit is recruited from.
* '''[recall]''': the player recalled a unit. Same keys as [recruit], except that '''value''' is the id of the unit being recalled.
* '''[attack]''': the player attacked.
** '''weapon''': the index number of the weapon. Weapons are indexed by the unit designer.
** '''defender_weapon''': the index number of the defenders weapon. Weapons are indexed by the unit designer, '-1' to choose the best weapon locally. The '-1' option is deprecated because it can cause OOS.
** '''[source]''': the location of the attacking unit. Use a [[StandardLocationFilter]].
** '''[destination]''': the location of the defending unit. Use a [[StandardLocationFilter]].
* '''[disband]''': the player removes a unit from his recall list.
** '''value''' the id of the removed unit.
* '''[end_turn]''': the player ended his turn.
* '''[init_side]''': new turn is starting for a side. This fires begin of turn events.
* '''[fire_event]''': a specific event was raised. This is mainly used for right-click menu items. ([set_menu_item])
** '''raise''': the name of the event
** '''[source]''': the location of the event. Use a [[StandardLocationFilter]].
** '''[set_variable]''' (deprecated): set WML variable(s) before firing.
*** '''name''': the name of the variable
*** '''value''': a string value (literal)
* '''[lua_ai]''' {{DevFeature1.13|12}} This has been removed.
** '''code''' the lua code that is executed.
* '''[custom_command]''' {{DevFeature1.13|12}} Executes a custom command registered by Lua code
** '''name''': The name of the custom command to run.
** '''[data]''': Arbitrary data to be passed to the custom command.
* '''[auto_shroud]''' a player toggled delayed shroud update
** '''active''' whether automatic shroud updates will be active.
* '''[update_shroud]''' a player manually updated shroud.

Non dependent commands can have a [checkup] tag which is used to check whether the data generated in the replay matches the data generated during the original game, The [checkup] tag can contain different [result] tags whose content is different for the different actions.
For [attack] commands the [result]s give information about the single hits and can have the following attributes:
** '''chance''': the percent chance that the attack had to hit.
** '''damage''': the amount of damage that the attack would do if it hits.
** '''hits''': whether the attack hits.
Or
** '''dies''': whether the defender dies from the hit.

The following tags are recognized for dependent=true:
* '''[choose]''': the player was given an option by the scenario or for an advancement path.
** '''value''': the index number of the option chosen. Index numbers are given by the scenario designer.
* '''[input]''': if a lua code used [[LuaWML:Misc#wesnoth.synchronize_choice]] this tag contains the returned table.
* '''[global_variable]''' a WML code used with [get_global_variable]
* '''[random_seed]''' A user actions uses the rng and thus new random seed is needed.

== See Also ==
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

ScenarioWML

2023-01-29T17:48:09Z

Toranks: [multiplayer] supports define key

{{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 difference between these tags is the way that the scenarios they describe are accessed.

The keys '''id''' and '''next_scenario''' affect how scenarios can be accessed.
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.
Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first
(in this case there is nothing on the recall list).
These scenarios are called ''initial scenario''s.

A list of initial scenarios, and how to access them:

* 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.)
* 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.

== The [scenario] tag ==

The following keys and tags are recognized in '''[scenario]''' 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.
* '''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_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|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]]
* '''turn_at''': the turn to start on (default=1)
*: Note that none of the regular start-of-turn behavior, including poison damage, healing, income and refreshing unit movement and status, will occur before the start of turn 2. All start-of-turn [[EventWML|WML events]] will still be fired, however.
* '''random_start_time''': controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example ''random_start_time=2,3,5,6'' (default depends on version and mp/sp, better include this key)
* '''music''': the music file relative to ''./music/'' to play during the scenario
* '''[music]''': specifies the music tracks to play during this scenario, see [[MusicListWML]].
* '''defeat_music''': specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.
* '''victory_music''': specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.
* '''theme''': the name of the UI theme that should be used when playing this scenario. Valid ids to use can be found in the files in data/themes. Cutscene and Cutscene_Minimal can be useful for dialog only scenarios.
* '''victory_when_enemies_defeated''': when this is set to '''yes''' (default), the player wins once all non-allied units with '''canrecruit=yes''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.) See Also [[SideWML]]. When this value is true the following keys can be used:
** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''remove_from_carryover_on_defeat''': when this is set to '''yes''' (default), for sides who got defeated (according to the side.defeat_condition), carryover will be removed.
* '''disallow_recall''': when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.
* '''experience_modifier''': the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.
* '''do_healing''': {{DevFeature1.15|0}} when set to yes, the engine will not skip healing at the first sides turn and will do the healing just like every other turn.
* '''[story]''': describes the intro screen. See [[IntroWML]]
* '''[label]''': sets a label
** '''x''', '''y''': location to set label
** '''text''': the label
* '''[item]''': places an item on map. See [[InterfaceActionsWML#.5Bitem.5D|InterfaceActionsWML]].
* '''[time]''': how a day should progress. See [[TimeWML]]
* '''current_time''': The time of day slot number (starting from zero) active at scenario start.
* '''[time_area]''': how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag
** takes x and y coordinates.
** '''[time]''': how a day should progress in those locations. See [[TimeWML]]
** '''current_time''': The time slot number (starting with zero) active at the creation of the area.
** 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]]
* '''[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
** '''default''': the default random map generator
* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]
* [[TerrainGraphicsWML]]: Scenarios can define custom terrain rules for the rendering of the map.
* [[GameConfigWML#Color_Palettes|Color palettes]]
* '''[lua]''': code in Lua. See [[LuaWML]]
* '''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 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]].
* '''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_era''': a list of era ids. Only the eras with matching ids will be allowed to be played with this scenario.
* '''disallow_era''': a list of era ids. Eras with matching ids will not be allowed to be played with this scenario. Cannot be used in parallel with allow_era.
* '''ignore_incompatible_era''': a list of era ids. The eras with matching ids will be considered compatible with this scenario regardless their dependencies.
* '''allow_modification''': same as allow_era, but for modifications.
* '''disallow_modification''': same as disallow_era, but for modifications. Cannot be used in parallel with allow_modification.
* '''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.
* '''[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.
* '''mp_village_gold''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
* '''mp_village_support''': {{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]'''
* '''define''': {{DevFeature1.13|0}} the scenario is preprocessed with this additional '''#define'''

== The [test] tag ==

The following keys and subtags are additionally recognized in '''[test]''' scenarios:

* '''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.

== Scenario End Conditions ==

In this section we will give a more precise explanation of things that can cause a scenario to end.

* At the '''end of every turn''', the turn number will be compared with the turn limit.
** If we pass the limit, the ''time over'' event will fire. If turns are not added by WML in response to this event, then the scenario will immediately end in defeat. [[EventWML#The_.27name.27_Key_.28Mandatory.29]]
* At the '''beginning of any turn''', and at '''the end of any user or ai action''', the victory conditions will be checked. This will result either in the scenario ending or continuing. The procedure for this is as follows:
** Every side will have its ''defeat_condition'' evaluated based on the units it currently has on the board. [[SideWML]]
*** At this time, villages of defeated sides will be unflagged, and if ''remove_from_carryover_on_defeat = yes'' then their carryover will be cleared as well.
** If any two not-defeated sides are enemies, the scenario will continue.
*** At this time, the ''enemies defeated'' event will fire.
** Furthermore, if ''victory_when_enemies_defeated=no'' and there exists a human controlled side, then the scenario will continue.
*** The human controlled side may be local or remote, for networked mp play.
** If neither of these conditions is met then the scenario will end.
***In victory or defeat according to whether a local human-controlled side is not defeated.

== See Also ==

* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

ModificationWML

2023-01-29T17:45:18Z

Toranks: [modification] supports define key

{{WML Tags}}
== The [modification] toplevel tag ==

This tag describes an SP or MP modification. A modification is, practically speaking, a bunch of events which get included into the scenario if the modification is enabled.

The following keys/tags are recognized for '''[modification]''':

* '''id''': identifier for the modification. Must be unique.
* '''name''': the name of the modification, as displayed to the user.
* '''type''': where the modification will be available for playing. Possible values are ''sp'', ''mp'', and ''hybrid''.
* '''description''': a brief description for the modification.
* '''define'''='''''MODIFICATION_SYMBOL''''' when this addon is active, the preprocessor symbol '''''MODIFICATION_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the modification file from other modifications or campaigns. Only the tags '''[modification]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''MODIFICATION_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''MODIFICATION_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this modification.
* '''disallow_scenario''': a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this modification. Cannot be used in parallel with allow_scenario.
* '''allow_era''': same as allow_scenario, but for eras.
* '''disallow_era''': same as disallow_scenario, but for eras. Can't be used with allow_era.
* '''allow_modification''': same as allow_scenario, but for modifications.
* '''disallow_modification''': same as disallow_scenario, but for modifications. Can't be used with allow_modification.
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this modification regardless their dependencies.
* '''ignore_incompatible_era''': same as ignore_incompatible_scenario, but for eras.
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
* '''require_modification''': a boolean value; if set to yes, all players have to have this modification installed to join the game. Default no.
* '''addon_min_version''': {{DevFeature1.13|0}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
* '''[event]''': any [event] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled. See [[EventWML]].
* '''[lua]''': any [lua] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled.
* '''[options]''': custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.
* '''[modify_unit_type]''' {{DevFeature1.15|2}}: Changes a unit type while this modification is active. This tag is also supported in [campaign] and [era]. The supported attributes are:
** '''type''' : the id of the unit type to change.
** '''set_experience''' : changes the unit type's max experience.
** '''set_cost''' : changes the unit type's recruit cost.
** '''set_advances_to''' : changes the unit type's advancements.
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

== The [resource] toplevel tag ==

{{DevFeature1.13|2}}

The '''[resource]''' toplevel tag is similar to [modification] in that it contains [event] and [lua] tags which are then copied into the scenario. However, unlike [modification], resources defined this way are completely hidden from the user. To load a resource, use '''[load_resource] id=<resource id>''' in [scenario], [multiplayer], [era], [campaign], [modification], or [resource].

Template:WML Tags

2023-01-27T15:08:14Z

Toranks: Errata

{| class="reference-sidebar"
|-
|
[[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit]]'''WML Tags'''
|-
|''A:''
[[AbilitiesWML|abilities]],
[[CreditsWML#.5Babout.5D|about]],
[[Creating_Custom_AIs#Behavior_Candidate_Actions|add_ai_behavior]],
[[SingleUnitWML|advance]],
[[AdvancedPreferenceWML|advanced_preference]],
[[AchievementsWML|achievement]],
[[AchievementsWML|achievement_group]],
[[UnitTypeWML|advancefrom]],
[[UnitTypeWML#After_max_level_advancement_.28AMLA.29|advancement]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|affect_adjacent]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|ai]],
[[StandardSideFilter|allied_with]],
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],
[[ConditionalActionsWML#Meta-Condition_Tags|and]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],
[[AnimationWML|animation]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|aspect]],
attack ([[ReplayWML|replay]], [[UnitTypeWML#Attacks|weapon]]),
[[AnimationWML|attack_anim]],
attacks ([[AbilitiesWML#The_.5Bspecials.5D_tag|special]], [[StatisticalScenarioWML#The_.5Bteam.5D_tag|stats]]),
[[AiWML#List_of_AI_Aspects|avoid]];
|-
|''B:''
[[UnitTypeWML#Other_tags|base_unit]],
[[IntroWML#.5Bbackground_layer.5D|background_layer]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|berserk]],
[[BinaryPathWML|binary_path]],
[[InternalActionsWML#Flow_control_actions|break]],
[[EditorWML#The_.5Bbrush.5D_tag|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML#.5Bcancel_action.5D|cancel_action]],
[[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|candidate_action]],
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|chance_to_hit]],
[[InterfaceActionsWML#.5Bchange_theme.5D|change_theme]],
[[InterfaceActionsWML#.5Bchat.5D|chat]],
[[OptionWML|checkbox]],
[[OptionWML|choice]],
[[ReplayWML|choose]],
[[PersistenceWML|clear_global_variable]],
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],
[[InternalActionsWML#.5Bclear_variable.5D|clear_variable]],
[[InterfaceActionsWML#.5Bcolor_adjust.5D|color_adjust]],
[[GameConfigWML#Color_Palettes|color_palette]],
[[GameConfigWML#Color_Palettes|color_range]],
command ([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]),
[[InternalActionsWML#Flow_control_actions|continue]],
[[CreditsWML#.5Bcredits_group.5D|credits_group]],
[[AiWML#The_.5Bgoal.5D_Tag|criteria]];
|-
|''D:''
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage]],
[[AnimationWML#death|death]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|deaths]],
[[AnimationWML#default|default]],
[[AnimationWML#defend|defend]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|defends]],
[[UnitsWML#.5Bmovetype.5D|defense]],
[[InterfaceActionsWML#.5Bdelay.5D|delay]],
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],
[[ReplayWML|destination]],
[[CampaignWML|difficulty]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|disable]],
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]],
[[DirectActionsWML#.5Bdo_command.5D|do_command]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|drains]],
[[AnimationWML#draw_weapon_anim|draw_weapon_anim]];
|-
|''E:''
[[EditorWML#The_.5Beditor_group.5D_tag|editor_group]],
[[EditorWML#The_.5Beditor_music.5D_tag|editor_music]],
[[EditorWML#The_.5Beditor_times.5D_tag|editor_times]],
[[EffectWML|effect]],
else ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]]), [[ConditionalActionsWML#.5Bif.5D|elseif]],
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],
end_turn ([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML|replay]]),
[[StandardSideFilter|enemy_of]],
[[Wesnoth_AI_Framework#Available_Engines|engine]],
entry ([[CreditsWML#.5Bentry.5D|credits]], [[OptionWML|options]]),
[[EraWML|era]],
[[EventWML|event]],
[[AnimationWML#Simplified_animation_blocks|extra_anim]];
|-
|''F:''
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]],
[[InterfaceActionsWML#.5Banimate_unit.5D|facing]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|fake_unit]],
[[ConditionalActionsWML#.5Bfalse.5D|false]],
[[PblWML#.5Bfeedback.5D|feedback]],
[[UnitTypeWML#Other_tags|female]],
filter ([[FilterWML|concept]], [[EventWML#.5Bfilter.5D|event]]),
[[StandardUnitFilter|filter_adjacent]],
[[StandardLocationFilter|filter_adjacent_location]],
[[FilterWML#Filtering_Weapons|filter_attack]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_attacker]],
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|filter_base_value]],
[[EventWML#.5Bfilter_condition.5D|filter_condition]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_defender]],
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_enemy]],
[[StandardLocationFilter|filter_location]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_opponent]],
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_own]],
[[StandardLocationFilter|filter_owner]],
[[StandardLocationFilter|filter_radius]],
[[SingleUnitWML|filter_recall]],
[[StandardUnitFilter|filter_second]],
[[FilterWML#Filtering_Weapons|filter_second_attack]],
[[AbilitiesWML|filter_self]],
[[StandardSideFilter|filter_side]],
[[AbilitiesWML|filter_student]],
[[FilterWML#Filtering_Vision|filter_vision]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_weapon]],
[[FilterWML#Filtering_on_WML_data|filter_wml]],
[[InternalActionsWML#.5Bfind_path.5D|find_path]],
[[InternalActionsWML#.5Bfire_event.5D|fire_event]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]],
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],
[[ConditionalActionsWML#.5Bfound_item.5D|found_item]],
[[ConditionalActionsWML#.5Bfor.5D|for]],
[[ConditionalActionsWML#.5Bforeach.5D|foreach]],
[[AnimationWML#Frames|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[PersistenceWML|get_global_variable]],
[[AiWML#The_.5Bgoal.5D_Tag|goal]],
[[DirectActionsWML#.5Bgold.5D|gold]],
[[InterfaceActionsWML#.5Bobjectives.5D|gold_carryover]];
|-
|''H:''
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],
[[StandardSideFilter|has_ally]],
[[StandardUnitFilter|has_attack]],
[[StandardSideFilter|has_unit]],
[[ConditionalActionsWML#.5Bhas_achievement.5D|has_achievement]],
[[ConditionalActionsWML#.5Bhave_location.5D|have_location]],
[[ConditionalActionsWML#.5Bhave_unit.5D|have_unit]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|heal_on_hit]],
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],
[[AnimationWML#healed|healed_anim]],
[[AnimationWML#healing|healing_anim]],
[[AbilitiesWML|heals]],
[[UnitsWML#.5Bhide_help.5D|hide_help]],
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]],
[[AbilitiesWML|hides]];
|-
|''I:''
[[AnimationWML#idling|idle_anim]],
if ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]], [[IntroWML|intro]]),
[[AbilitiesWML|illuminates]],
image ([[IntroWML#.5Bimage.5D|intro]], [[TerrainGraphicsWML|terrain]]),
[[ReplayWML|init_side]],
[[InternalActionsWML#.5Binsert_tag.5D|insert_tag]],
[[InterfaceActionsWML#.5Binspect.5D|inspect]],
[[InterfaceActionsWML#.5Bitem.5D|item]],
[[EditorWML#The_.5Bitem_group.5D_tag|item_group]];
|-
|''J:''
[[UnitsWML#.5Bmovetype.5D|jamming_costs]],
[[InternalActionsWML#.5Bset_variable.5D|join]];
|-
|''K:''
[[DirectActionsWML#.5Bkill.5D|kill]],
[[StatisticalScenarioWML|killed]];
|-
|''L:''
[[InterfaceActionsWML#.5Blabel.5D|label]],
[[LanguageWML|language]],
[[SideWML|leader]],
[[AiWML#List_of_AI_Aspects|leader_goal]],
[[AbilitiesWML|leadership]],
[[AnimationWML#leading|leading_anim]],
[[AnimationWML#levelin|levelin_anim]],
[[AnimationWML#levelout|levelout_anim]],
[[DirectActionsWML#.5Blift_fog.5D|lift_fog]],
[[AI_Recruitment#Aspect_recruitment_instructions|limit]],
[[InternalActionsWML#.5Bset_variables.5D|literal]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|load_resource]],
[[LocaleWML|locale]],
[[InterfaceActionsWML#.5Block_view.5D|lock_view]],
[[LuaWML|lua]];
|-
|''M:''
[[UnitTypeWML#Other_tags|male]],
[[SavefileWML|menu_item]],
[[InterfaceActionsWML#.5Bmessage.5D|message]],
[[Micro AIs|micro_ai]],
[[AnimationWML#The_content_of_a_frame|missile_frame]],
[[ModificationWML|modification]],
[[SingleUnitWML|modifications]],
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],
[[ModificationWML|modify_unit_type]],
[[ReplayWML|move]],
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],
[[AnimationWML#movement|movement_anim]],
[[UnitsWML#.5Bmovetype.5D|movement costs]],
[[UnitsWML#.5Bmovetype.5D|movetype]],
[[ScenarioWML|multiplayer]],
[[EraWML|multiplayer_side]],
[[MusicListWML#.5Bmusic.5D|music]];
|-
|''N:''
[[ConditionalActionsWML#Meta-Condition_Tags|not]],
[[InterfaceActionsWML#.5Bobjectives.5D|note]];
|-
|''O:''
[[DirectActionsWML#.5Bobject.5D|object]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],
[[DirectActionsWML#.5Bon_undo.5D|on_undo]],
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],
[[InterfaceActionsWML#.5Bmessage.5D|option]],
[[OptionWML|options]],
[[ConditionalActionsWML#Meta-Condition_Tags|or]];
|-
|''P:''
[[IntroWML|part]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]],
[[DirectActionsWML#.5Bpetrify.5D|petrify]],
[[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|plague]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|poison]],
[[UnitTypeWML#Other_tags|portrait]],
[[AnimationWML#post_movement|post_movement_anim]],
[[AnimationWML#pre_movement|pre_movement_anim]],
[[InternalActionsWML#.5Bfire_event.5D|primary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|primary_unit]],
[[InterfaceActionsWML#.5Bprint.5D|print]],
[[DirectActionsWML#.5Bput_to_recall_list.5D|put_to_recall_list]];
|-
|''R:''
[[UnitsWML#.5Brace.5D|race]],
[[InternalActionsWML#.5Brandom_placement.5D|random_placement]],
recall ([[DirectActionsWML#.5Brecall.5D|action]], [[ReplayWML|replay]]),
[[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]],
[[AnimationWML#recruited|recruit_anim]],
[[AnimationWML#recruiting|recruiting_anim]],
[[StatisticalScenarioWML|recruits]],
[[InterfaceActionsWML#.5Bredraw.5D|redraw]],
[[AbilitiesWML|regenerate]],
[[InternalActionsWML#.5Bremove_event.5D|remove_event]],
[[InterfaceActionsWML#.5Bremove_item.5D|remove_item]],
[[DirectActionsWML#.5Bremove_object.5D|remove_object]],
[[DirectActionsWML#.5Bremove_shroud.5D|remove_shroud]],
[[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]],
[[DirectActionsWML#.5Bremove_time_area.5D|remove_time_area]],
[[DirectActionsWML#.5Bremove_trait.5D|remove_trait]],
[[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],
[[ConditionalActionsWML#.5Brepeat.5D|repeat]],
[[DirectActionsWML#.5Breplace_map.5D|replace_map]],
[[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]],
[[ReplayWML|replay]],
[[SavefileWML|replay_start]],
[[DirectActionsWML#.5Breset_fog.5D|reset_fog]],
resistance ([[AbilitiesWML|ability]], [[UnitsWML#.5Bmovetype.5D|unit]]),
[[UnitsWML#.5Bresistance_defaults.5D|resistance_defaults]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|resource]],
[[InternalActionsWML#Flow_control_actions|return]],
[[InternalActionsWML#.5Brole.5D|role]],
[[TerrainMaskWML|rule]];
|-
|''S:''
[[SavefileWML|save]],
[[ScenarioWML|scenario]],
[[InterfaceActionsWML#.5Bscroll.5D|scroll]],
[[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_unit]],
[[HelpWML|section]],
[[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]],
[[ReplayWML|sequence]],
[[DirectActionsWML#.5Bset_achievement.5D|set_achievement]],
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],
[[PersistenceWML|set_global_variable]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]],
[[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],
[[EffectWML|set_specials]],
[[InternalActionsWML#.5Bset_variable.5D|set_variable]],
[[InternalActionsWML#.5Bset_variables.5D|set_variables]],
[[AnimationWML#sheath_weapon|sheath_weapon_anim]],
show_if ([[InterfaceActionsWML#.5Bmessage.5D|message]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]]),
[[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],
[[SideWML|side]],
[[AbilitiesWML|skirmisher]],
[[OptionWML|slider]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|slow]],
[[SavefileWML|snapshot]],
[[InterfaceActionsWML#.5Bsound.5D|sound]],
[[InterfaceActionsWML#.5Bsound_source.5D|sound_source]],
source ([[ReplayWML|replay]], [[DirectActionsWML#.5Btunnel.5D|teleport]]),
[[UnitTypeWML#Other_tags|special_note]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|specials]],
[[InternalActionsWML#.5Bset_variables.5D|split]],
[[Wesnoth_AI_Framework#Available_Stages|stage]],
[[AnimationWML#standing|standing_anim]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[SingleUnitWML|status]],
[[InternalActionsWML#.5Bstore_gold.5D|store_gold]],
[[InternalActionsWML#.5Bstore_items.5D|store_items]],
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],
[[InternalActionsWML#.5Bstore_relative_direction.5D|store_relative_direction]],
[[InternalActionsWML#.5Bstore_side.5D|store_side]],
[[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]],
[[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]],
[[InternalActionsWML#.5Bstore_turns.5D|store_turns]],
[[InternalActionsWML#.5Bstore_unit.5D|store_unit]],
[[InternalActionsWML#.5Bstore_unit_defense.5D|store_unit_defense]],
[[InternalActionsWML#.5Bstore_unit_defense_on.5D|store_unit_defense_on]],
[[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]],
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]],
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]],
[[IntroWML|story]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]],
[[InternalActionsWML#.5Bsync_variable.5D|sync_variable]];
|-
|''T:''
[[DirectActionsWML#.5Btunnel.5D|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
teleport ([[AbilitiesWML|ability]], [[DirectActionsWML#.5Bteleport.5D|action]]),
[[AnimationWML#pre_teleport|teleport_anim]],
[[DirectActionsWML#.5Bterrain.5D|terrain]],
[[UnitsWML#.5Bterrain_defaults.5D|terrain_defaults]],
[[TerrainGraphicsWML|terrain_graphics]],
[[TerrainMaskWML|terrain_mask]],
[[TerrainWML|terrain_type]],
[[ScenarioWML#Test_scenario|test]],
[[InterfaceActionsWML#.5Btest_condition.5D|test_condition]],
[[InterfaceActionsWML#.5Bmessage.5D|text_input]],
[[GettextForWesnothDevelopers#The_textdomain_declaration|textdomain]],
[[ThemeWML|theme]],
[[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]],
[[TimeWML|time]],
[[DirectActionsWML#.5Btime_area.5D|time_area]],
[[HelpWML|topic]],
[[HelpWML|toplevel]],
[[UnitsWML#.5Btrait.5D|trait]],
[[DirectActionsWML#.5Btransform_unit.5D|transform_unit]],
[[InternalActionsWML#.5Bfind_path.5D|traveler]],
[[ConditionalActionsWML#.5Btrue.5D|true]],
[[DirectActionsWML#.5Btunnel.5D|tunnel]],
[[ScenarioWML|tutorial]];
|-
|''U:''
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]],
[[SingleUnitWML|unit]],
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]],
[[UnitTypeWML|unit_type]],
[[InternalActionsWML#.5Bunit_worth.5D|unit_worth]],
[[UnitsWML|units]],
[[InterfaceActionsWML#.5Bunlock_view.5D|unlock_view]],
[[DirectActionsWML#.5Bunpetrify.5D|unpetrify]],
[[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]],
[[InternalActionsWML#.5Bunsynced.5D|unsynced]];
|-
| ''V:''
[[InternalActionsWML#.5Bset_variables.5D|value]],
[[ConditionalActionsWML#.5Bvariable.5D|variable]],
[[VariablesWML#The_.5Bvariables.5D_tag|variables]],
[[TerrainGraphicsWML|variant]],
[[UnitTypeWML#Other_tags|variation]],
[[AnimationWML#victory|victory_anim]],
[[SideWML|village]],
[[UnitsWML#.5Bmovetype.5D|vision_costs]],
[[InterfaceActionsWML#.5Bvolume.5D|volume]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]],
[[SchemaWML|wml_schema]];
|-
| ''Z:''
[[InterfaceActionsWML#.5Bzoom.5D|zoom]];
|}<includeonly>[[Category:WML Reference]]</includeonly><noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the WML reference pages.</noinclude>

StandardUnitFilter

2023-01-25T19:07:21Z

Toranks: find_in searchs by id

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering units.

When a unit filter is applied to a map, first it applies to all units on the field,
based on their coordinates.
Next it applies to units in the recall list.
This is important to remember as it means, for example,
that the tag '''[kill]''' can be used to kill units in the recall list.

You can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables

The term [[StandardUnitFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardUnitFilter]] needs to be included in a [filter] tag. But many tags take the [[StandardUnitFilter]] directly as an argument, like [kill] and [have_unit]. See [[Special:WhatLinksHere/StandardUnitFilter]] for tags which can contain a StandardUnitFilter.

__TOC__

The following attributes and sub-tags are allowed:

* '''id''': unit matches the given id. This is the same as ''id'' in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this (see [[SingleUnitWML]]). id= can be a comma-separated list, every unit with one of these ids matches.
* '''speaker''': alias for id (no comma-separated list supported)
* '''type''': matches the unit's type name (can be a list of types)
* '''type_adv_tree''': {{DevFeature1.13|7}} matches the type name of the unit and all its advancements (can be a list)
* '''race''': the race of the unit type. This can be a comma-separated list; the unit's race must match one of the given races. Mainline races are listed in data/core/units.cfg 
* '''variation''': the unit type variation id (can be a list of variation ids)
* '''has_variation''': matches if the unit type for the unit defines at least one of the variation ids provided as a comma-separated list
* '''upkeep''': {{DevFeature1.15|3}} The upkeep of the unit. Can be either a non-negative number or one of the special values ''loyal'', ''free'', ''full''. Note that while ''loyal'' and ''free'' are synonymous with an upkeep of 0, the value ''full'' is not synonymous with any single numeric value – it is equivalent to `$this_unit.level`.
* '''ability''': unit has an ability with the given id; see [[AbilitiesWML]]
* '''ability_type''': {{DevFeature1.13|7}} unit has an ability with the given type (tag name) - eg, ''ability_type=heals'' will match a unit with any healing ability.
* '''ability_type_active''': {{DevFeature1.13|8}} unit has an ''active'' ability with the given type (tag name).
* '''trait''': {{DevFeature1.13|8}} This can be a comma-separated list. The unit must have at least one of the specified traits.
* '''status''': {{DevFeature1.13|0}} matches if the unit has the specified status active. This can be a comma-separated list, in which case the unit will match as long as it has one of the listed statuses active (note: possible statuses are listed on the [[SingleUnitWML]] page).
* '''side''': the unit is on the given side (can be a list)
* '''has_weapon''': the unit has a weapon with the given name {{DevFeature1.13|5}} Now deprecated
* '''[has_attack]''': {{DevFeature1.13|5}} the unit has a weapon matching the [[StandardWeaponFilter]]. If this is present, '''has_weapon''' is ignored.
* '''canrecruit''': yes if the unit can recruit (i.e. is a leader)
* '''gender''': female if the unit is female rather than the default of male
* '''role''': the unit has been assigned the given role; see '''[role]''', [[InternalActionsWML]]
* '''level''': the level of the unit (this can be a comma-separated list).
* '''defense''': current defense of the unit on current tile (chance to hit %, like in movement type definitions)
* '''movement_cost''': current movement cost of the unit on current tile
* '''x,y''': the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
* '''find_in''': name of an array or container variable; if present, the unit will not match unless a unit with the same '''id''' is already stored in the variable
* '''[filter_vision]''': this tests whether or not the unit is currently visible
** '''visible''': yes or no, default yes. When "yes", this matches units that are not obscured by fog or shroud, and that are not hiding (via the {{tag|AbilitiesWML|hides}} ability). When "no", this matches units that are obscured by fog or shroud, or that are hiding.
** [[StandardSideFilter]] tags and keys. Filter for who may be able to see (or not see) the unit. If there is *at least one* matching side which can see the unit then the filter matches, and otherwise it fails to match.
* '''[filter_wml]''': Converts the unit to WML (as if by '''[store_unit]''') and tests it against a [[FilterWML#Filtering_on_WML_data|WML filter]]. For a list of things in the WML that could be filtered on, see [[SingleUnitWML]] or open a saved game in a text editor. Note that this is slower than other methods, so if possible it's better to use other filter keys and tags; however, if the WML filter contains only a child '''[variables]''', then the unit is not converted to WML and the filter is matched only against the unit's variables (which are already WML).
* '''[and]''': an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. ''Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.''
* '''[or]''': an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
* '''[filter_adjacent]''' with a StandardUnitFilter as argument; do not use a [filter] tag. If present the correct number of adjacent units must match this filter.
**'''StandardUnitFilter''' tags and keys
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[StandardLocationFilter#Directions|notes]])
** '''is_enemy''': a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
** '''$other_unit''': {{DevFeature1.13|2}} Within [filter_adjacent], the special variable $other_unit refers to the filtered unit from the enclosing filter, while $this_unit refers (as with all StandardUnitFilters) to the unit being filtered on.
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
*'''[filter_side]''': The currently filtered unit's side must match this [[StandardSideFilter]] for the unit to match.
**[[StandardSideFilter]] tags and keys
* '''formula''': A formula using [[Wesnoth Formula Language]]. The <tt>self</tt> variable is set to the current $this_unit, and the formula should return a boolean. If it returns 0, the filter does not match. Otherwise, the filter does match. {{DevFeature1.13|5}} If the filter has a secondary unit, the formula can access it using the <code>other</code> variable. Both the unit and the secondary unit are a '''unit object''', with keys documented [[#Wesnoth_Formula_Language|below]]. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
* '''lua_function''': the name of a [[LuaWML|Lua]] function in the global environment that takes a unit as an argument and returns true if the given unit matches the filter. {{DevFeature1.13|5}} Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

== Wesnoth Formula Language ==

When using the '''formula''' key, the '''self''' and (if present) '''other''' objects support the following keys:

* '''x''', '''y''', '''loc''' - the latter is a '''location object''' such as what would be returned from [[Wesnoth_Formula_Language#loc|loc()]].
* '''id'''
* '''type'''
* '''name'''
* '''usage'''
* '''canrecruit''', '''leader'''
* '''undead''' - true if the unit has the ''not_living'' status
* '''attacks''' - a list of '''[[FilterWML#Filtering_Weapons|weapon objects]]'''
* '''abilities''' - a list of the ability IDs the unit possesses
* '''hitpoints''', '''max_hitpoints'''
* '''experience''', '''max_experience'''
* '''moves''', '''max_moves'''
* '''attacks_left''', '''max_attacks'''
* '''level''', '''full''' - '''full''' refers to the unit's level to support the formula <syntaxhighlight lang=wfl inline>upkeep = full</syntaxhighlight>
* '''traits''' - a list of the trait IDs
* '''extra_recruit'''
* '''advances_to'''
* '''status''' - a list of active statuses
* '''side_number'''
* '''cost'''
* '''upkeep'''
* '''loyal''' - a constant 0 to support the formula <syntaxhighlight lang=wfl inline>upkeep = loyal</syntaxhighlight>
* '''hidden'''
* '''petrified''' - true if the unit has the '''petrified''' status
* '''resting'''
* '''role'''
* '''race'''
* '''gender'''
* '''variation'''
* '''zoc'''
* '''alignment'''
* '''facing'''
* '''resistance''', '''movement_cost''', '''vision_cost''', '''jamming_cost''', '''defense''' - {{DevFeature1.15|3}} Maps containing the basic movetype data. The '''defense''' and '''resistance''' maps contain the actual defense and resistance values, rather than the values specified in the WML, so you do not need to subtract them from 100.
* '''flying''' {{DevFeature1.15|3}}
* '''vars''' - WFL variables owned by the unit, which can be set and used by FormulaAI
* '''wml_vars''' - the WML variables stored in the unit
* '''n''', '''s''', '''ne''', '''se''', '''nw''', '''sw''', '''lawful''', '''chaotic''', '''neutral''', '''liminal''', '''male''', '''female''' - these are all defined to be the equivalent string so that, for example, you can write a formula like <syntaxhighlight lang=wfl inline>alignment = liminal and gender = female</syntaxhighlight> without needing to quote the alignment and gender strings.

== A Note about Re-Using the Same Attribute ==
You are limited to having each attribute, such as '''id''', appear once or less in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:

<syntaxhighlight lang='wml'>
[kill]
[not]
id=Gwiti Ha'atel
[/not]
[not]
id=Tanar
[/not]
[/kill]
</syntaxhighlight>

And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:

<syntaxhighlight lang='wml'>
[kill]
id=Gwiti Ha'atel
[or]
id=Tanar
[/or]
[/kill]
</syntaxhighlight>

== Tutorial ==

* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

ConditionalActionsWML

2023-01-25T18:32:41Z

Toranks: /* [foreach] */

{{WML Tags}}

Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside '''[if]''' aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
** [[#Condition Tags|Condition Tags]]: Specifies the conditions, just like in '''[if]'''.
** '''[then]''': Specifies actions, exactly like the '''[then]''' tag inside '''[if]'''.

* '''[else]''': Contains [[ActionWML|actions]] which should be executed if all condition tags in the '''[if]''' and any directly nested '''[elseif]''' all evaluate as false.

'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.

Example usage:
<syntaxhighlight lang=wml>
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[elseif]
[variable]
name=we.gold
equals=$they.gold
[/variable]
[then]
[message]
message=This should be fair!
[/message]
[/then]
[/elseif]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
</syntaxhighlight>

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable. Boolean variable values are not accepted and cause lua errors currently.

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
<syntaxhighlight lang=wml>
[switch]
variable=foo
[case]
value="A"
# ... WML if foo=A ...
[/case]
[case]
value="B"
# ... WML if foo=B ...
[/case]
[else]
# ... WML if not foo=A nor foo=B ...
[/else]
[/switch]
</syntaxhighlight>

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false. Multiple '''[do]''' tags can be used, and they will be executed in sequence on each iteration. However, there is usually no reason to do this.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros. Note: This macro is deprecated; you should just use the '''[foreach]''' WML tag instead.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [for] ===

{{DevFeature1.13|2}}

Loops over an integer range. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.

* '''variable''': The name of the variable containing the current index. Defaults to ''i''. If there is already a variable with this name, it will be automatically saved before the start of the loop, and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, it will be automatically deleted, there is no need to do a '''[clear_variable]''' afterwards
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [foreach] ===

{{DevFeature1.13|2}}

Loops over an array variable. This is not used to implement the {FOREACH} macro because [foreach] doesn't support adding or removing elements while looping (and will usually raise an error), use '''[for]''' instead.

* '''array''': The array variable to loop over.
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

The '''[foreach]''' tag simulates local-scoping of its index variables. If there was already a WML variable with the same name (by default ''i'' and ''this_item'' respectively), it will be automatically saved before the start of the '''[do]''', and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, there is no need to do a '''[clear_variable]''' afterwards.

It's possible to nest '''[foreach]''' loops, however it's strongly recommended avoid having both use the same ''variable='' name.

=== [repeat] ===

{{DevFeature1.13|2}}

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use '''[for]''' instead.)

* '''times''': The number of times to repeat the actions.
* '''[do]''': The actions to repeat. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

=== [true] ===

Represents a condition that always yields true. Takes no arguments.

=== [false] ===

Represents a condition that always yields false. Takes no arguments.

=== [have_unit] ===

A unit with greater than zero hit points matching this filter exists.

* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.
* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')

=== [have_location] ===

A location matching this filter exists.

* [[StandardLocationFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

=== [has_achievement] ===

{{DevFeature1.17|13}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

=== [variable] ===

Test the value of a WML [[SyntaxWML#Variables|variable]] against another value.

* '''name''': The name of the variable to test.
* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
** '''contains''': ''$name'' contains this string value.
** '''equals''': ''$name'' is equal (string wise) to this value.
** '''not_equals''': ''$name'' is not equal (string wise) to this value.
** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
** '''greater_than''': ''$name'' is numerically greater than this value.
** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.
** '''less_than''': ''$name'' is numerically less than this value.
** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.
** '''boolean_equals''': ''$name'' has an equivalent boolean value.
** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.
** '''formula''': {{DevFeature1.15|0}} ''$name'' satisfies the given [[Wesnoth_Formula_Language|WFL]] formula.

====Boolean Values====
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.

* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true.

'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

====Formulas====
When using a formula, the variable's value can be referenced as '''value''' in the formula. This is a WFL representation of a config object that supports the following fields:

* '''__all_children''': A list of key-value pairs, where the key is the tag name and the value is another config object representing the tag content.
* '''__children''': A map from tag name to a list of all children with that tag name.
* '''__attributes''': A map from attribute to value. Only useful if you specifically require a map for some reason.
* ''Any attribute name'': The value of that attribute
* ''Any tag name'': A list of all children with that tag name.
* Note that if there is a tag and an attribute with the same name, accessing it by name will return the attribute. You would need to use '''__children''' to access the tag.

For example, suppose you had a variable with the following WML content:

<syntaxhighlight lang=wml>
[my_variable]
stuff=777
something=a value
[something]
value=42
[/something]
[another_tag]
value=21
[/another_tag]
[subarray]
value=8
[/subarray]
[subarray]
value=91
[/subarray]
[another_tag]
value=12
[/another_tag]
[/my_variable]
</syntaxhighlight>

Then the formula could access the following variables on the '''value''' object:
* '''__all_children''': A list of ordered key-value pairs roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> ['value' -> 42], 'another_tag' -> ['value' -> 21], 'subarray' -> ['value' -> 8], 'subarray' -> ['value' -> 91], 'another_tag' -> ['value' -> 12]]</syntaxhighlight>
* '''__children''': A map roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> [['value' -> 42]], 'another_tag' -> [['value' -> 21], ['value' -> 12]], 'subarray' -> [['value' -> 8], ['value' -> 91]]]</syntaxhighlight>
* '''__attributes''': A map equivalent to <syntaxhighlight lang=wfl inline>['stuff' -> 777, 'something' -> 'a value']</syntaxhighlight>
* '''stuff''': The number <syntaxhighlight lang=wfl inline>777</syntaxhighlight>
* '''something''': The string <syntaxhighlight lang=wfl inline>'a value'</syntaxhighlight>
* '''another_tag''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 21], ['value' -> 12]]</syntaxhighlight>
* '''subarray''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 8], ['value' -> 91]]</syntaxhighlight>

{{DevFeature1.17|11}} When using a formula, you can now specify an additional key:

* '''as_type''': Specifies the type of the '''value''' object in the formula. The default is ''wml'', which uses the structure as described above. The other supported options are:
** ''unit'': Interprets the variable's value as a stored unit, allowing you to write the formula the same way you would in a [[StandardUnitFilter]].
** ''weapon'': Interprets the variable's value as an attack type, allowing you to write the formula the same way you would in a [[StandardWeaponFilter]].

=== [found_item] ===

{{DevFeature1.13|2}} Test if an item (ie, a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function.

* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

=== [proceed_to_next_scenario] ===

{{DevFeature1.13|10}} In SP, true if the scenario has been won.

=== [lua] ===

{{DevFeature1.13|11}} Evaluate a lua expression, which must return a boolean value. Useful for writing one-off conditions that are difficult to express with other tags, but for much-used conditions it's better to define a custom condition tag using [[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]].

* '''code''': The Lua expression.
* '''[args]''': Arbitrary data passed to the expression, accessible via <tt>...</tt> in the Lua code.

For example

<syntaxhighlight lang=wml>
[event]
name=new turn
first_time_only=no
[filter_condition]
[lua]
code = << return (wesnoth.get_variable("turn_number") % 2 == 0) >>
[/lua]
[/filter_condition]
[message]
speaker=narrator
message= "Hello world $turn_number|"
[/message]
[/event]
</syntaxhighlight>

=== Meta-Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
# this true or false result is combined with the top meta-condition to produce another true or false result
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.

== See Also ==
* [[SyntaxWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

ConditionalActionsWML

2023-01-25T18:31:38Z

Toranks: /* [repeat] */

{{WML Tags}}

Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside '''[if]''' aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
** [[#Condition Tags|Condition Tags]]: Specifies the conditions, just like in '''[if]'''.
** '''[then]''': Specifies actions, exactly like the '''[then]''' tag inside '''[if]'''.

* '''[else]''': Contains [[ActionWML|actions]] which should be executed if all condition tags in the '''[if]''' and any directly nested '''[elseif]''' all evaluate as false.

'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.

Example usage:
<syntaxhighlight lang=wml>
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[elseif]
[variable]
name=we.gold
equals=$they.gold
[/variable]
[then]
[message]
message=This should be fair!
[/message]
[/then]
[/elseif]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
</syntaxhighlight>

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable. Boolean variable values are not accepted and cause lua errors currently.

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
<syntaxhighlight lang=wml>
[switch]
variable=foo
[case]
value="A"
# ... WML if foo=A ...
[/case]
[case]
value="B"
# ... WML if foo=B ...
[/case]
[else]
# ... WML if not foo=A nor foo=B ...
[/else]
[/switch]
</syntaxhighlight>

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false. Multiple '''[do]''' tags can be used, and they will be executed in sequence on each iteration. However, there is usually no reason to do this.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros. Note: This macro is deprecated; you should just use the '''[foreach]''' WML tag instead.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [for] ===

{{DevFeature1.13|2}}

Loops over an integer range. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.

* '''variable''': The name of the variable containing the current index. Defaults to ''i''. If there is already a variable with this name, it will be automatically saved before the start of the loop, and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, it will be automatically deleted, there is no need to do a '''[clear_variable]''' afterwards
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [foreach] ===

{{DevFeature1.13|2}}

Loops over an array variable. This is not used to implement the {FOREACH} macro because [foreach] doesn't support adding or removing elements while looping (and will usually raise an error). Use '''[for]''' instead.

* '''array''': The array variable to loop over.
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

The '''[foreach]''' tag simulates local-scoping of its index variables. If there was already a WML variable with the same name (by default ''i'' and ''this_item'' respectively), it will be automatically saved before the start of the '''[do]''', and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, there is no need to do a '''[clear_variable]''' afterwards.

It's possible to nest '''[foreach]''' loops, however it's strongly recommended avoid having both use the same ''variable='' name.

=== [repeat] ===

{{DevFeature1.13|2}}

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use '''[for]''' instead.)

* '''times''': The number of times to repeat the actions.
* '''[do]''': The actions to repeat. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

=== [true] ===

Represents a condition that always yields true. Takes no arguments.

=== [false] ===

Represents a condition that always yields false. Takes no arguments.

=== [have_unit] ===

A unit with greater than zero hit points matching this filter exists.

* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.
* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')

=== [have_location] ===

A location matching this filter exists.

* [[StandardLocationFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

=== [has_achievement] ===

{{DevFeature1.17|13}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

=== [variable] ===

Test the value of a WML [[SyntaxWML#Variables|variable]] against another value.

* '''name''': The name of the variable to test.
* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
** '''contains''': ''$name'' contains this string value.
** '''equals''': ''$name'' is equal (string wise) to this value.
** '''not_equals''': ''$name'' is not equal (string wise) to this value.
** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
** '''greater_than''': ''$name'' is numerically greater than this value.
** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.
** '''less_than''': ''$name'' is numerically less than this value.
** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.
** '''boolean_equals''': ''$name'' has an equivalent boolean value.
** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.
** '''formula''': {{DevFeature1.15|0}} ''$name'' satisfies the given [[Wesnoth_Formula_Language|WFL]] formula.

====Boolean Values====
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.

* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true.

'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

====Formulas====
When using a formula, the variable's value can be referenced as '''value''' in the formula. This is a WFL representation of a config object that supports the following fields:

* '''__all_children''': A list of key-value pairs, where the key is the tag name and the value is another config object representing the tag content.
* '''__children''': A map from tag name to a list of all children with that tag name.
* '''__attributes''': A map from attribute to value. Only useful if you specifically require a map for some reason.
* ''Any attribute name'': The value of that attribute
* ''Any tag name'': A list of all children with that tag name.
* Note that if there is a tag and an attribute with the same name, accessing it by name will return the attribute. You would need to use '''__children''' to access the tag.

For example, suppose you had a variable with the following WML content:

<syntaxhighlight lang=wml>
[my_variable]
stuff=777
something=a value
[something]
value=42
[/something]
[another_tag]
value=21
[/another_tag]
[subarray]
value=8
[/subarray]
[subarray]
value=91
[/subarray]
[another_tag]
value=12
[/another_tag]
[/my_variable]
</syntaxhighlight>

Then the formula could access the following variables on the '''value''' object:
* '''__all_children''': A list of ordered key-value pairs roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> ['value' -> 42], 'another_tag' -> ['value' -> 21], 'subarray' -> ['value' -> 8], 'subarray' -> ['value' -> 91], 'another_tag' -> ['value' -> 12]]</syntaxhighlight>
* '''__children''': A map roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> [['value' -> 42]], 'another_tag' -> [['value' -> 21], ['value' -> 12]], 'subarray' -> [['value' -> 8], ['value' -> 91]]]</syntaxhighlight>
* '''__attributes''': A map equivalent to <syntaxhighlight lang=wfl inline>['stuff' -> 777, 'something' -> 'a value']</syntaxhighlight>
* '''stuff''': The number <syntaxhighlight lang=wfl inline>777</syntaxhighlight>
* '''something''': The string <syntaxhighlight lang=wfl inline>'a value'</syntaxhighlight>
* '''another_tag''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 21], ['value' -> 12]]</syntaxhighlight>
* '''subarray''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 8], ['value' -> 91]]</syntaxhighlight>

{{DevFeature1.17|11}} When using a formula, you can now specify an additional key:

* '''as_type''': Specifies the type of the '''value''' object in the formula. The default is ''wml'', which uses the structure as described above. The other supported options are:
** ''unit'': Interprets the variable's value as a stored unit, allowing you to write the formula the same way you would in a [[StandardUnitFilter]].
** ''weapon'': Interprets the variable's value as an attack type, allowing you to write the formula the same way you would in a [[StandardWeaponFilter]].

=== [found_item] ===

{{DevFeature1.13|2}} Test if an item (ie, a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function.

* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

=== [proceed_to_next_scenario] ===

{{DevFeature1.13|10}} In SP, true if the scenario has been won.

=== [lua] ===

{{DevFeature1.13|11}} Evaluate a lua expression, which must return a boolean value. Useful for writing one-off conditions that are difficult to express with other tags, but for much-used conditions it's better to define a custom condition tag using [[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]].

* '''code''': The Lua expression.
* '''[args]''': Arbitrary data passed to the expression, accessible via <tt>...</tt> in the Lua code.

For example

<syntaxhighlight lang=wml>
[event]
name=new turn
first_time_only=no
[filter_condition]
[lua]
code = << return (wesnoth.get_variable("turn_number") % 2 == 0) >>
[/lua]
[/filter_condition]
[message]
speaker=narrator
message= "Hello world $turn_number|"
[/message]
[/event]
</syntaxhighlight>

=== Meta-Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
# this true or false result is combined with the top meta-condition to produce another true or false result
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.

== See Also ==
* [[SyntaxWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

ConditionalActionsWML

2023-01-25T18:31:00Z

Toranks: /* [foreach] */

{{WML Tags}}

Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside '''[if]''' aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
** [[#Condition Tags|Condition Tags]]: Specifies the conditions, just like in '''[if]'''.
** '''[then]''': Specifies actions, exactly like the '''[then]''' tag inside '''[if]'''.

* '''[else]''': Contains [[ActionWML|actions]] which should be executed if all condition tags in the '''[if]''' and any directly nested '''[elseif]''' all evaluate as false.

'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.

Example usage:
<syntaxhighlight lang=wml>
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[elseif]
[variable]
name=we.gold
equals=$they.gold
[/variable]
[then]
[message]
message=This should be fair!
[/message]
[/then]
[/elseif]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
</syntaxhighlight>

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable. Boolean variable values are not accepted and cause lua errors currently.

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
<syntaxhighlight lang=wml>
[switch]
variable=foo
[case]
value="A"
# ... WML if foo=A ...
[/case]
[case]
value="B"
# ... WML if foo=B ...
[/case]
[else]
# ... WML if not foo=A nor foo=B ...
[/else]
[/switch]
</syntaxhighlight>

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false. Multiple '''[do]''' tags can be used, and they will be executed in sequence on each iteration. However, there is usually no reason to do this.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros. Note: This macro is deprecated; you should just use the '''[foreach]''' WML tag instead.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [for] ===

{{DevFeature1.13|2}}

Loops over an integer range. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.

* '''variable''': The name of the variable containing the current index. Defaults to ''i''. If there is already a variable with this name, it will be automatically saved before the start of the loop, and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, it will be automatically deleted, there is no need to do a '''[clear_variable]''' afterwards
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [foreach] ===

{{DevFeature1.13|2}}

Loops over an array variable. This is not used to implement the {FOREACH} macro because [foreach] doesn't support adding or removing elements while looping (and will usually raise an error). Use '''[for]''' instead.

* '''array''': The array variable to loop over.
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

The '''[foreach]''' tag simulates local-scoping of its index variables. If there was already a WML variable with the same name (by default ''i'' and ''this_item'' respectively), it will be automatically saved before the start of the '''[do]''', and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, there is no need to do a '''[clear_variable]''' afterwards.

It's possible to nest '''[foreach]''' loops, however it's strongly recommended avoid having both use the same ''variable='' name.

=== [repeat] ===

{{DevFeature1.13|2}}

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use [for] instead.)

* '''times''': The number of times to repeat the actions.
* '''[do]''': The actions to repeat. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

=== [true] ===

Represents a condition that always yields true. Takes no arguments.

=== [false] ===

Represents a condition that always yields false. Takes no arguments.

=== [have_unit] ===

A unit with greater than zero hit points matching this filter exists.

* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.
* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')

=== [have_location] ===

A location matching this filter exists.

* [[StandardLocationFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

=== [has_achievement] ===

{{DevFeature1.17|13}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

=== [variable] ===

Test the value of a WML [[SyntaxWML#Variables|variable]] against another value.

* '''name''': The name of the variable to test.
* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
** '''contains''': ''$name'' contains this string value.
** '''equals''': ''$name'' is equal (string wise) to this value.
** '''not_equals''': ''$name'' is not equal (string wise) to this value.
** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
** '''greater_than''': ''$name'' is numerically greater than this value.
** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.
** '''less_than''': ''$name'' is numerically less than this value.
** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.
** '''boolean_equals''': ''$name'' has an equivalent boolean value.
** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.
** '''formula''': {{DevFeature1.15|0}} ''$name'' satisfies the given [[Wesnoth_Formula_Language|WFL]] formula.

====Boolean Values====
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.

* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true.

'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

====Formulas====
When using a formula, the variable's value can be referenced as '''value''' in the formula. This is a WFL representation of a config object that supports the following fields:

* '''__all_children''': A list of key-value pairs, where the key is the tag name and the value is another config object representing the tag content.
* '''__children''': A map from tag name to a list of all children with that tag name.
* '''__attributes''': A map from attribute to value. Only useful if you specifically require a map for some reason.
* ''Any attribute name'': The value of that attribute
* ''Any tag name'': A list of all children with that tag name.
* Note that if there is a tag and an attribute with the same name, accessing it by name will return the attribute. You would need to use '''__children''' to access the tag.

For example, suppose you had a variable with the following WML content:

<syntaxhighlight lang=wml>
[my_variable]
stuff=777
something=a value
[something]
value=42
[/something]
[another_tag]
value=21
[/another_tag]
[subarray]
value=8
[/subarray]
[subarray]
value=91
[/subarray]
[another_tag]
value=12
[/another_tag]
[/my_variable]
</syntaxhighlight>

Then the formula could access the following variables on the '''value''' object:
* '''__all_children''': A list of ordered key-value pairs roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> ['value' -> 42], 'another_tag' -> ['value' -> 21], 'subarray' -> ['value' -> 8], 'subarray' -> ['value' -> 91], 'another_tag' -> ['value' -> 12]]</syntaxhighlight>
* '''__children''': A map roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> [['value' -> 42]], 'another_tag' -> [['value' -> 21], ['value' -> 12]], 'subarray' -> [['value' -> 8], ['value' -> 91]]]</syntaxhighlight>
* '''__attributes''': A map equivalent to <syntaxhighlight lang=wfl inline>['stuff' -> 777, 'something' -> 'a value']</syntaxhighlight>
* '''stuff''': The number <syntaxhighlight lang=wfl inline>777</syntaxhighlight>
* '''something''': The string <syntaxhighlight lang=wfl inline>'a value'</syntaxhighlight>
* '''another_tag''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 21], ['value' -> 12]]</syntaxhighlight>
* '''subarray''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 8], ['value' -> 91]]</syntaxhighlight>

{{DevFeature1.17|11}} When using a formula, you can now specify an additional key:

* '''as_type''': Specifies the type of the '''value''' object in the formula. The default is ''wml'', which uses the structure as described above. The other supported options are:
** ''unit'': Interprets the variable's value as a stored unit, allowing you to write the formula the same way you would in a [[StandardUnitFilter]].
** ''weapon'': Interprets the variable's value as an attack type, allowing you to write the formula the same way you would in a [[StandardWeaponFilter]].

=== [found_item] ===

{{DevFeature1.13|2}} Test if an item (ie, a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function.

* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

=== [proceed_to_next_scenario] ===

{{DevFeature1.13|10}} In SP, true if the scenario has been won.

=== [lua] ===

{{DevFeature1.13|11}} Evaluate a lua expression, which must return a boolean value. Useful for writing one-off conditions that are difficult to express with other tags, but for much-used conditions it's better to define a custom condition tag using [[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]].

* '''code''': The Lua expression.
* '''[args]''': Arbitrary data passed to the expression, accessible via <tt>...</tt> in the Lua code.

For example

<syntaxhighlight lang=wml>
[event]
name=new turn
first_time_only=no
[filter_condition]
[lua]
code = << return (wesnoth.get_variable("turn_number") % 2 == 0) >>
[/lua]
[/filter_condition]
[message]
speaker=narrator
message= "Hello world $turn_number|"
[/message]
[/event]
</syntaxhighlight>

=== Meta-Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
# this true or false result is combined with the top meta-condition to produce another true or false result
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.

== See Also ==
* [[SyntaxWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

ConditionalActionsWML

2023-01-25T18:30:34Z

Toranks: be more specific about foreach not supporting adding or removing elements

{{WML Tags}}

Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside '''[if]''' aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
** [[#Condition Tags|Condition Tags]]: Specifies the conditions, just like in '''[if]'''.
** '''[then]''': Specifies actions, exactly like the '''[then]''' tag inside '''[if]'''.

* '''[else]''': Contains [[ActionWML|actions]] which should be executed if all condition tags in the '''[if]''' and any directly nested '''[elseif]''' all evaluate as false.

'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.

Example usage:
<syntaxhighlight lang=wml>
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[elseif]
[variable]
name=we.gold
equals=$they.gold
[/variable]
[then]
[message]
message=This should be fair!
[/message]
[/then]
[/elseif]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
</syntaxhighlight>

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable. Boolean variable values are not accepted and cause lua errors currently.

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
<syntaxhighlight lang=wml>
[switch]
variable=foo
[case]
value="A"
# ... WML if foo=A ...
[/case]
[case]
value="B"
# ... WML if foo=B ...
[/case]
[else]
# ... WML if not foo=A nor foo=B ...
[/else]
[/switch]
</syntaxhighlight>

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false. Multiple '''[do]''' tags can be used, and they will be executed in sequence on each iteration. However, there is usually no reason to do this.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros. Note: This macro is deprecated; you should just use the '''[foreach]''' WML tag instead.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [for] ===

{{DevFeature1.13|2}}

Loops over an integer range. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.

* '''variable''': The name of the variable containing the current index. Defaults to ''i''. If there is already a variable with this name, it will be automatically saved before the start of the loop, and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, it will be automatically deleted, there is no need to do a '''[clear_variable]''' afterwards
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [foreach] ===

{{DevFeature1.13|2}}

Loops over an array variable. This is not used to implement the {FOREACH} macro because [foreach] doesn't support adding or removing elements while looping (and will usually raise an error). Use [for] instead.

* '''array''': The array variable to loop over.
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

The '''[foreach]''' tag simulates local-scoping of its index variables. If there was already a WML variable with the same name (by default ''i'' and ''this_item'' respectively), it will be automatically saved before the start of the '''[do]''', and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, there is no need to do a '''[clear_variable]''' afterwards.

It's possible to nest '''[foreach]''' loops, however it's strongly recommended avoid having both use the same ''variable='' name.

=== [repeat] ===

{{DevFeature1.13|2}}

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use [for] instead.)

* '''times''': The number of times to repeat the actions.
* '''[do]''': The actions to repeat. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

=== [true] ===

Represents a condition that always yields true. Takes no arguments.

=== [false] ===

Represents a condition that always yields false. Takes no arguments.

=== [have_unit] ===

A unit with greater than zero hit points matching this filter exists.

* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.
* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')

=== [have_location] ===

A location matching this filter exists.

* [[StandardLocationFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

=== [has_achievement] ===

{{DevFeature1.17|13}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

=== [variable] ===

Test the value of a WML [[SyntaxWML#Variables|variable]] against another value.

* '''name''': The name of the variable to test.
* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
** '''contains''': ''$name'' contains this string value.
** '''equals''': ''$name'' is equal (string wise) to this value.
** '''not_equals''': ''$name'' is not equal (string wise) to this value.
** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
** '''greater_than''': ''$name'' is numerically greater than this value.
** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.
** '''less_than''': ''$name'' is numerically less than this value.
** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.
** '''boolean_equals''': ''$name'' has an equivalent boolean value.
** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.
** '''formula''': {{DevFeature1.15|0}} ''$name'' satisfies the given [[Wesnoth_Formula_Language|WFL]] formula.

====Boolean Values====
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.

* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true.

'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

====Formulas====
When using a formula, the variable's value can be referenced as '''value''' in the formula. This is a WFL representation of a config object that supports the following fields:

* '''__all_children''': A list of key-value pairs, where the key is the tag name and the value is another config object representing the tag content.
* '''__children''': A map from tag name to a list of all children with that tag name.
* '''__attributes''': A map from attribute to value. Only useful if you specifically require a map for some reason.
* ''Any attribute name'': The value of that attribute
* ''Any tag name'': A list of all children with that tag name.
* Note that if there is a tag and an attribute with the same name, accessing it by name will return the attribute. You would need to use '''__children''' to access the tag.

For example, suppose you had a variable with the following WML content:

<syntaxhighlight lang=wml>
[my_variable]
stuff=777
something=a value
[something]
value=42
[/something]
[another_tag]
value=21
[/another_tag]
[subarray]
value=8
[/subarray]
[subarray]
value=91
[/subarray]
[another_tag]
value=12
[/another_tag]
[/my_variable]
</syntaxhighlight>

Then the formula could access the following variables on the '''value''' object:
* '''__all_children''': A list of ordered key-value pairs roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> ['value' -> 42], 'another_tag' -> ['value' -> 21], 'subarray' -> ['value' -> 8], 'subarray' -> ['value' -> 91], 'another_tag' -> ['value' -> 12]]</syntaxhighlight>
* '''__children''': A map roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> [['value' -> 42]], 'another_tag' -> [['value' -> 21], ['value' -> 12]], 'subarray' -> [['value' -> 8], ['value' -> 91]]]</syntaxhighlight>
* '''__attributes''': A map equivalent to <syntaxhighlight lang=wfl inline>['stuff' -> 777, 'something' -> 'a value']</syntaxhighlight>
* '''stuff''': The number <syntaxhighlight lang=wfl inline>777</syntaxhighlight>
* '''something''': The string <syntaxhighlight lang=wfl inline>'a value'</syntaxhighlight>
* '''another_tag''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 21], ['value' -> 12]]</syntaxhighlight>
* '''subarray''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 8], ['value' -> 91]]</syntaxhighlight>

{{DevFeature1.17|11}} When using a formula, you can now specify an additional key:

* '''as_type''': Specifies the type of the '''value''' object in the formula. The default is ''wml'', which uses the structure as described above. The other supported options are:
** ''unit'': Interprets the variable's value as a stored unit, allowing you to write the formula the same way you would in a [[StandardUnitFilter]].
** ''weapon'': Interprets the variable's value as an attack type, allowing you to write the formula the same way you would in a [[StandardWeaponFilter]].

=== [found_item] ===

{{DevFeature1.13|2}} Test if an item (ie, a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function.

* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

=== [proceed_to_next_scenario] ===

{{DevFeature1.13|10}} In SP, true if the scenario has been won.

=== [lua] ===

{{DevFeature1.13|11}} Evaluate a lua expression, which must return a boolean value. Useful for writing one-off conditions that are difficult to express with other tags, but for much-used conditions it's better to define a custom condition tag using [[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]].

* '''code''': The Lua expression.
* '''[args]''': Arbitrary data passed to the expression, accessible via <tt>...</tt> in the Lua code.

For example

<syntaxhighlight lang=wml>
[event]
name=new turn
first_time_only=no
[filter_condition]
[lua]
code = << return (wesnoth.get_variable("turn_number") % 2 == 0) >>
[/lua]
[/filter_condition]
[message]
speaker=narrator
message= "Hello world $turn_number|"
[/message]
[/event]
</syntaxhighlight>

=== Meta-Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
# this true or false result is combined with the top meta-condition to produce another true or false result
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.

== See Also ==
* [[SyntaxWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

Template:WML Tags

2023-01-22T19:33:30Z

Toranks: Achievements tags added

{| class="reference-sidebar"
|-
|
[[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit]]'''WML Tags'''
|-
|''A:''
[[AbilitiesWML|abilities]],
[[CreditsWML#.5Babout.5D|about]],
[[Creating_Custom_AIs#Behavior_Candidate_Actions|add_ai_behavior]],
[[SingleUnitWML|advance]],
[[AdvancedPreferenceWML|advanced_preference]],
[[AchievementsWML|achievement]],
[[AchievementsWML|achievements_group]],
[[UnitTypeWML|advancefrom]],
[[UnitTypeWML#After_max_level_advancement_.28AMLA.29|advancement]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|affect_adjacent]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|ai]],
[[StandardSideFilter|allied_with]],
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],
[[ConditionalActionsWML#Meta-Condition_Tags|and]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],
[[AnimationWML|animation]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|aspect]],
attack ([[ReplayWML|replay]], [[UnitTypeWML#Attacks|weapon]]),
[[AnimationWML|attack_anim]],
attacks ([[AbilitiesWML#The_.5Bspecials.5D_tag|special]], [[StatisticalScenarioWML#The_.5Bteam.5D_tag|stats]]),
[[AiWML#List_of_AI_Aspects|avoid]];
|-
|''B:''
[[UnitTypeWML#Other_tags|base_unit]],
[[IntroWML#.5Bbackground_layer.5D|background_layer]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|berserk]],
[[BinaryPathWML|binary_path]],
[[InternalActionsWML#Flow_control_actions|break]],
[[EditorWML#The_.5Bbrush.5D_tag|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML#.5Bcancel_action.5D|cancel_action]],
[[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|candidate_action]],
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|chance_to_hit]],
[[InterfaceActionsWML#.5Bchange_theme.5D|change_theme]],
[[InterfaceActionsWML#.5Bchat.5D|chat]],
[[OptionWML|checkbox]],
[[OptionWML|choice]],
[[ReplayWML|choose]],
[[PersistenceWML|clear_global_variable]],
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],
[[InternalActionsWML#.5Bclear_variable.5D|clear_variable]],
[[InterfaceActionsWML#.5Bcolor_adjust.5D|color_adjust]],
[[GameConfigWML#Color_Palettes|color_palette]],
[[GameConfigWML#Color_Palettes|color_range]],
command ([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]),
[[InternalActionsWML#Flow_control_actions|continue]],
[[CreditsWML#.5Bcredits_group.5D|credits_group]],
[[AiWML#The_.5Bgoal.5D_Tag|criteria]];
|-
|''D:''
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage]],
[[AnimationWML#death|death]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|deaths]],
[[AnimationWML#default|default]],
[[AnimationWML#defend|defend]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|defends]],
[[UnitsWML#.5Bmovetype.5D|defense]],
[[InterfaceActionsWML#.5Bdelay.5D|delay]],
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],
[[ReplayWML|destination]],
[[CampaignWML|difficulty]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|disable]],
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]],
[[DirectActionsWML#.5Bdo_command.5D|do_command]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|drains]],
[[AnimationWML#draw_weapon_anim|draw_weapon_anim]];
|-
|''E:''
[[EditorWML#The_.5Beditor_group.5D_tag|editor_group]],
[[EditorWML#The_.5Beditor_music.5D_tag|editor_music]],
[[EditorWML#The_.5Beditor_times.5D_tag|editor_times]],
[[EffectWML|effect]],
else ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]]), [[ConditionalActionsWML#.5Bif.5D|elseif]],
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],
end_turn ([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML|replay]]),
[[StandardSideFilter|enemy_of]],
[[Wesnoth_AI_Framework#Available_Engines|engine]],
entry ([[CreditsWML#.5Bentry.5D|credits]], [[OptionWML|options]]),
[[EraWML|era]],
[[EventWML|event]],
[[AnimationWML#Simplified_animation_blocks|extra_anim]];
|-
|''F:''
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]],
[[InterfaceActionsWML#.5Banimate_unit.5D|facing]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|fake_unit]],
[[ConditionalActionsWML#.5Bfalse.5D|false]],
[[PblWML#.5Bfeedback.5D|feedback]],
[[UnitTypeWML#Other_tags|female]],
filter ([[FilterWML|concept]], [[EventWML#.5Bfilter.5D|event]]),
[[StandardUnitFilter|filter_adjacent]],
[[StandardLocationFilter|filter_adjacent_location]],
[[FilterWML#Filtering_Weapons|filter_attack]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_attacker]],
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|filter_base_value]],
[[EventWML#.5Bfilter_condition.5D|filter_condition]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_defender]],
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_enemy]],
[[StandardLocationFilter|filter_location]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_opponent]],
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_own]],
[[StandardLocationFilter|filter_owner]],
[[StandardLocationFilter|filter_radius]],
[[SingleUnitWML|filter_recall]],
[[StandardUnitFilter|filter_second]],
[[FilterWML#Filtering_Weapons|filter_second_attack]],
[[AbilitiesWML|filter_self]],
[[StandardSideFilter|filter_side]],
[[AbilitiesWML|filter_student]],
[[FilterWML#Filtering_Vision|filter_vision]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_weapon]],
[[FilterWML#Filtering_on_WML_data|filter_wml]],
[[InternalActionsWML#.5Bfind_path.5D|find_path]],
[[InternalActionsWML#.5Bfire_event.5D|fire_event]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]],
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],
[[ConditionalActionsWML#.5Bfound_item.5D|found_item]],
[[ConditionalActionsWML#.5Bfor.5D|for]],
[[ConditionalActionsWML#.5Bforeach.5D|foreach]],
[[AnimationWML#Frames|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[PersistenceWML|get_global_variable]],
[[AiWML#The_.5Bgoal.5D_Tag|goal]],
[[DirectActionsWML#.5Bgold.5D|gold]],
[[InterfaceActionsWML#.5Bobjectives.5D|gold_carryover]];
|-
|''H:''
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],
[[StandardSideFilter|has_ally]],
[[StandardUnitFilter|has_attack]],
[[StandardSideFilter|has_unit]],
[[ConditionalActionsWML#.5Bhas_achievement.5D|has_achievement]],
[[ConditionalActionsWML#.5Bhave_location.5D|have_location]],
[[ConditionalActionsWML#.5Bhave_unit.5D|have_unit]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|heal_on_hit]],
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],
[[AnimationWML#healed|healed_anim]],
[[AnimationWML#healing|healing_anim]],
[[AbilitiesWML|heals]],
[[UnitsWML#.5Bhide_help.5D|hide_help]],
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]],
[[AbilitiesWML|hides]];
|-
|''I:''
[[AnimationWML#idling|idle_anim]],
if ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]], [[IntroWML|intro]]),
[[AbilitiesWML|illuminates]],
image ([[IntroWML#.5Bimage.5D|intro]], [[TerrainGraphicsWML|terrain]]),
[[ReplayWML|init_side]],
[[InternalActionsWML#.5Binsert_tag.5D|insert_tag]],
[[InterfaceActionsWML#.5Binspect.5D|inspect]],
[[InterfaceActionsWML#.5Bitem.5D|item]],
[[EditorWML#The_.5Bitem_group.5D_tag|item_group]];
|-
|''J:''
[[UnitsWML#.5Bmovetype.5D|jamming_costs]],
[[InternalActionsWML#.5Bset_variable.5D|join]];
|-
|''K:''
[[DirectActionsWML#.5Bkill.5D|kill]],
[[StatisticalScenarioWML|killed]];
|-
|''L:''
[[InterfaceActionsWML#.5Blabel.5D|label]],
[[LanguageWML|language]],
[[SideWML|leader]],
[[AiWML#List_of_AI_Aspects|leader_goal]],
[[AbilitiesWML|leadership]],
[[AnimationWML#leading|leading_anim]],
[[AnimationWML#levelin|levelin_anim]],
[[AnimationWML#levelout|levelout_anim]],
[[DirectActionsWML#.5Blift_fog.5D|lift_fog]],
[[AI_Recruitment#Aspect_recruitment_instructions|limit]],
[[InternalActionsWML#.5Bset_variables.5D|literal]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|load_resource]],
[[LocaleWML|locale]],
[[InterfaceActionsWML#.5Block_view.5D|lock_view]],
[[LuaWML|lua]];
|-
|''M:''
[[UnitTypeWML#Other_tags|male]],
[[SavefileWML|menu_item]],
[[InterfaceActionsWML#.5Bmessage.5D|message]],
[[Micro AIs|micro_ai]],
[[AnimationWML#The_content_of_a_frame|missile_frame]],
[[ModificationWML|modification]],
[[SingleUnitWML|modifications]],
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],
[[ModificationWML|modify_unit_type]],
[[ReplayWML|move]],
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],
[[AnimationWML#movement|movement_anim]],
[[UnitsWML#.5Bmovetype.5D|movement costs]],
[[UnitsWML#.5Bmovetype.5D|movetype]],
[[ScenarioWML|multiplayer]],
[[EraWML|multiplayer_side]],
[[MusicListWML#.5Bmusic.5D|music]];
|-
|''N:''
[[ConditionalActionsWML#Meta-Condition_Tags|not]],
[[InterfaceActionsWML#.5Bobjectives.5D|note]];
|-
|''O:''
[[DirectActionsWML#.5Bobject.5D|object]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],
[[DirectActionsWML#.5Bon_undo.5D|on_undo]],
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],
[[InterfaceActionsWML#.5Bmessage.5D|option]],
[[OptionWML|options]],
[[ConditionalActionsWML#Meta-Condition_Tags|or]];
|-
|''P:''
[[IntroWML|part]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]],
[[DirectActionsWML#.5Bpetrify.5D|petrify]],
[[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|plague]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|poison]],
[[UnitTypeWML#Other_tags|portrait]],
[[AnimationWML#post_movement|post_movement_anim]],
[[AnimationWML#pre_movement|pre_movement_anim]],
[[InternalActionsWML#.5Bfire_event.5D|primary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|primary_unit]],
[[InterfaceActionsWML#.5Bprint.5D|print]],
[[DirectActionsWML#.5Bput_to_recall_list.5D|put_to_recall_list]];
|-
|''R:''
[[UnitsWML#.5Brace.5D|race]],
[[InternalActionsWML#.5Brandom_placement.5D|random_placement]],
recall ([[DirectActionsWML#.5Brecall.5D|action]], [[ReplayWML|replay]]),
[[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]],
[[AnimationWML#recruited|recruit_anim]],
[[AnimationWML#recruiting|recruiting_anim]],
[[StatisticalScenarioWML|recruits]],
[[InterfaceActionsWML#.5Bredraw.5D|redraw]],
[[AbilitiesWML|regenerate]],
[[InternalActionsWML#.5Bremove_event.5D|remove_event]],
[[InterfaceActionsWML#.5Bremove_item.5D|remove_item]],
[[DirectActionsWML#.5Bremove_object.5D|remove_object]],
[[DirectActionsWML#.5Bremove_shroud.5D|remove_shroud]],
[[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]],
[[DirectActionsWML#.5Bremove_time_area.5D|remove_time_area]],
[[DirectActionsWML#.5Bremove_trait.5D|remove_trait]],
[[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],
[[ConditionalActionsWML#.5Brepeat.5D|repeat]],
[[DirectActionsWML#.5Breplace_map.5D|replace_map]],
[[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]],
[[ReplayWML|replay]],
[[SavefileWML|replay_start]],
[[DirectActionsWML#.5Breset_fog.5D|reset_fog]],
resistance ([[AbilitiesWML|ability]], [[UnitsWML#.5Bmovetype.5D|unit]]),
[[UnitsWML#.5Bresistance_defaults.5D|resistance_defaults]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|resource]],
[[InternalActionsWML#Flow_control_actions|return]],
[[InternalActionsWML#.5Brole.5D|role]],
[[TerrainMaskWML|rule]];
|-
|''S:''
[[SavefileWML|save]],
[[ScenarioWML|scenario]],
[[InterfaceActionsWML#.5Bscroll.5D|scroll]],
[[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_unit]],
[[HelpWML|section]],
[[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]],
[[ReplayWML|sequence]],
[[DirectActionsWML#.5Bset_achievement.5D|set_achievement]],
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],
[[PersistenceWML|set_global_variable]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]],
[[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],
[[EffectWML|set_specials]],
[[InternalActionsWML#.5Bset_variable.5D|set_variable]],
[[InternalActionsWML#.5Bset_variables.5D|set_variables]],
[[AnimationWML#sheath_weapon|sheath_weapon_anim]],
show_if ([[InterfaceActionsWML#.5Bmessage.5D|message]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]]),
[[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],
[[SideWML|side]],
[[AbilitiesWML|skirmisher]],
[[OptionWML|slider]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|slow]],
[[SavefileWML|snapshot]],
[[InterfaceActionsWML#.5Bsound.5D|sound]],
[[InterfaceActionsWML#.5Bsound_source.5D|sound_source]],
source ([[ReplayWML|replay]], [[DirectActionsWML#.5Btunnel.5D|teleport]]),
[[UnitTypeWML#Other_tags|special_note]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|specials]],
[[InternalActionsWML#.5Bset_variables.5D|split]],
[[Wesnoth_AI_Framework#Available_Stages|stage]],
[[AnimationWML#standing|standing_anim]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[SingleUnitWML|status]],
[[InternalActionsWML#.5Bstore_gold.5D|store_gold]],
[[InternalActionsWML#.5Bstore_items.5D|store_items]],
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],
[[InternalActionsWML#.5Bstore_relative_direction.5D|store_relative_direction]],
[[InternalActionsWML#.5Bstore_side.5D|store_side]],
[[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]],
[[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]],
[[InternalActionsWML#.5Bstore_turns.5D|store_turns]],
[[InternalActionsWML#.5Bstore_unit.5D|store_unit]],
[[InternalActionsWML#.5Bstore_unit_defense.5D|store_unit_defense]],
[[InternalActionsWML#.5Bstore_unit_defense_on.5D|store_unit_defense_on]],
[[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]],
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]],
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]],
[[IntroWML|story]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]],
[[InternalActionsWML#.5Bsync_variable.5D|sync_variable]];
|-
|''T:''
[[DirectActionsWML#.5Btunnel.5D|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
teleport ([[AbilitiesWML|ability]], [[DirectActionsWML#.5Bteleport.5D|action]]),
[[AnimationWML#pre_teleport|teleport_anim]],
[[DirectActionsWML#.5Bterrain.5D|terrain]],
[[UnitsWML#.5Bterrain_defaults.5D|terrain_defaults]],
[[TerrainGraphicsWML|terrain_graphics]],
[[TerrainMaskWML|terrain_mask]],
[[TerrainWML|terrain_type]],
[[ScenarioWML#Test_scenario|test]],
[[InterfaceActionsWML#.5Btest_condition.5D|test_condition]],
[[InterfaceActionsWML#.5Bmessage.5D|text_input]],
[[GettextForWesnothDevelopers#The_textdomain_declaration|textdomain]],
[[ThemeWML|theme]],
[[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]],
[[TimeWML|time]],
[[DirectActionsWML#.5Btime_area.5D|time_area]],
[[HelpWML|topic]],
[[HelpWML|toplevel]],
[[UnitsWML#.5Btrait.5D|trait]],
[[DirectActionsWML#.5Btransform_unit.5D|transform_unit]],
[[InternalActionsWML#.5Bfind_path.5D|traveler]],
[[ConditionalActionsWML#.5Btrue.5D|true]],
[[DirectActionsWML#.5Btunnel.5D|tunnel]],
[[ScenarioWML|tutorial]];
|-
|''U:''
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]],
[[SingleUnitWML|unit]],
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]],
[[UnitTypeWML|unit_type]],
[[InternalActionsWML#.5Bunit_worth.5D|unit_worth]],
[[UnitsWML|units]],
[[InterfaceActionsWML#.5Bunlock_view.5D|unlock_view]],
[[DirectActionsWML#.5Bunpetrify.5D|unpetrify]],
[[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]],
[[InternalActionsWML#.5Bunsynced.5D|unsynced]];
|-
| ''V:''
[[InternalActionsWML#.5Bset_variables.5D|value]],
[[ConditionalActionsWML#.5Bvariable.5D|variable]],
[[VariablesWML#The_.5Bvariables.5D_tag|variables]],
[[TerrainGraphicsWML|variant]],
[[UnitTypeWML#Other_tags|variation]],
[[AnimationWML#victory|victory_anim]],
[[SideWML|village]],
[[UnitsWML#.5Bmovetype.5D|vision_costs]],
[[InterfaceActionsWML#.5Bvolume.5D|volume]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]],
[[SchemaWML|wml_schema]];
|-
| ''Z:''
[[InterfaceActionsWML#.5Bzoom.5D|zoom]];
|}<includeonly>[[Category:WML Reference]]</includeonly><noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the WML reference pages.</noinclude>

Talk:GameConfigWML

2023-01-22T15:36:31Z

Toranks:

Outdated info? In game_config.cfg for 1.10 I see another keys and values.

All the '''option_image=''' keys have been moved to the '''[images] option=''' tag

There are also several undocumented tags '''[colors]''' ,'''[sounds]''' etc.

WesnothTranslations

2023-01-20T14:44:43Z

Toranks: It's my alias

== Translations ==

Wesnoth is currently being translated into the following languages. Instructions on how to contribute are found here:
[[WesnothTranslationsHowTo]].

{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AfrikaansTranslation|Afrikaans]] || None || N/A
|-
| [[AncientGreekTranslation|Ancient Greek]] || None || N/A
|-
| [[ArabicTranslation|Arabic]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[BasqueTranslation|Basque]] || None || N/A
|-
| [[BurmeseTranslation|Burmese]] || None || N/A
|-
| [[BulgarianTranslation|Bulgarian]] || Ivan Petrov (TheWhiteKnight) || [mailto:vankata_petrovATabvDOTbg]
|-
| [[CatalanTranslation|Catalan]] || Miquel-Àngel Burgos i Fradeja || [mailto:miquel.angel.burgosATgmailDOTcom]
|-
| [[ChineseTranslation|Chinese]] || CloudiDust || [mailto:cloudidustATgmailDOTcom]
|-
| [[ChineseTaiwanTranslation|Chinese (Taiwan)]] || 楊綮銘 (Taiwan) || [mailto:steven2880ATgmailDOTcom]
|-
| [[CroatianTranslation|Croatian]] || None || N/A
|-
| [[CzechTranslation|Czech]] || Michal Žejdl || [mailto:lachimATemerDOTcz]
|-
| [[DanishTranslation|Danish]] || None || N/A
|-
| [[DutchTranslation|Dutch]] || Merijn de Vet || [mailto:tybonzerATliveDOTnl]
|-
| [[EnglishGBTranslation|English (GB)]] || Wedge009 || [mailto:wedge009ATwedge009DOTnet]
|-
| [[EnglishShawTranslation|English (Shaw)]] || Arc Riley || [mailto:ArcRileyATubuntuDOTcom]
|-
| [[Esperanto_translation|Esperanto]] || Luther Thompson || [mailto:lutherATlibremDOTone]
|-
| [[EstonianTranslation|Estonian]] || None || N/A
|-
| [[FilipinoTranslation|Filipino]] || None || N/A
|-
| [[FinnishTranslation|Finnish]] || Jaakko Saarikko (styxnix) || [mailto:jaakkoDOTsaarikkoATprotonmailDOTcom]
|-
| [[FrenchTranslation|French]] || Mathieu Guilbaud (Guim) || Translations ML
|-
| [[GalicianTranslation|Galician]] || None || N/A
|-
| [[GermanTranslation|German]] || Aaron Winter (Bitron) ||
|-
| [[GreekTranslation|Greek]] || None || N/A
|-
| [[HebrewTranslation|Hebrew]] || None || N/A
|-
| [[HungarianTranslation|Hungarian]] || Széll András || [mailto:szellDOTandrisATgmailDOTcom]
|-
| [[IcelandicTranslation|Icelandic]] || None || N/A
|-
| [[IndonesianTranslation|Indonesian]] || Irsyad Musthafa || [mailto:sevennightmareATtutanotaDOTde]
|-
| [[IrishTranslation|Irish]] || None || N/A
|-
| [[ItalianTranslation|Italian]] || Antonio Rosella || [mailto:arosellaATyahooDOTcom]
|-
| [[JapaneseTranslation|Japanese]] || Hironori Fujimoto (RatArmy) || [mailto:broadbarredfirefishATgmailDOTcom]
|-
| [[KoreanTranslation|Korean]] || mistzone || [mailto:drier22ATgmailDOTcom]
|-
| [[LatinTranslation|Latin]] || None || N/A
|-
| [[LatvianTranslation|Latvian]] || None || N/A
|-
| [[LithuanianTranslation|Lithuanian]] || None || N/A
|-
| [[MarathiTranslation|Marathi]] || None || N/A
|-
| [[MacedonianTranslation|Macedonian]] || None || N/A
|-
| [[NorwegianTranslation|Norwegian]] || None || N/A
|-
| [[OldEnglishTranslation|Old English]] || None || N/A
|-
| [[PolishTranslation|Polish]] || ForPeace || [https://forums.wesnoth.org/viewtopic.php?f=7&t=3796 forum thread]
|-
| [[PortugueseTranslation|Portuguese Brazilian]] || Andrei Machado || [mailto:andreisp.machadoATyahooDOTcom]
|-
| [[PortugueseContinentalTranslation|Portuguese (European)]] || trewe || [mailto:sjrs456ATyahooDOTfr]
|-
| [[RACVTranslation|RACV]] || None || N/A
|-
| [[RomanianTranslation|Romanian]] || None || N/A
|-
| [[RussianTranslation|Russian]] || Artem Khrapov || ([[User:kabachuha|kabachuha]]) [mailto:artemkhrapov2001ATyandexDOTru]
|-
| [[Scottish_Gaelic_Translation|Scottish Gaelic]] || GunChleoc || [mailto:fiosAIGforamnagaidhligDOTnet]
|-
| [[SerbianTranslation|Serbian]] || None || N/A
|-
| [[SlovakTranslation#Preklad|Slovak]] || Aceman ||
|-
| [[SlovenianTranslation|Slovenian]] || None || N/A
|-
| [[SpanishTranslation|Spanish]] || Toranks || [mailto:davinciATtoranksDOTes]
|-
| [[SpanishLatinAmericanTranslation|Spanish (Latin American)]] || None || N/A
|-
| [[SwedishTranslation|Swedish]] || Alex Alowersson (fluxbird) || [mailto:alexalowersonATgmailDOTcom]
|-
| [[TurkishTranslation|Turkish]] || Nilgün Belma Bugüner || [mailto:nilgunATbelgelerDOTorg]
|-
| [[UkrainianTranslation|Ukrainian]] || None || N/A
|-
| [[ValencianTranslation|Valencian]] || None || N/A
|-
| [[VietnameseTranslation|Vietnamese]] || None || N/A
|}

== Mailing List ==

There now is a mailing list dedicated to translation matters. It is mainly intended to be used for informing translation maintainers about important changes, to announce string freezes and other special things. Everyone is free to subscribe to this list.

* [https://listengine.tuxfamily.org/wesnoth.org/i18n/ List info, how to subscribe, and archives from April 2022]
* [https://mailman.wesnoth.org/pipermail/i18n/ Old list archives (up until April 2022)]

Please keep in mind that this list is not meant for discussing changes for one single translation but instead subjects which are relevant to all translations.

== See also ==

* [[WesnothTranslationsHowTo]]
* [[ImageLocalization]]
* [[GetText]]
* [http://gettext.wesnoth.org Translations statistics (stable)]
* [http://gettext.wesnoth.org/index.php?version=trunk&package=alloff Translations statistics (development)]
* [[WesCamp| Translating User made Campaigns (featuring WesCamp-i18n)]]
* [[SpellingMistakes]]
* [[CharactersStorys| Character descriptions for Translators (Spoiler Warning)]]
* [[Poetry of Wesnoth Translations]]

[[Category:Translations|*]]

DirectActionsWML

2023-01-13T13:08:02Z

Toranks: x and y positions can be changed too

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/SingleUnitWML filter_recall] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]''' (not sure on this one)
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} events in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} event, interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an [enter_hex] event on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an [enter_hex] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

FilterWML

2023-01-05T03:27:42Z

Toranks: attacks changed to strikes, to be more specific

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location.
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''number''': {{DevFeature1.13|5}} filter on number of strikes
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]. The context object for the formula is a '''weapon object''', which supports the following keys: '''name''', '''description''', '''type''', '''icon''', '''range''', '''damage''', '''number''', '''attack_weight''', '''defense_weight''', '''accuracy''', '''parry''', '''movement_used''', '''specials'''. The '''specials''' key is a list of all the special IDs the unit possesses. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Filtering on WML data ==

Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. The following conventions are possible:

* '''key=value''': Means that the key '''key''' must be present with the specified value.
* '''glob_on_key=glob''': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_key=*''' in a '''[not]''' tag.
* '''[some_tag]''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.

== Tutorial ==
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]