The Battle for Wesnoth Wiki - User contributions [en]

DirectActionsWML

2021-06-30T00:10:18Z

EliDupree: /* [do_command] */

{{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.
* '''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 add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit 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.
* '''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.
* '''extra_recruit''': the types of units that the side 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.
* '''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.
* '''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]''', '''[secondary_attack]''' {{DevFeature1.13|8}} The attacks to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by.

=== [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 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'''
* '''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.
* '''id''': (Optional) allows the item to be removed later. 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.
* '''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.
* '''[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).
* '''[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 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 worked the following way: Step1) remove thos objects from the unit wml, Step2) Rebuild the unit to make the changes effective. Step2 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 [modify_unit] to get a list of properties that can safely be changes via [modify_unit]

=== [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 (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.
* '''[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.

=== [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.
* '''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''': Content of a wesnoth map file. Example:
map="{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 [http://www.wesnoth.org/macro-reference.xhtml 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

2021-06-29T23:51:15Z

EliDupree: /* [do_command] */

{{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.
* '''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 add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit 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.
* '''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.
* '''extra_recruit''': the types of units that the side 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.
* '''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.
* '''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]''', '''[secondary_attack]''' {{DevFeature1.13|8}} The attacks to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by.

=== [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 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'''
* '''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.
* '''id''': (Optional) allows the item to be removed later. 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.
* '''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.
* '''[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).
* '''[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 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 worked the following way: Step1) remove thos objects from the unit wml, Step2) Rebuild the unit to make the changes effective. Step2 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 [modify_unit] to get a list of properties that can safely be changes via [modify_unit]

=== [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 (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.
* '''[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.

=== [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.
* '''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''': Content of a wesnoth map file. Example:
map="{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 is intended to always be replay safe. However, in practice (as of Wesnoth 1.15.14), it appears to only be replay safe if invoked in an unsynced context, such as a select event or a menu item with `synced = false`. If invoked in a turn refresh event, for example, the command may not be recorded in the replay, resulting in out-of-sync errors during the replay.

=== [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 [http://www.wesnoth.org/macro-reference.xhtml 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]]

LuaAPI/filesystem

2021-06-27T23:59:32Z

EliDupree:

This module contains functions for working with files on disk, providing read-only access to the data and userdata directories.

=== filesystem.read_file ===

* '''filesystem.read_file'''(''file_path'') → ''file_contents''

Loads a file into memory and returns it as a string. The rules for locating the files are the same as for WML files, but with no requirements on file extension. If the path points to a directory, it instead returns a table containing a list of directory entries, sorted alphabetically with directories grouped at the beginning. In this case, there is also an '''ndirs''' member which contains the number of entries that are directories, allowing you to easily skip the directories if you wish.

=== filesystem.have_file ===

* '''filesystem.have_file'''(''file_path''[, ''only_as_regular_file'']) → ''boolean''

Checks if a file exists. The rules for locating the files are the same as for WML files. Using the second parameter, you can distinguish regular files from directories.

=== filesystem.canonical_path ===

* '''filesystem.canonical_path'''(''file_path'') → ''path''

Returns the path resolved relative to the current script and with any dotfiles stripped out. The returned path is still relative to the data or userdata directory.

=== filesystem.image_size ===

* '''filesystem.image_size(''filename'')''' → ''width'', ''height'

Returns the width and height of an image.

<syntaxhighlight lang=lua>
local w, h = filesystem.image_size "units/transport/galleon.png"
</syntax_highlight>

=== filesystem.have_asset ===

* '''filesystem.have_asset'''(''asset_type'', ''path'') → ''exists''

Tests whether an asset file exists in the current binary path. The ''asset_type'' will usually be one of the following constants in '''filesystem.asset_type''':

* '''IMAGE'''
* '''MUSIC'''
* '''MAP'''
* '''SOUND'''

However, it can be any arbitrary string. You could conceivably define a custom asset type in this way.

=== filesystem.resolve_asset ===

* '''filesystem.resolve_asset'''(''asset_type'', ''path'') → ''resolved path''

Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will always begin with the string "data/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with '''wesnoth.read_file''', this prefix must be stripped off.

StandardSideFilter

2018-06-23T19:18:51Z

EliDupree:

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering on sides. Often a SSF needs to be included in a [filter_side] tag. There are however also many tags that take the SSF tags and keys directly as arguments.

The following attributes and sub-tags are permitted:

* '''side''': filter matches only if side number is contained in a comma-separated list. Note that as opposed to the usual inline side= key in wml action tags, which defaults to 1, the side= key in a SSF defaults to all sides (similarly, the id= key in SUFs defaults to all ids). This key also accepts ranges (i.e. "1,3-4,6")
* '''[has_unit]''':
**'''[[StandardUnitFilter]]''': filter matches only if side controls a unit matched by it
**'''search_recall_list''': (boolean yes|no, default no) whether to include recall list units when trying to match this [[StandardUnitFilter]] against a unit

* '''team_name''': The currently filtered side matches only if this passed team_name is contained in its (the filtered side's) team_name= string. Note that a side can be allied/on the same team like 2 (more...) other sides which can be enemies at the same time. (achieved by defining a side via [side]team_name=1,2 etc.)

* '''[enemy_of]''': The currently filtered side must be an enemy of all of the sides matching this StandardSideFilter for it to match. If this inner StandardSideFilter matches no sides, the outer filter also doesn't. Note that a side is not an enemy of itself.
**StandardSideFilter tags and keys

* '''[allied_with]''': The currently filtered side must be allied with all of the sides matching this StandardSideFilter for it to match. If this inner StandardSideFilter matches no sides, the outer filter also doesn't. Note that a side is allied with itself.
**StandardSideFilter tags and keys

* '''[has_enemy]''': The currently filtered side must have at least one enemy matching this StandardSideFilter for it to match. (Note that a side is not an enemy of itself.)
**StandardSideFilter tags and keys.

* '''[has_ally]''': The currently filtered side must have at least one ally matching this StandardSideFilter for it to match. (Note that a side is allied with itself.)
**StandardSideFilter tags and keys.

* '''controller''': The currently filtered side matches only if it has this controller string. Sensible values are ai, human, and null. This key is disabled for networked multiplayer, since there the controller value of a side may differ between the clients. Thus using this key would inevitably lead to OOS errors.

* '''formula''': {{DevFeature1.13|5}} A formula using [[Wesnoth Formula Language]]

Also, [and], [or], and [not] subfilters are supported.

Interaction of SSF and side= in tags like [remove_shroud] :
In case that inline side= and [filter_side] are given, inline side= is ignored and [filter_side]side= gets priority:

selects side 4 and 5:
[remove_shroud]
side=2
[filter_side]
side=4,5
[/filter_side]
[remove_shroud]

InternalActionsWML

2018-06-23T19:18:09Z

EliDupree: /* [store_side] */

{{WML Tags}}

Part of [[ActionWML]], Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.

== Variable Actions ==

These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.

=== [set_variable] ===

The '''[set_variable]''' tag is used to create and manipulate WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.

* '''name''': the name of the variable to manipulate

* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])

* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollar signs.

* '''to_variable''': set the variable to the value of the given variable, e.g. 'to_variable=temp' would be equivalent to 'value=$temp'.

* '''add''': add the given amount to the variable.

* '''sub''': subtract the given amount from the variable.

* '''multiply''': multiply the variable by the given number. The result is a float. To negate a number, multiply by -1. If you negate 0, the result is a floating-point negative zero -0. To display -0 as 0, use a second tag with add=0; it will flip -0 to 0 but not affect other numbers.

* '''divide''': divide the variable by the given number. The result is a float. Wesnoth 1.9 and later no longer uses integer division. Use a second tag with round=floor if you relied on this.

* '''modulo''': returns the remainder of a division.

* '''abs''': Returns the absolute value of the variable.

* '''root''': Use '''root=square''' to calculate the square root. {{DevFeature1.15|0}} Also supports '''root=cube''' and arbitrary integer roots.

* '''power''': Raise the variable to some power.

* '''rand''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'rand=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'rand=3..5'. You may combine these, e.g. 'rand=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. If a number or item is repeated, it is sampled more frequently as appropriate. See [[MultiplayerContent]] for more info on the MP case. Using rand= will automatically result in the current action being non undoable. Ignoring possible [allow_undo].

* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.

* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).

* '''[join]''' joins an array of strings to create a textual list
** '''variable''': name of the array
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to connect the elements
** '''remove_empty''': whether to ignore empty elements

* '''ipart''': Assigns the integer part (the part to the left of the decimal point) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the decimal point) of the referenced variable.

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.
**'''round=trunc''': {{DevFeature1.15|0}} Rounds towards zero; this is the same operation as '''ipart''', but operating on the value already contained in the variable rather than the value assigned to the key.

* '''formula''': Calculate the new value of the variable from a WFL formula operating on the old value. This is similar to using the '''$(...)''' syntax but avoids the possibility of WFL syntax errors if a referenced variable is empty.

=== [set_variables] ===

Manipulates a WML array or container

* '''name''': the name of the array or container to manipulate

* '''mode''': one of the following values:
** ''replace'': will clean the array '''name''' and replace it with given data
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''. Attributes in '''[value]''' will overwrite any existing already in '''name'''. Tags in '''[value]''' modify the corresponding tag of the original value of '''name''', so for example the first '''[attack]''' tag in '''[value]''' would modify the first '''[attack]''' tag of '''name''' rather than appending a new '''[attack]''' tag. A few special syntaxes are supported:
*** ''__remove=yes'': When used in a subtag, causes the corresponding subtag in '''name''' to be deleted rather than merged. Deletion happens after any other subtags have been merged.
*** ''add_to_xxx'': Adds its integer value to the integer value of ''xxx'' in '''name'', and sets ''xxx'' in '''name''' to the result. {{DevFeature1.13|8}} Now adds as real numbers rather than integers.
*** ''concat_to_xxx'': {{DevFeature1.13|8}} Similar to ''add_to_xxx'', but does string concatenation instead of numerical addition.
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

* '''to_variable''': data will be set to the given array

* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])

* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags

*'''[split]''' splits a textual list into an array which will then be set to data
** '''list''': textual list to split
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to separate the elements
** '''remove_empty''': whether to ignore empty elements

{{DevFeature1.13|4}} You can now mix '''[value]''', '''[literal]''', and '''[split]''' in the same '''[set_variables]''' tag. They will be processed in order of appearance. Multiple instances of [split] are also supported now.

=== Capturing Game Data ===

These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.

==== [store_gold] ====

Stores a side's gold into a variable.

* '''[[StandardSideFilter]]''': The first matching side's gold will be stored in the variable "variable".
* '''variable''': (default='gold') the name of the variable to store the gold in

==== [store_locations] ====

Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only). The array will include any unreachable border hexes, if applicable.

* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. By default, all locations on the map are stored.

* '''variable''': the name of the variable (array) into which to store the locations.

* '''mode''': {{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and locations which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and locations which match the filter will be added to the array after the existing elements.

==== [store_reachable_locations] ====

Stores locations reachable by the given units. Can store either the movement, attack or vision ranges.

* '''[filter]''': a [[StandardUnitFilter]]. The locations reachable by any of the matching units will be stored.
* '''[filter_location]''': (optional) a [[StandardLocationFilter]]. Only locations which also match this filter will be stored.
* '''range''': possible values ''movement'' (default), ''attack'', ''vision''. If ''movement'', stores the locations within the movement range of the unit, taking Zone of Control into account. If ''attack'', stores the attack range (movement range + 1 hex). If ''vision'', stores the vision range (movement range ignoring Zone of Control + 1 hex).
* '''moves''': possible values ''current'' (default), ''max''. Specifies whether to use the current or maximum movement points when calculating the range.
* '''viewing_side''': (optional) the side whose vision to use when calculating the reach. This only has meaning in the presence of fog, shroud, or units with the ambush ability. If left out, then fog, shroud and ambushers are ignored and the real reach of the units is stored.
* '''variable''': the name of the variable (array) into which to store the locations.

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are sides matching the filter. If mode is set to ''append'', the variable will not be cleared, and sides which match the filter will be added to the array after the existing elements.
'''Result'''

Variable will contain following members:
* '''color''': It indicates team color. Can be one of the following:
{| border = 1
| ''color''
| red
| blue
| green
| purple
| black
| brown
| orange
| white
| teal
|-
| ''value''
| 1
| 2
| 3
| 4
| 5
| 6
| 7
| 8
| 9
|}
* '''controller''': Indicates type of player that control this side. ''Note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''null''': If players assigns "Empty" to "Player/Type" in game lobby
* '''fog''': Indicates whether this side is affected by fog of war.
* '''gold''': The amount of gold the side has.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Income for this side (base income + all village income. AKA gross income. Note that this is different from the [side] income key).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''team_name''': String representing the team's description.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''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|7}} When the side will be considered defeated. See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''faction''': {{DevFeature1.13|7}} id of the selected faction, string (multiplayer-only)
* '''faction_name''': {{DevFeature1.13|7}} Name of the selected faction, string (multiplayer-only)
* '''num_units''' {{DevFeature1.13|7}}: The number of units the side currently has on the map.
* '''num_villages''' {{DevFeature1.13|7}}: The number of villages the side currently controls.
* '''total_upkeep''' {{DevFeature1.13|7}}: The number of unit levels the side is currently supporting.
* '''expenses''' {{DevFeature1.13|7}}: The amount of gold the side is currently spending to support units.
* '''net_income''' {{DevFeature1.13|7}}: The income the side gains per turn after expenses.
* '''base_income''' {{DevFeature1.13|8}}: The income the side gains per turn (same as [side] income key)

* {{DevFeature1.13|7}} All other keys and tags of the side that are contained in [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] .__cfg

==== [store_starting_location] ====

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' and 'owner_side' (villages only)

* [[StandardSideFilter]]: The starting locations of all matching sides will be stored. If multiple sides are matched, a WML array will be created.
* '''variable''': (default='location'): the name of the variable to store the location in
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and the starting locations of the sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and the starting locations of the matching sides will be added to the array after the existing elements.

==== [store_time_of_day] ====

Stores time of day information from the current scenario into a WML variable container.

* '''x, y''': Location to store the time for. [[DirectActionsWML#.5Btime_area.5D|Time areas]] matter; illumination does not. If this is omitted, the global (location-independent) time is stored.

* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].

* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.

==== [store_turns] ====

Stores the turn limit (the maximum number of turns). If there is no limit, this stores ''-1''.

* '''variable''': (default='turns') the name of the variable in which to store the turn limit.

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample '''list of these tags and keys''' can be found at [[InternalActionsWMLUnitTags]].

If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file). One can also use the [[CommandMode|:inspect]] command or the [[InterfaceActionsWML#.5Binspect.5D|[inspect]]] tag to open a game-state inspector dialog, which can be used to view unit properties.

Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] to re-create the unit with the modified variables.

''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] and [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH].''

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables. The units will be stored in order of their internal ''underlying_id'' attribute, which is usually in creation order (but you normally should not depend on the order).

* '''variable''': the name of the variable into which to store the unit(s)

* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and units which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are units matching the filter. If mode is set to ''append'', the variable will not be cleared, and units which match the filter will be added to the array after the existing elements.

* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.

==== [store_unit_defense] ====

{{DevFeature1.13|9}}

Stores in a variable the defense of a unit on a particular terrain. If terrain or location is not specified, the terrain on which the unit currently stands is used. (Note: it is a WML defense, so the higher it is, the weaker unit's defense is.)

* StandardUnitFilter
* '''loc_x''', '''loc_y''': x and y of a valid map location. The terrain on this location will be used for the defense calculation.
* '''terrain''': The terrain code for which unit defense should be calculated. If '''terrain''' is specified, '''loc_x''' and '''loc_y''' are ignored.
* '''variable''': the name of the variable into which to store the defense. default: "terrain_defense"

==== [store_unit_type] ====

Stores a unit type definition into a variable.

* '''type''': (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.

* '''variable''': the name of the variable into which to store the unit type information (default "unit_type")

* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable. If mode is set to ''replace'', the variable will not be cleared, and the unit type will overwrite the existing element at the start of the array, leaving any additional elements intact if the original array contained more elements. If mode is set to ''append'', the variable will not be cleared, and the unit type will be added to the array after the existing elements.

==== [store_unit_type_ids] ====

* '''variable''': the name of the variable into which to store a comma-separated list of all unit type IDs including all from all loaded addons

==== [store_villages] ====

Stores a series of locations of villages that pass certain criteria into an array. Each member of the result array will have members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.

Note: This differs from using [store_locations] only in that the hexes considered for match are restricted to those with villages (those whose terrain type has its 'gives_income' flag set to true), in the same way that use of either the 'owner_side' key or the '[filter_owner]' will. In fact, if either of these are present, [store_villages] and [store_locations] will behave identically.

* '''variable''': the name of the variable (array) into which to store the locations (default: "location")
* '''[[StandardLocationFilter]]''' tags and keys as arguments

==== [store_items] ====

Stores current items in the scenario into an array. Each entry has at least members x and y and can have all of the other keys listed in the documentation of [[InterfaceActionsWML#.5Bitem.5D|[item]]] (depending on what was set during creating the item).

*'''variable''': name of the wml variable array to use (default "items")
*'''[[StandardLocationFilter]]''' keys as arguments: only items on locations matching this [[StandardLocationFilter]] will be stored

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

Gets the relative direction from one hex to another. This is an interface to the function wesnoth uses to decide how a unit will face while it is moving / attacking / defending.

* '''[source]''' x and y must describe a map location
* '''[destination]''' similar
* '''variable''' name of the variable to store string result in (one of 'n', 'nw', 'ne', 's', 'sw', 'se')
* '''mode''' optional. 0 is the default setting corresponding to default wesnoth implementation used in animations. 1 is an alternate "radially symmetric" mode. The default mode breaks ties in the direction of south, since this makes more units face the player directly on screen. The radially symmetric mode breaks ties in the direction of counter-clockwise, and might be more appropriate in some cases.

==== [find_path] ====

A WML interface to the pathfinder. Calculates the path between a unit and a location and returns the result in a WML variable, that contains also an array for every step of the path.

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]], only the first matching nearest hex will be used
*'''variable''': the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
*'''allow_multiple_turns''': default no, if yes also moves that require more than one turn will be calculated.
*'''check_visibility''': default no, if yes the path will not be computed if some hexes are not visible due to shroud.
*'''check_teleport''': default yes; if no, teleport won't be taken in account while computing path.
*'''check_zoc''': default yes; if no, unit ZOCs won't be considered while calculating the path.
This is the structure of the variable returned by [find_path]:
[path]
hexes = the total length of the path
if the path is calculated to an impassable hex, or the move requires multiple turns
and allow_multiple_turns is no, its value will be 0.
from_x, from_y = location of the unit
to_x, to_y = destination
movement_cost = total movement cost required by unit to reach that hex
required_turns = total turns required by unit to reach that hex
[step]
x, y = location of the step
terrain = terrain of the step
movement_cost = movement cost required by unit to reach that hex
required_turns = turns required by unit to reach that hex
[/step]
[/path]

==== [unit_worth] ====
Takes only an inline [[StandardUnitFilter]] (only the first matching unit will be used for calculation) and outputs the following variables:
*''cost'', the current unit cost;
*''next_cost'', the cost of the most expensive advancement;
*''health'', the health of the unit in percentage;
*''experience'', current experience in percentage;
*''unit_worth'', how much the unit is worth.

Mainly used for internal AI checks, but one could in theory just do anything with it.

[event]
name=moveto
[unit_worth]
x,y=$x1,$y1
[/unit_worth]
[message]
id=$unit.id
message=_"I cost $cost gold, with $health|% of my hitpoints and $experience|% on the way to cost $next_cost|.
I am estimated to be worth $unit_worth"
[/message]
[clear_variable]
name=cost,next_cost,health,experience,unit_worth
[/clear_variable]
[/event]

=== [clear_variable] ===

This will delete the given variable. This tag can delete a scalar or an entire array; it can also delete one container at an array index. The macro [http://www.wesnoth.org/macro-reference.xhtml#CLEAR_VARIABLE CLEAR_VARIABLE] is a shortcut for this tag.

This action is good to use to clean up the set of variables; for example, a well-behaved scenario will delete any variables that should not be kept for the next scenario before the end of the scenario. One can also clear tags and variables of stored units; for example, one can remove [trait]s and [object]s.

* '''name''': the name of the variable to clear. This can also be a comma-separated list of multiple variable names.
** If a name ends with an array index, then it deletes that one container, and shifts the indexes of all subsequent containers. For example, <code>{CLEAR_VARIABLE my_awesome_array[2]}</code> deletes <code>my_awesome_array[2]</code>, but then moves <code>my_awesome_array[3]</code> to <code>my_awesome_array[2]</code>, moves <code>my_awesome_array[4]</code> to <code>my_awesome_array[3]</code>, and so on until the end of the array.
** Note that <code>{CLEAR_VARIABLE my_awesome_array}</code> deletes the entire array, but <code>{CLEAR_VARIABLE my_awesome_array[0]}</code> deletes only the first container.

=== [sync_variable] ===

{{DevFeature1.13|0}}

Sets one or multiple variables to the same value as on all clients and also on replays, it uses the value from the currently active side.
* '''name''' the name of the variable to synchonize this can be a comma seperated list.

== Other Internal Actions ==

Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.

=== [fire_event] ===

Trigger a WML event (used often for [[EventWML#Custom_events|custom events]])

* '''name''': the name of event to trigger
** ''(Optional)'' {{DevFeature1.13|6}}

* '''id''': ''(Optional)'' the id of a single event to trigger {{DevFeature1.13|6}}

* '''[primary_unit]''': ''(Optional)'' Primary unit for the event. Will never match on a recall list unit. The first unit matching the filter will be chosen.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.

* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.

=== [remove_event] ===
{{DevFeature1.13|0}}

Removes the event with the specified id. Equivalent to [event] id=foo remove=yes. See [[EventWML#remove|EventWML]].

* '''id''': the id of the event to remove. May be a comma separated list.

=== [insert_tag] ===

Inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form. ([[#.5Binsert_tag.5D_Example|See Example]]).

Tag insertion is a special case in that it can be used in places where other ActionWML cannot be used. The basic rule is that anywhere that $variable syntax works, tag insertion will also work. In practice this means pretty much everywhere except directly within top-level scenario tags.

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': Name of the container variable which will have its value inserted into the tag.

=== [role] ===

Tries to find a unit to assign a role to. This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.

* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.

* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

* '''search_recall_list''': {{DevFeature1.13|5}} whether to consider units on the recall list when assigning the role. Can be either yes or no, defaults to yes. {{DevFeature1.13|6}} If set to 'only', then units on the map are not considered when assigning the role - only units on the recall list can receive it.

* '''[else]''' {{DevFeature1.13|5}} ActionWML to execute if the game is unable to find a unit to assign the role to. For example, this could be used to create a new unit satisfying the role.

* '''[auto_recall]''' {{DevFeature1.13|6}} If present, and the role is assigned to a unit on the recall list, then that unit is recalled. Supports all unique keys of [[DirectActionsWML#.5Brecall.5D|[recall]]], but no [[StandardUnitFilter]].

* [[StandardUnitFilter]], do not use a [filter] sub-tag. SUF's role= and type= keys are not used: if you want to use them, use a nested SUF wrapped inside a [and] tag.

=== [random_placement] ===
{{DevFeature1.13|2}}

Selects randomly a given number of locations from a given set of locations and exectutes the given code for each of those locations.

* '''[filter_location]''': a [[StandardLocationFilter]].
* '''[command]''': contains ActionWml that is executed for each of the locations.
* '''num_items''': the number of locations that should be selected, this can be a (lua) expression to calculate the number of locations based on the number of locations that match the filter, for example (size * 0.5) will execute the command for exactly half of the locations (rounded down)
* '''variable''': The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x and y.
* '''min_distance''': The minimum distance of 2 chosen locations, a value less than 0 means that the same locations can be chosen more than one time.
* '''allow_less''': If yes, the tag will not show an error in case there were less than num_items locations available.

=== Flow control actions ===

{{DevFeature1.13|2}}

There are three actions that alter the flow of execution. They are '''[break]''', '''[continue]''', and '''[return]'''. All of them take no arguments.

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. This completely exits the current event, including any nested events, such that the [message] will not be displayed in the below example. No further WML actions are executed in this context. Any separate, subsequent events will be run as usual.
<syntaxhighlight lang=wml>
[event]
name=moveto
[fire_event]
name=return_please
[/fire_event]
[message]
message="Made it back"
[/message]
[/event]
[event]
name=return_please
[return][/return]
[/event]
</syntaxhighlight>

=== [unsynced] ===

{{DevFeature1.13|?}}

Runs the contained actionwml in a unsynced context, that means actions performed inside [unsynced] are not synced over the network. for example
<syntaxhighlight lang=wml>
[event]
name=moveto
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will print the same message to all clients, but also disallow undoing (regardless of [allow_undo]) for that moveto becasue it requests a synced random seed form the server. However this code
<syntaxhighlight lang=wml>
[event]
name=moveto
[unsynced]
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[unsynced]
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will not prevent undoing, but might print a different message for each client in a multiplayer game (or during a sp replay), so `[unsynced]` should not be used for actions that actually change the gamestate otherwise you'll get OOS

== Examples ==

=== Using [set_variables] to Create Arrays of WML ===

<syntaxhighlight lang=wml>
[set_variables]
name=arr
mode=replace
[value]
foo=bar
[/value]
[value]
foo=more
[/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}
</syntaxhighlight>

This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.

=== [insert_tag] Example ===

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== See Also ==
* [[VariablesWML]]
* [[ActionWML]]
** [[ConditionalWML]]
** [[DirectActionsWML]]
** [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

LuaWML/Sides

2018-06-23T19:15:13Z

EliDupree:

This page describes the [[LuaWML]] functions and helpers for handling sides and villages.

==== wesnoth.sides ====

This is not a function but a table indexed by side numbers. Its elements are proxy tables with these fields:
* '''side''': the side number
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
* '''total_income''': integer (read only)
* '''objectives''', '''user_team_name''': translatable strings (read/write)
* '''objectives_changed''': boolean (read/write)
* '''team_name''': string (read/write)
* '''is_local''' {{DevFeature1.13|8}}: boolean (read). Whether the side is local. Careless use will cause OOS errors.
* '''controller''': string (read/write):
:''note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you'll have OOS errors.''

: The only possible values are 'human', 'ai' or 'null'.

{{DevFeature1.13|8}} Remote and local are no longer differentiated by this field. For example, remote humans will be shown as "human". Use 'is_local' field if you need to differentiate.
* '''fog''': boolean (read {{DevFeature1.13|7}}/write)
* '''shroud''': boolean (read {{DevFeature1.13|7}}/write)
* '''hidden''': boolean (read/write)
* '''name''': string (read)
* '''faction''': {{DevFeature1.13|5}} id of the selected faction, string (multiplayer-only, read)
* '''faction_name''': {{DevFeature1.13|5}} name of the selected faction, string (multiplayer-only, read)
* '''color''': string (read/write)
* '''recruit''': table of strings (read/write)
* '''scroll_to_leader''': boolean (read/write)
* '''village_support''': string (read/write)
* '''flag''': string (read {{DevFeature1.13|7}}/write) As of 1.14.0 this is not writable.
* '''flag_icon''': string (read {{DevFeature1.13|7}}/write)
* '''defeat_condition''': string (read/write) See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''lost''': bool (read/write) If lost=true this side will be removed from the persitent list at the end of the scenario. This key can also be used to stop the engine from removing a side by setting it to false. Writing this key only works in a victory/defeat event.
* '''persistent''' {{DevFeature1.13|5}}: boolean (read/write)
* '''suppress_end_turn_confirmation''' {{DevFeature1.13|7}}: boolean (read/write)
* '''share_vision''' {{DevFeature1.13|7}}: string (read/write)
* '''share_maps''' {{DevFeature1.13|7}}: boolean (read)
* '''share_view''' {{DevFeature1.13|7}}: boolean (read)
* '''num_units''' {{DevFeature1.13|7}}: integer (read)
* '''num_villages''' {{DevFeature1.13|7}}: integer (read)
* '''total_upkeep''' {{DevFeature1.13|7}}: integer (read)
* '''expenses''' {{DevFeature1.13|7}}: integer (read)
* '''net_income''' {{DevFeature1.13|7}}: integer (read)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"side"'''.

local side = wesnoth.sides[1]
side.gold = side.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

==== wesnoth.get_sides ====

* '''wesnoth.get_sides(''filter'')'''

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]]. The output is the same format as the wesnoth.sides table, above.
--set gold to 0 for all sides with a leader
local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })
for i,v in ipairs(sides) do
v.gold = 0
end

==== wesnoth.get_village_owner ====

* '''wesnoth.get_village_owner(''x'', ''y'')'''

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

==== wesnoth.set_village_owner ====

* '''wesnoth.set_village_owner(''x'', ''y'', ''side'', [''fire_events''])'''

Gives ownership of the village at the given location to the given side (or remove ownership if none). Ownership is also removed if nil or 0 is passed for the third parameter, but no capture events are fired in this case.
An optional 4th parameter (boolean true|false, default: false) can be passed determining whether to fire any capture events.

wesnoth.set_village_owner(12, 15, 1)

==== wesnoth.is_enemy ====

* '''wesnoth.is_enemy(''side1'', ''side2'')'''

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

==== wesnoth.match_side ====

* '''wesnoth.match_side(''side'', ''filter'')'''

Matches a side against a given [[StandardSideFilter]].

wesnoth.message(tostring(wesnoth.match_side(1, {{"has_unit", { type = "Troll" }}})))

==== wesnoth.get_starting_location ====

* '''wesnoth.get_starting_location(''side'')'''

Returns the starting location of the given side.

local loc = wesnoth.get_starting_location(1)
wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))

==== wesnoth.get_side_variable ====

* '''wesnoth.get_side_variable(''side'', ''name'')'''

Returns a variable stored in the side

local loc = wesnoth.get_side_variable(1, "a.c[7].d")

==== wesnoth.set_side_variable ====

* '''wesnoth.set_side_variable(''side'', ''name'', ''content'')'''

Sets a variable stored in the side

local loc = wesnoth.set_side_variable(1, "a.c[7].d", 5)

==== wesnoth.set_side_id ====

{{DevFeature1.13|7}}

* '''wesnoth.set_side_id(''side'', ''flag'', ''color'')'''

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes.

==== wesnoth.place_shroud ====

{{DevFeature1.13|7}}

* '''wesnoth.place_shroud(''side'', ''shroud'')'''

Shrouds the specified hexes. You can pass a shroud_data string (which will be merged with existing shroud), a list of specific locations (where each location is a two-element list of x and y coordinates), or the special string "all" to shroud all hexes.

==== wesnoth.remove_shroud ====

{{DevFeature1.13|7}}

* '''wesnoth.remove_shroud(''side'', ''shroud'')'''

Unshrouds the specified hexes. Hexes are specified as with place_shroud, except that a shroud_data string will not work.

==== wesnoth.is_fogged ====

{{DevFeature1.13|7}}

* '''wesnoth.is_fogged(''side'', ''location'')'''

Tests if the given location is under fog from the point of view of the given side.

==== wesnoth.is_shrouded ====

{{DevFeature1.13|7}}

* '''wesnoth.is_shrouded(''side'', ''location'')'''

Tests if the given location is under shroud from the point of view of the given side.

==== wesnoth.switch_ai ====

{{DevFeature1.13|7}}

* '''wesnoth.switch_ai(''side'', ''file'')'''

Replaces a side's AI with the configuration from a specified file.

==== wesnoth.append_ai ====

{{DevFeature1.13|7}}

* '''wesnoth.append_ai(''side'', ''params'')'''

Appends AI parameters (aspects, stages, goals) to the side's AI. The syntax for the parameters to be appended is the same as that supported by [modify_side].

==== wesnoth.add_ai_component ====

{{DevFeature1.13|7}}

* '''wesnoth.add_ai_component(''side'', ''path'', ''component'')'''

Adds a component to the side's AI. The path syntax is the same as that used by [modify_ai]. The component is the content of the component - it should not contain eg a toplevel [facet] tag.

==== wesnoth.change_ai_component ====

{{DevFeature1.13|7}}

* '''wesnoth.change_ai_component(''side'', ''path'', ''component'')'''

Like add_ai_component, but replaces an existing component instead of adding a new one.

==== wesnoth.delete_ai_component ====

{{DevFeature1.13|7}}

* '''wesnoth.delete_ai_component(''side'', ''path'')'''

Like add_ai_component, but removes a component instead of adding one.

==== helper.all_teams ====

* '''helper.all_teams()'''

Returns an iterator over sides that can be used in a for-in loop.

Note that the method name "teams" is a historical mistake, currently left out for backwards compatibility. It has no relation to [team] tag.

for side in helper.all_teams() do side.gold = 200 end

[[Category: Lua Reference]]

LuaWML/Sides

2018-06-19T02:40:59Z

EliDupree:

This page describes the [[LuaWML]] functions and helpers for handling sides and villages.

==== wesnoth.sides ====

This is not a function but a table indexed by side numbers. Its elements are proxy tables with these fields:
* '''side''': the side number
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
* '''total_income''': integer (read only)
* '''objectives''', '''user_team_name''': translatable strings (read/write)
* '''objectives_changed''': boolean (read/write)
* '''team_name''': string (read/write)
* '''is_local''' {{DevFeature1.13|8}}: boolean (read). Whether the side is local. Careless use will cause OOS errors.
* '''controller''': string (read/write) :
:''note: As of 1.14.1, the following note is incorrect, but I don't know exactly what the truth is, so I'm leaving it here until somebody who knows the truth edits it. In particular, I observed a networked multiplayer game where both clients displayed both sides' controllers as "human". The behavior may be consistent with the behavior described in [[SideWML]]. - EliDupree''

:''note: In networked multiplayer, the controller attribute is ambiguous (won't be the same on all clients). Be very careful or you'll have OOS errors.''
: The controller attribute has 6 possible values: human, network, ai, network_ai, null, idle. (Or less, see below.)

: A local human should always be "human", a local ai should always be "ai", a remote human should always be "network". and a remote ai should always be "network_ai". An empty side should be null on all clients.

: An idle side should appear similarly as a "human" side for all sides that don't own the idle side, i.e. as "network".

: These values may be checked using lua, or the :controller command in game.

: This value can only be set to 'human', 'ai' or 'null'.

{{DevFeature1.13|8}} Remote and local are no longer differentiated by this field. For example, remote humans will be shown as "human". Use 'is_local' field if you need to differentiate.
* '''fog''': boolean (read {{DevFeature1.13|7}}/write)
* '''shroud''': boolean (read {{DevFeature1.13|7}}/write)
* '''hidden''': boolean (read/write)
* '''name''': string (read)
* '''faction''': {{DevFeature1.13|5}} id of the selected faction, string (multiplayer-only, read)
* '''faction_name''': {{DevFeature1.13|5}} name of the selected faction, string (multiplayer-only, read)
* '''color''': string (read/write)
* '''recruit''': table of strings (read/write)
* '''scroll_to_leader''': boolean (read/write)
* '''village_support''': string (read/write)
* '''flag''': string (read {{DevFeature1.13|7}}/write) As of 1.14.0 this is not writable.
* '''flag_icon''': string (read {{DevFeature1.13|7}}/write)
* '''defeat_condition''': string (read/write) See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''lost''': bool (read/write) If lost=true this side will be removed from the persitent list at the end of the scenario. This key can also be used to stop the engine from removing a side by setting it to false. Writing this key only works in a victory/defeat event.
* '''persistent''' {{DevFeature1.13|5}}: boolean (read/write)
* '''suppress_end_turn_confirmation''' {{DevFeature1.13|7}}: boolean (read/write)
* '''share_vision''' {{DevFeature1.13|7}}: string (read/write)
* '''share_maps''' {{DevFeature1.13|7}}: boolean (read)
* '''share_view''' {{DevFeature1.13|7}}: boolean (read)
* '''num_units''' {{DevFeature1.13|7}}: integer (read)
* '''num_villages''' {{DevFeature1.13|7}}: integer (read)
* '''total_upkeep''' {{DevFeature1.13|7}}: integer (read)
* '''expenses''' {{DevFeature1.13|7}}: integer (read)
* '''net_income''' {{DevFeature1.13|7}}: integer (read)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"side"'''.

local side = wesnoth.sides[1]
side.gold = side.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

==== wesnoth.get_sides ====

* '''wesnoth.get_sides(''filter'')'''

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]]. The output is the same format as the wesnoth.sides table, above.
--set gold to 0 for all sides with a leader
local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })
for i,v in ipairs(sides) do
v.gold = 0
end

==== wesnoth.get_village_owner ====

* '''wesnoth.get_village_owner(''x'', ''y'')'''

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

==== wesnoth.set_village_owner ====

* '''wesnoth.set_village_owner(''x'', ''y'', ''side'', [''fire_events''])'''

Gives ownership of the village at the given location to the given side (or remove ownership if none). Ownership is also removed if nil or 0 is passed for the third parameter, but no capture events are fired in this case.
An optional 4th parameter (boolean true|false, default: false) can be passed determining whether to fire any capture events.

wesnoth.set_village_owner(12, 15, 1)

==== wesnoth.is_enemy ====

* '''wesnoth.is_enemy(''side1'', ''side2'')'''

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

==== wesnoth.match_side ====

* '''wesnoth.match_side(''side'', ''filter'')'''

Matches a side against a given [[StandardSideFilter]].

wesnoth.message(tostring(wesnoth.match_side(1, {{"has_unit", { type = "Troll" }}})))

==== wesnoth.get_starting_location ====

* '''wesnoth.get_starting_location(''side'')'''

Returns the starting location of the given side.

local loc = wesnoth.get_starting_location(1)
wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))

==== wesnoth.get_side_variable ====

* '''wesnoth.get_side_variable(''side'', ''name'')'''

Returns a variable stored in the side

local loc = wesnoth.get_side_variable(1, "a.c[7].d")

==== wesnoth.set_side_variable ====

* '''wesnoth.set_side_variable(''side'', ''name'', ''content'')'''

Sets a variable stored in the side

local loc = wesnoth.set_side_variable(1, "a.c[7].d", 5)

==== wesnoth.set_side_id ====

{{DevFeature1.13|7}}

* '''wesnoth.set_side_id(''side'', ''flag'', ''color'')'''

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes.

==== wesnoth.place_shroud ====

{{DevFeature1.13|7}}

* '''wesnoth.place_shroud(''side'', ''shroud'')'''

Shrouds the specified hexes. You can pass a shroud_data string (which will be merged with existing shroud), a list of specific locations (where each location is a two-element list of x and y coordinates), or the special string "all" to shroud all hexes.

==== wesnoth.remove_shroud ====

{{DevFeature1.13|7}}

* '''wesnoth.remove_shroud(''side'', ''shroud'')'''

Unshrouds the specified hexes. Hexes are specified as with place_shroud, except that a shroud_data string will not work.

==== wesnoth.is_fogged ====

{{DevFeature1.13|7}}

* '''wesnoth.is_fogged(''side'', ''location'')'''

Tests if the given location is under fog from the point of view of the given side.

==== wesnoth.is_shrouded ====

{{DevFeature1.13|7}}

* '''wesnoth.is_shrouded(''side'', ''location'')'''

Tests if the given location is under shroud from the point of view of the given side.

==== wesnoth.switch_ai ====

{{DevFeature1.13|7}}

* '''wesnoth.switch_ai(''side'', ''file'')'''

Replaces a side's AI with the configuration from a specified file.

==== wesnoth.append_ai ====

{{DevFeature1.13|7}}

* '''wesnoth.append_ai(''side'', ''params'')'''

Appends AI parameters (aspects, stages, goals) to the side's AI. The syntax for the parameters to be appended is the same as that supported by [modify_side].

==== wesnoth.add_ai_component ====

{{DevFeature1.13|7}}

* '''wesnoth.add_ai_component(''side'', ''path'', ''component'')'''

Adds a component to the side's AI. The path syntax is the same as that used by [modify_ai]. The component is the content of the component - it should not contain eg a toplevel [facet] tag.

==== wesnoth.change_ai_component ====

{{DevFeature1.13|7}}

* '''wesnoth.change_ai_component(''side'', ''path'', ''component'')'''

Like add_ai_component, but replaces an existing component instead of adding a new one.

==== wesnoth.delete_ai_component ====

{{DevFeature1.13|7}}

* '''wesnoth.delete_ai_component(''side'', ''path'')'''

Like add_ai_component, but removes a component instead of adding one.

==== helper.all_teams ====

* '''helper.all_teams()'''

Returns an iterator over sides that can be used in a for-in loop.

Note that the method name "teams" is a historical mistake, currently left out for backwards compatibility. It has no relation to [team] tag.

for side in helper.all_teams() do side.gold = 200 end

[[Category: Lua Reference]]

LuaWML/Display

2018-05-17T01:46:27Z

EliDupree: /* wesnoth.select_unit */

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

* '''wesnoth.message([''speaker'',] ''message'')'''

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

* '''wesnoth.clear_messages()'''

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

* '''wesnoth.textdomain(''domain'')'''

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

* '''wesnoth.delay(''milliseconds'')'''

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

* '''wesnoth.float_label(''x'', ''y'', ''text'')'''

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "Ouch")

==== wesnoth.get_viewing_side ====

* '''wesnoth.get_viewing_side()'''

returns two values 1) the number of the side of the current viewpoint, 2) a boolean specifying whether it has full vision (can only only true happen in replays or for observers)

==== wesnoth.select_unit ====

* '''wesnoth.select_hex(''x'', ''y'', [''show_movement'', [''fire_events'']])'''
* {{DevFeature1.13|5}} '''wesnoth.select_unit(''unit'', [''show_movement'', [''fire_events'']])'''
* {{DevFeature1.13|5}} '''''unit'':select([''show_movement'', [''fire_events'']])'''

Selects the given unit in the game map as if the player had clicked on it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false). Note: currently (1.14.1), this argument has no effect (events are never fired).

wesnoth.select_unit(14,6, true, true)

The '''wesnoth.select_hex''' form is deprecated. If there is a unit on the location, it does the same thing as '''wesnoth.select_unit''', but if ''show_movement'' is true it also calls '''wesnoth.highlight_hex''' for the location. If there is no unit on the location, '''wesnoth.select_hex''' does not do anything useful.

==== wesnoth.highlight_hex ====

* '''wesnoth.highlight_hex(''x'', ''y'')'''

Draws an outline around the specified hex.

==== wesnoth.deselect_hex ====

* '''wesnoth.deselect_hex()'''

{{DevFeature1.13|2}}

Reverses any select_hex call, leaving all locations unhighlighted. Takes no arguments.

==== wesnoth.scroll_to_tile ====

* '''wesnoth.scroll_to_tile(''x'', ''y'', [''only_if_visible'', [''instant'']])'''
* {{DevFeature1.13|7}} '''wesnoth.scroll_to_tile(''x'', ''y'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])'''

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.lock_view ====

* '''wesnoth.lock_view(''lock'')'''

Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_tile still can; 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.

wesnoth.lock_view(true)
wesnoth.scroll_to_tile(12, 14, false, true)

==== wesnoth.view_locked ====

* '''wesnoth.view_locked()'''

Returns a boolean indicating whether gamemap view scrolling is currently locked.

==== wesnoth.play_sound ====

* '''wesnoth.play_sound(''sound'', [''repeat_count''])'''

Plays the given sound file once, optionally repeating it one or more more times if an integer value is provided as a second argument (note that the sound is ''repeated'' the number of times specified in the second argument, i.e. a second argument of 4 will cause the sound to be played once and then repeated four more times for a total of 5 plays. See the example below).

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

* '''wesnoth.set_music(''music_entry'')'''

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

{{DevFeature1.13|8}} This function is now deprecated. Use the '''wesnoth.music_list''' table instead

==== wesnoth.music_list ====

{{DevFeature1.13|8}}

This is a table giving access to the current music playlist. It can be accessed as a normal array, including the Lua length operator. If you assign a music config to an entry, the track is replaced. It is not a normal array however and cannot be manipulated with the table library.

In addition, it has the following named fields:

* '''wesnoth.music_list.current''' (read-write): The currently-playing track. This may sometimes be a track that's not on the playlist - "play once" tracks are not placed on the playlist.
* '''wesnoth.music_list.current.__cfg''' (read-only): Returns a copy of the current track information.
* '''wesnoth.music_list.previous''' (read-write): The track played before the current one. This may sometimes be a track that's not on the playlist - "play once" tracks are not placed on the playlist.
* '''wesnoth.music_list.previous.__cfg''' (read-only): Returns a copy of the previous track information. NOTE: Wesnoth's playlist implementation effectively "plays" every song as it's added to the playlist, so when replacing one playlist with another, this will return information on the second-to-last track added to the new playlist, not the track you actually heard playing from the playlist that was replaced.
* '''wesnoth.music_list.current_i''' (read-write): The index of the currently-playing track on the playlist, or nil if the currently-playing track is not on the playlist.
* '''wesnoth.music_list.volume''' (read-write): The current music volume, as a percentage of the user's preferred volume set in preferences.
* '''wesnoth.music_list.all''' (read-only): Returns a copy of the music list as an array of WML tables.

It also contains some functions:

* '''wesnoth.music_list.add(''track_name'', [''immediate'',] [''ms_before'', [''ms_after'']])''': Appends a track to the playlist. If true is passed, also start playing the new track.
* '''wesnoth.music_list.remove(''n1'', ...)''': Removes one or more tracks by their index. You can pass as many indices as you wish. If one of the removed tracks is currently playing, it continues to play.
* '''wesnoth.music_list.clear()''': Clears the playlist. The currently-playing track continues to play.
* '''wesnoth.music_list.next()''': Stop playing the current track and move on to the next one. This honours the shuffle settings.
* '''wesnoth.music_list.play(''track_name'')''': Start playing a track without appending it to the playlist.

Each track contains the following fields:

* '''shuffle''' (read-write)
* '''once''' (read-write): generally only true for '''wesnoth.music_list.current'''
* '''ms_before''' (read-write)
* '''ms_after''' (read-write)
* '''immediate''' (read-only)
* '''name''' (read-only): the unresolved track filename
* '''title''' (read-only): a user-friendly track title

==== wesnoth.sound_volume ====

{{DevFeature1.13|8}}

* '''wesnoth.sound_volume(''new_volume'')'''

Sets the current sound volume, as a percentage of the user's preferred volume set in preferences.
Returns the previous sound volume in the same format.

==== wesnoth.show_menu ====

* '''wesnoth.show_menu(''items'' [, ''initial''] [, ''markup''])'''

Shows a popup menu onscreen at the current mouse location. This could be used for example to produce a sort of submenu in a <tt>[set_menu_item]</tt>. The items are specified as a Lua array of tables, each of which supports the following keys:

* ''icon'': An icon to display in the leftmost column of the menu.
* ''image'': An image to display in the main column of the menu. If this is present, ''label'' is ignored.
* ''label'': A label to display in the main column of the menu.
* ''second_label'': A secondary label to display in the right column of the menu.
* ''tooltip'': Text to display when mousing over this option.

The ''initial'' argument must be a valid index into the ''items'' array, or 0 to indicate that no element is initially selected (which is the default but typically not what you want).

The ''markup'' argument specifies whether Pango markup will be parsed in the menuitems. It defaults to false.

The ''initial'' and ''markup'' arguments can be passed in either order; the game will understand which is meant based on the type of the argument.

==== wesnoth.show_message_box ====

* '''wesnoth.show_message_box(''title'', ''message'' [, ''button''] [, ''markup''])'''
* '''wesnoth.confirm([''title'',] ''message'')'''
* '''wesnoth.alert([''title''], ''message'')'''

Shows a standard message box onscreen (similar to the quit confirmation message, for example). The button can be any arbitrary potentially-translatable string (in which case, there will be one button with that label), or it can be one of the following special values:

* ''ok'' or nil: A single OK button; this is the default
* ''cancel'': A single Cancel button
* ''close'': A single Close button
* ''ok_cancel'': Two buttons labelled OK and Cancel
* ''yes_no'': Two buttons labelled Yes and No
* an empty string: No buttons; the dialog automatically closes after a few seconds

The alert and confirm functions are simpler wrappers for this function, using a single OK button and a pair of Yes/No buttons, respectively. Both confirm and show_message_box return false if No or Cancel was clicked, and true otherwise.

==== wesnoth.show_message_dialog ====

* '''wesnoth.show_message_dialog(''attributes'', [''options'', [''text_input_attributes'']])'''

{{DevFeature1.13|2}}

Shows a message dialog, of the type used by the [message] ActionWML tag. Unlike the [message] tag, this is unsynced; if you need it synced, you must do it yourself. The first argument is a table describing the dialog with the following keys:

* ''title'' - The title to show on the message. For example, the speaker's name.
* ''message'' - The message content.
* ''portrait'' - An image to show along with the message. By default, no image is shown.
* ''left_side'' - The default is true; set to false to show the image on the right.
* ''mirror'' - If true, the image will be flipped horizontally.

The second argument is a list of options as a Lua array. Each option is either a (possibly-translatable) string or a config with [[DescriptionWML#WML_Format|DescriptionWML]] keys. The array itself can also have an optional '''default''' key which if present should be the index of the initially selected option (useful if you don't need full DescriptionWML but want to set a default). If present it overrides any defaults set in individual options.

The third argument is a table describing the text input field with the following keys:

* ''label'' - A label to show to the left of the text field.
* ''text'' - Initial contents of the text field.
* ''max_length'' - Maximum input length in characters (defaults to 256).

You need at least one key for the text input to be shown. Both the second arguments are option, but if you want text input with no options, you must pass nil for the second parameter.

This function returns two values. The first is the numeric result of the dialog. If there are no options and no text input, this is -2 if the user closed by pressing Escape, otherwise it's -1. If there are options, this is the index of the option chosen (starting from 1). If there is text input but no options, the first return value is 0. If there was text input, the second value contains the text entered.

Example:

wesnoth.show_message_dialog({
title = "Make your choice:",
message = "Select an option and enter some text.",
portrait = "wesnoth-icon.png",
}, {
"The first choice is always the best!",
"Pick me! Second choices are better!",
"You know you want the third option!",
}, {
label = "Text:",
text = "?",
max_length = 16
})

(You don't have to format it like that, of course.)

==== wesnoth.show_popup_dialog ====

* '''wesnoth.show_popup_dialog(''title'', ''message'', [''image''])'''

{{DevFeature1.13|2}}

Shows a simple popup dialog in the centre of the screen. Takes three arguments, which in order are:

# A title string for the dialog
# The message content for the dialog.
# An image to show.

Both the title and the message support Pango markup. The image is optional.

==== wesnoth.show_story ====

* '''wesnoth.show_story(''story_config'', ''default_title'')'''

{{DevFeature1.13|8}}

Shows the storyscreen. The passed config is identical to the contents of [[IntroWML|[story]]]. The second parameter is the default title used if a part does not specify one — unlike intro storyscreens, a Lua-invoked one does not default to the scenario name.

==== wesnoth.show_dialog ====

* '''wesnoth.show_dialog(''wml_dialog_table'', [''pre_show_function'', [''post_show_function'']])'''

Displays a dialog box described by a WML table and returns:
* if the dialog was dismissed by a button click, the integer value associated to the button via the "return_value" keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the resolution section of a GUI window as described in [[GUIToolkitWML#Window_definition|GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

<syntaxhighlight lang=lua>
local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { return_value = -1, T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))
</syntaxhighlight>

==== wesnoth.set_dialog_value ====

* '''wesnoth.set_dialog_value(''value'', ''path, to, widget, id'')'''

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_dialog_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

* '''wesnoth.get_dialog_value(''path, to, widget, id'')'''

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

{{DevFeature1.13|0}}
For treeviews this function returns a table descibing the currently selected node.
If for example in this treeview
+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12
Item 9 is selcted the value will be {2,1,3}

==== wesnoth.set_dialog_active ====

* '''wesnoth.set_dialog_active(''active?'', ''path, to, widget, id'')'''

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

* '''wesnoth.set_dialog_callback(''callback_function'', ''path, to, widget, id'')'''

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_markup ====

* '''wesnoth.set_dialog_markup(''allowed?'', ''path, to, widget, id'')'''

Sets the flag associated to a widget to enable or disable Pango markup. The new flag value is passed as the first argument (boolean), and the widget to modify is obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). Most widgets start with Pango markup disabled unless this function is used to set their flag to true.

wesnoth.set_dialog_markup(true, "notice_label")
wesnoth.set_dialog_value("<big>NOTICE!</big>", "notice_label")

==== wesnoth.set_dialog_focus ====

* '''wesnoth.set_dialog_focus(''focused?'', ''path, to, widget, id'')'''

{{DevFeature1.13|2}}

Switches the keyboard focus to the widget found following the given path (see [[#wesnoth.set_dialog_value]]). This is often useful for dialogs containing a central listbox, so that it can be controlled with the keyboard as soon as it is displayed.

wesnoth.set_dialog_focus("my_listbox")

==== wesnoth.set_dialog_visible ====

* '''wesnoth.set_dialog_visible(''visible?'', ''path, to, widget, id'')'''

{{DevFeature1.13|2}}

Sets a widget's visibility status. The new status is passed as the first argument, and the path to the widget is specified by the remaining arguments (see [[#wesnoth.set_dialog_value]]). The following visibility statuses are recognized:

{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

wesnoth.set_dialog_visible(false, "secret_button")

==== wesnoth.set_dialog_canvas ====

* '''wesnoth.set_dialog_canvas(''index'', ''content'', ''path, to, widget, id'')'''

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

==== wesnoth.add_dialog_tree_node ====

* '''wesnoth.add_dialog_tree_node(''type'', ''index'', ''path, to, widget, id'')'''

{{DevFeature1.13|0}}

Adds a childnode to a treeview widget or a treeview node. The type (id of the node definition) of the node is passed in the first parameter. The second parameter (integer) spcifies where the node should be inserted in the parentnode. The other arguments describe the path of the parent treeview (-node)

==== wesnoth.remove_dialog_item ====

* '''wesnoth.remove_dialog_item(''index'', ''count'', ''path, to, widget, id'')'''

{{DevFeature1.13|1}}

Removes an item from a listbox, a multipage or a treeview. First parameter is the index of the item to delete, second parameter is the number of items to delete and the remaining parameters describe the path to the listbox, the multipage or the parent treview node.

==== wesnoth.is_skipping_messages ====

* '''wesnoth.is_skipping_messages()'''

{{DevFeature1.13|2}}

Returns true if messages are currently being skipped, for example because the player has chosen to skip replay, or has pressed escape to dismiss a message.

==== wesnoth.skip_messages ====

* '''wesnoth.skip_messages([''skip?'')'''

{{DevFeature1.13|2}}

Sets the skip messages flag. By default it sets it to true, but you can also pass false to unset the flag.

==== wesnoth.get_displayed_unit ====

* '''wesnoth.get_displayed_unit()'''

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.log ====

* '''wesnoth.log([''logger''], ''message', ''in_chat'')'''

{{DevFeature1.13|5}} Logs a message to the console. These messages are normally not visible unless Wesnoth is run from the command-line or (in Windows) with the --wconsole switch. The in_chat argument, however, can be set to true to also echo the message to the in-game chat area.

Possible loggers are info, debug, warning, error, and wml. The wml logger is special and is intended for WML errors; it always goes to chat, so the in_chat argument is ignored and can be omitted. The default logger is info.

==== wesnoth.theme_items ====

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

<syntaxhighlight lang=lua>
local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local _ = wesnoth.textdomain "mydomain"
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end
</syntaxhighlight>

The things that would need to be to modified in the above code are:

* the domain of your addon ("mydomain"), assuming that you are using translations. Otherwise just remove the underscore in the tooltip line.
* the name of the status (u.status.entangled). Note that if the attribute happens to be inside [variables], so be it: u.variables.whatever.
* the path to the image ("entangled.png").
* the tooltip of the status ("entangled: This unit ...").

The following is a list of valid entries in wesnoth.theme_items which will have an effect in the game. Unfortunately when this feature was created the full range of capabilities of the feature was never properly documented. The following list is automatically generated. To find out what each entry will do, you will have to make guesses and experiment, or read the source code at src/reports.cpp. If you find out what an entry does, you are more than welcome to edit the wiki and give a proper description to any of these fields.

* '''unit_name'''
* '''selected_unit_name'''
* '''unit_type'''
* '''selected_unit_type'''
* '''unit_race'''
* '''selected_unit_race'''
* '''unit_side'''
* '''selected_unit_side'''
* '''unit_level'''
* '''selected_unit_level'''
* '''unit_amla'''
* '''unit_traits'''
* '''selected_unit_traits'''
* '''unit_status'''
* '''selected_unit_status'''
* '''unit_alignment'''
* '''selected_unit_alignment'''
* '''unit_abilities'''
* '''selected_unit_abilities'''
* '''unit_hp'''
* '''selected_unit_hp'''
* '''unit_xp'''
* '''selected_unit_xp'''
* '''unit_advancement_options'''
* '''selected_unit_advancement_options'''
* '''unit_defense'''
* '''selected_unit_defense'''
* '''unit_vision'''
* '''selected_unit_vision'''
* '''unit_moves'''
* '''selected_unit_moves'''
* '''unit_weapons'''
* '''highlighted_unit_weapons'''
* '''selected_unit_weapons'''
* '''unit_image'''
* '''selected_unit_image'''
* '''selected_unit_profile'''
* '''unit_profile'''
* '''tod_stats'''
* '''time_of_day'''
* '''unit_box'''
* '''turn'''
* '''gold'''
* '''villages'''
* '''num_units'''
* '''upkeep'''
* '''expenses'''
* '''income'''
* '''terrain_info'''
* '''terrain'''
** <nowiki>Text for terrain of the active hex. Same as the one displayed on the UI. It probably returns an empty table when no hex is active. Otherwise, it returns something like {{"element",{text="Grassland (Flat)"}}}.</nowiki>
* '''zoom_level'''
* '''position'''
* '''side_playing'''
* '''observers'''
** <nowiki>When there is no observer, it returns an empty table. When there are observers, it gives
{{"element",
{tooltip="Observers\n<observer1>\n<observer2>\n", image="misc/eye.png"}
}}

</nowiki>
* '''selected_terrain'''
* '''edit_left_button_function'''
* '''report_clock'''
** <nowiki>wesnoth.theme_items.report_clock() gives a table {{"element", text=<time>}}, where <time> is HH:MM of local time. It probably return 12hr or 24hr formats depending on user preference. </nowiki>
* '''report_countdown'''
** <nowiki>wesnoth.theme_items.report_countdown() gives a table {{"element", text=<time>}}, where <time> is MM:SS of time limit for player's turn. If turn limit < 120 or 60, add 
or html tags. </nowiki>

==== helper.get_user_choice ====

* '''helper.get_user_choice(''message_table'', ''options'')'''

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

==== wesnoth.zoom ====

{{DevFeature1.13|8}}

* '''wesnoth.zoom(''factor''[, ''relative''])'''

Changes the zoom level of the map. If relative is false, which is the default, it simply sets the zoom level. If relative is true, it zooms relative to the current zoom level. So, for example, if the zoom level is currently 0.5, then wesnoth.zoom(2) sets it to 2, while wesnoth.zoom(2, true) sets it to 1 (2 * 0.5).

This function also returns the resulting zoom level. Because of this, you can call wesnoth.zoom(1) to simply get the current zoom level.

Note that this function cannot zoom to a level that the user would not be able to reach from the UI. Attempting to do so will simply select the nearest allowed zoom level.

LuaWML/Events

2018-05-17T01:45:47Z

EliDupree: /* wesnoth.game_events */

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

* '''wesnoth.fire(''wml_action_name'', ''wml_action_contents'')'''

Fires a [[ActionWML|WML action]]. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

<syntaxhighlight lang=lua>
wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })
</syntaxhighlight>

==== wesnoth.wml_actions ====

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
</syntaxhighlight>

The new tag can now be used in plain WML code.

<syntaxhighlight lang=wml>
[freeze_unit]
id=Delfador
[/freeze_unit]
</syntaxhighlight>

You can override functions already assigned to the table. This is useful if you need to extend functionality of core tags. For instance, the following script overrides the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.print(cfg)
cfg.size = (cfg.size or 12) + 10
wml_actions.print(cfg)
end
</syntaxhighlight>

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.wml_conditionals ====

{{DevFeature1.13|0}}

This is an associative table like wesnoth.wml_actions. You can use it to define new conditional wml tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when '''wesnoth.eval_conditional''' is run.

Use it like

<syntaxhighlight lang=lua>
function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end
</syntaxhighlight>

If this lua code is executed, it would make the following syntax be valid WML in your add-on:

<syntaxhighlight lang=wml>
[if]
[foo]
bar = $X
[/foo]
[then]
[message]
...
[/message]
[/then]
[/if]
</syntaxhighlight>

You cannot override the meaning of any core conditional tags.

==== wesnoth.game_events ====

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].
* '''on_mouse_action''': function called when the user leftclicks on hex; its arguments are x,y of location selected. {{DevFeature1.13|10}} Might be from earlier 1.13, not tested.

''on_mouse_action'' has several gotchas. Currently (1.14.1), the sequence goes like this:
* The player clicks the mouse (mousedown followed by mouse up in the same hex).
* on_mouse_action triggers, for that hex.
* the click has its normal UI effect (such as selecting or moving a unit), based on the '''current''' position of the mouse.
Thus, if you display any sort of animation during the on_mouse_action function, the player may have ''moved'' the mouse, causing a mouse-click effect to happen in a place they didn't expect, which is also different than the location that was passed to on_mouse_action. In addition, there are the usual gotchas about this function not being synchronized for network games or replays. See also: https://github.com/wesnoth/wesnoth/issues/2325

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

<syntaxhighlight lang=lua>
-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end
</syntaxhighlight>

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
"color_palette", "color_range", "era", "event", "generator", "label",
"lua", "menu_item", "music", "next_item_name", "objectives", "side", "sound_source",
"story", "terrain_graphics", "time", "time_area", "tunnel", "used_item", "variables"

Note: a on_event handler will not prevent undoing of that event, so usually you need to add an event to diallow undo to prevent OOS. You can add an event handler for that event inside a on_event callback. A possible way to define a disallow_undo function is:

<syntaxhighlight lang=lua>
function disallow_undo()
wesnoth.wml_actions.event { name = wesnoth.current.event_context.name }
end
</syntaxhighlight>
Which should then be called from every on_event callback which changes the gamestate.

{{DevFeature1.13|5}}:
The event names passed to ''on_event'' always use underscores instead of spaces

==== wesnoth.persistent_tags ====

{{DevFeature1.13|12}}

This is an associative table defining tags that should be persisted in saved games. Each tag is itself a table containing two functions, read and write. The write function is called in <tt>on_load</tt> and passed a function as a parameter which takes a WML table and adds it the saved game under the specified tag; the read function is called once per matching tag found in the saved game, and is passed a WML table of its contents. Note the asymmetry here: if you're saving an array, the write function is responsible for saving the entire array (and is only called once), while the read function is only responsible for loading one item (and is called several times).

Example:

<syntaxhighlight lang=lua>
local inventory = {}

function wesnoth.persistent_tags.inventory.read(cfg)
inventory[cfg.side] = cfg
end

function wesnoth.persistent_tags.inventory.write(add)
for i = 1, #wesnoth.sides do
add(inventory[i])
end
end
</syntaxhighlight>

Notice that you don't need to create <tt>wesnoth.persistent_tags.inventory</tt> as an empty table first; you can simply define the read and write functions.

==== wesnoth.fire_event ====

* '''wesnoth.fire_event(''event_name'', [''x1'', ''y1'', [''x2'', ''y2'']], [''first_weapon'', [''second_weapon'']])'''

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.fire_event_by_id ====
{{DevFeature1.13|6}}

* '''wesnoth.fire_event_by_id(''event_id'', [''x1'', ''y1'', [''x2'', ''y2'']], [''first_weapon'', [''second_weapon'']])'''

Fires a single WML event with the given id. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of the event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event_by_id("explosion_1", 17, 42, { damage = "fire" })

==== wesnoth.add_event_handler ====

* '''wesnoth.add_event_handler(''cfg'')'''

{{DevFeature1.13|0}}

Registers a new event handler. This takes a WML table containing the same information normally used by the [[EventWML#The_.5Bevent.5D_Tag|[event]]] tag.

==== wesnoth.remove_event_handler ====

* '''wesnoth.remove_event_handler(''id'')'''

{{DevFeature1.13|0}}

Removes an event handler. This requires the event handler to have been assigned an [[EventWML#id|id]] at creation time.

==== wesnoth.eval_conditional ====

* '''wesnoth.eval_conditional(''conditional_tags'')'''

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

<syntaxhighlight lang=lua>
local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}
</syntaxhighlight>

==== wesnoth.tovconfig ====

* '''wesnoth.tovconfig(''config'')'''

Converts a WML table into a proxy object which performs variable substitution on the fly.

<syntaxhighlight lang=lua>
wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time
</syntaxhighlight>

==== helper.set_wml_action_metatable ====

* '''helper.set_wml_action_metatable{}'''

Sets the metatable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

<syntaxhighlight lang=lua>
local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }
</syntaxhighlight>

==== helper.wml_error ====

* '''helper.wml_error(''message'')'''

Interrupts the current execution and displays a chat message that looks like a WML error.

<syntaxhighlight lang=lua>
local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")
</syntaxhighlight>

==== helper.literal ====

* '''helper.literal(''config'')'''

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

<syntaxhighlight lang=lua>
function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end
</syntaxhighlight>

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

* '''helper.parsed(''config'')'''

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

* '''helper.shallow_literal(''config'')'''

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

* '''helper.shallow_parsed(''config'')'''

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

=== on_event.lua ===

{{DevFeature1.13|6}}

* '''on_event(''name'', [ ''priority'',] ''function'')'''

The file ''data/lua/on_event.lua'' provides a simple way to register lua functions as wml event handlers.

<syntaxhighlight lang=lua>
local on_event = wesnoth.require("lua/on_event.lua")
on_event("moveto", function(context)
if context.x1 == 10 and context.y1 == 11 then
wesnoth.message("unit moved to (10,11)")
end
end)

on_event("die", function(context)
if context.x1 == 20 and context.y1 == 21 then
wesnoth.message("unit died at (20,21)")
end
end)
</syntaxhighlight>

The passed function will be called with '''wesnoth.current.event_context''' as paremter. THis isn't as powerful as wml event handlers though: Filters must be implemented with an if in the function body (as shown above with ''context.x1 == 10 and context.x1 == 11''). There is no way to remove those event handlers, in particular they behave like ''first_time_only=no'' events. They are not persisted on save/load so they must be re-defined on each load (e.g. in a preload event).
[[Category: Lua Reference]]

LuaWML/Events

2018-05-15T14:28:27Z

EliDupree: Document some gotchas of on_mouse_action

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

* '''wesnoth.fire(''wml_action_name'', ''wml_action_contents'')'''

Fires a [[ActionWML|WML action]]. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

<syntaxhighlight lang=lua>
wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })
</syntaxhighlight>

==== wesnoth.wml_actions ====

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
</syntaxhighlight>

The new tag can now be used in plain WML code.

<syntaxhighlight lang=wml>
[freeze_unit]
id=Delfador
[/freeze_unit]
</syntaxhighlight>

You can override functions already assigned to the table. This is useful if you need to extend functionality of core tags. For instance, the following script overrides the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.print(cfg)
cfg.size = (cfg.size or 12) + 10
wml_actions.print(cfg)
end
</syntaxhighlight>

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.wml_conditionals ====

{{DevFeature1.13|0}}

This is an associative table like wesnoth.wml_actions. You can use it to define new conditional wml tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when '''wesnoth.eval_conditional''' is run.

Use it like

<syntaxhighlight lang=lua>
function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end
</syntaxhighlight>

If this lua code is executed, it would make the following syntax be valid WML in your add-on:

<syntaxhighlight lang=wml>
[if]
[foo]
bar = $X
[/foo]
[then]
[message]
...
[/message]
[/then]
[/if]
</syntaxhighlight>

You cannot override the meaning of any core conditional tags.

==== wesnoth.game_events ====

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].
* '''on_mouse_action''': function called when the user leftclicks on hex; its arguments are x,y of location selected. {{DevFeature1.13|10}} Might be from earlier 1.13, not tested.

''on_mouse_action'' has several gotchas. Currently (1.4.1), the sequence goes like this:
* The player clicks the mouse (mousedown followed by mouse up in the same hex).
* on_mouse_action triggers, for that hex.
* the click has its normal UI effect (such as selecting or moving a unit), based on the '''current''' position of the mouse.
Thus, if you display any sort of animation during the on_mouse_action function, the player may have ''moved'' the mouse, causing a mouse-click effect to happen in a place they didn't expect, which is also different than the location that was passed to on_mouse_action. In addition, there are the usual gotchas about this function not being synchronized for network games or replays. See also: https://github.com/wesnoth/wesnoth/issues/2325

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

<syntaxhighlight lang=lua>
-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end
</syntaxhighlight>

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
"color_palette", "color_range", "era", "event", "generator", "label",
"lua", "menu_item", "music", "next_item_name", "objectives", "side", "sound_source",
"story", "terrain_graphics", "time", "time_area", "tunnel", "used_item", "variables"

Note: a on_event handler will not prevent undoing of that event, so usually you need to add an event to diallow undo to prevent OOS. You can add an event handler for that event inside a on_event callback. A possible way to define a disallow_undo function is:

<syntaxhighlight lang=lua>
function disallow_undo()
wesnoth.wml_actions.event { name = wesnoth.current.event_context.name }
end
</syntaxhighlight>
Which should then be called from every on_event callback which changes the gamestate.

{{DevFeature1.13|5}}:
The event names passed to ''on_event'' always use underscores instead of spaces

==== wesnoth.persistent_tags ====

{{DevFeature1.13|12}}

This is an associative table defining tags that should be persisted in saved games. Each tag is itself a table containing two functions, read and write. The write function is called in <tt>on_load</tt> and passed a function as a parameter which takes a WML table and adds it the saved game under the specified tag; the read function is called once per matching tag found in the saved game, and is passed a WML table of its contents. Note the asymmetry here: if you're saving an array, the write function is responsible for saving the entire array (and is only called once), while the read function is only responsible for loading one item (and is called several times).

Example:

<syntaxhighlight lang=lua>
local inventory = {}

function wesnoth.persistent_tags.inventory.read(cfg)
inventory[cfg.side] = cfg
end

function wesnoth.persistent_tags.inventory.write(add)
for i = 1, #wesnoth.sides do
add(inventory[i])
end
end
</syntaxhighlight>

Notice that you don't need to create <tt>wesnoth.persistent_tags.inventory</tt> as an empty table first; you can simply define the read and write functions.

==== wesnoth.fire_event ====

* '''wesnoth.fire_event(''event_name'', [''x1'', ''y1'', [''x2'', ''y2'']], [''first_weapon'', [''second_weapon'']])'''

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.fire_event_by_id ====
{{DevFeature1.13|6}}

* '''wesnoth.fire_event_by_id(''event_id'', [''x1'', ''y1'', [''x2'', ''y2'']], [''first_weapon'', [''second_weapon'']])'''

Fires a single WML event with the given id. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of the event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event_by_id("explosion_1", 17, 42, { damage = "fire" })

==== wesnoth.add_event_handler ====

* '''wesnoth.add_event_handler(''cfg'')'''

{{DevFeature1.13|0}}

Registers a new event handler. This takes a WML table containing the same information normally used by the [[EventWML#The_.5Bevent.5D_Tag|[event]]] tag.

==== wesnoth.remove_event_handler ====

* '''wesnoth.remove_event_handler(''id'')'''

{{DevFeature1.13|0}}

Removes an event handler. This requires the event handler to have been assigned an [[EventWML#id|id]] at creation time.

==== wesnoth.eval_conditional ====

* '''wesnoth.eval_conditional(''conditional_tags'')'''

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

<syntaxhighlight lang=lua>
local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}
</syntaxhighlight>

==== wesnoth.tovconfig ====

* '''wesnoth.tovconfig(''config'')'''

Converts a WML table into a proxy object which performs variable substitution on the fly.

<syntaxhighlight lang=lua>
wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time
</syntaxhighlight>

==== helper.set_wml_action_metatable ====

* '''helper.set_wml_action_metatable{}'''

Sets the metatable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

<syntaxhighlight lang=lua>
local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }
</syntaxhighlight>

==== helper.wml_error ====

* '''helper.wml_error(''message'')'''

Interrupts the current execution and displays a chat message that looks like a WML error.

<syntaxhighlight lang=lua>
local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")
</syntaxhighlight>

==== helper.literal ====

* '''helper.literal(''config'')'''

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

<syntaxhighlight lang=lua>
function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end
</syntaxhighlight>

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

* '''helper.parsed(''config'')'''

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

* '''helper.shallow_literal(''config'')'''

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

* '''helper.shallow_parsed(''config'')'''

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

=== on_event.lua ===

{{DevFeature1.13|6}}

* '''on_event(''name'', [ ''priority'',] ''function'')'''

The file ''data/lua/on_event.lua'' provides a simple way to register lua functions as wml event handlers.

<syntaxhighlight lang=lua>
local on_event = wesnoth.require("lua/on_event.lua")
on_event("moveto", function(context)
if context.x1 == 10 and context.y1 == 11 then
wesnoth.message("unit moved to (10,11)")
end
end)

on_event("die", function(context)
if context.x1 == 20 and context.y1 == 21 then
wesnoth.message("unit died at (20,21)")
end
end)
</syntaxhighlight>

The passed function will be called with '''wesnoth.current.event_context''' as paremter. THis isn't as powerful as wml event handlers though: Filters must be implemented with an if in the function body (as shown above with ''context.x1 == 10 and context.x1 == 11''). There is no way to remove those event handlers, in particular they behave like ''first_time_only=no'' events. They are not persisted on save/load so they must be re-defined on each load (e.g. in a preload event).
[[Category: Lua Reference]]

LuaWML/Display

2018-05-15T14:17:00Z

EliDupree: /* wesnoth.select_unit */

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

* '''wesnoth.message([''speaker'',] ''message'')'''

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

* '''wesnoth.clear_messages()'''

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

* '''wesnoth.textdomain(''domain'')'''

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

* '''wesnoth.delay(''milliseconds'')'''

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

* '''wesnoth.float_label(''x'', ''y'', ''text'')'''

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "Ouch")

==== wesnoth.get_viewing_side ====

* '''wesnoth.get_viewing_side()'''

returns two values 1) the number of the side of the current viewpoint, 2) a boolean specifying whether it has full vision (can only only true happen in replays or for observers)

==== wesnoth.select_unit ====

* '''wesnoth.select_hex(''x'', ''y'', [''show_movement'', [''fire_events'']])'''
* {{DevFeature1.13|5}} '''wesnoth.select_unit(''unit'', [''show_movement'', [''fire_events'']])'''
* {{DevFeature1.13|5}} '''''unit'':select([''show_movement'', [''fire_events'']])'''

Selects the given unit in the game map as if the player had clicked on it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false). Note: currently (1.4.1), this argument has no effect (events are never fired).

wesnoth.select_unit(14,6, true, true)

The '''wesnoth.select_hex''' form is deprecated. If there is a unit on the location, it does the same thing as '''wesnoth.select_unit''', but if ''show_movement'' is true it also calls '''wesnoth.highlight_hex''' for the location. If there is no unit on the location, '''wesnoth.select_hex''' does not do anything useful.

==== wesnoth.highlight_hex ====

* '''wesnoth.highlight_hex(''x'', ''y'')'''

Draws an outline around the specified hex.

==== wesnoth.deselect_hex ====

* '''wesnoth.deselect_hex()'''

{{DevFeature1.13|2}}

Reverses any select_hex call, leaving all locations unhighlighted. Takes no arguments.

==== wesnoth.scroll_to_tile ====

* '''wesnoth.scroll_to_tile(''x'', ''y'', [''only_if_visible'', [''instant'']])'''
* {{DevFeature1.13|7}} '''wesnoth.scroll_to_tile(''x'', ''y'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])'''

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.lock_view ====

* '''wesnoth.lock_view(''lock'')'''

Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_tile still can; 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.

wesnoth.lock_view(true)
wesnoth.scroll_to_tile(12, 14, false, true)

==== wesnoth.view_locked ====

* '''wesnoth.view_locked()'''

Returns a boolean indicating whether gamemap view scrolling is currently locked.

==== wesnoth.play_sound ====

* '''wesnoth.play_sound(''sound'', [''repeat_count''])'''

Plays the given sound file once, optionally repeating it one or more more times if an integer value is provided as a second argument (note that the sound is ''repeated'' the number of times specified in the second argument, i.e. a second argument of 4 will cause the sound to be played once and then repeated four more times for a total of 5 plays. See the example below).

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

* '''wesnoth.set_music(''music_entry'')'''

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

{{DevFeature1.13|8}} This function is now deprecated. Use the '''wesnoth.music_list''' table instead

==== wesnoth.music_list ====

{{DevFeature1.13|8}}

This is a table giving access to the current music playlist. It can be accessed as a normal array, including the Lua length operator. If you assign a music config to an entry, the track is replaced. It is not a normal array however and cannot be manipulated with the table library.

In addition, it has the following named fields:

* '''wesnoth.music_list.current''' (read-write): The currently-playing track. This may sometimes be a track that's not on the playlist - "play once" tracks are not placed on the playlist.
* '''wesnoth.music_list.current.__cfg''' (read-only): Returns a copy of the current track information.
* '''wesnoth.music_list.previous''' (read-write): The track played before the current one. This may sometimes be a track that's not on the playlist - "play once" tracks are not placed on the playlist.
* '''wesnoth.music_list.previous.__cfg''' (read-only): Returns a copy of the previous track information. NOTE: Wesnoth's playlist implementation effectively "plays" every song as it's added to the playlist, so when replacing one playlist with another, this will return information on the second-to-last track added to the new playlist, not the track you actually heard playing from the playlist that was replaced.
* '''wesnoth.music_list.current_i''' (read-write): The index of the currently-playing track on the playlist, or nil if the currently-playing track is not on the playlist.
* '''wesnoth.music_list.volume''' (read-write): The current music volume, as a percentage of the user's preferred volume set in preferences.
* '''wesnoth.music_list.all''' (read-only): Returns a copy of the music list as an array of WML tables.

It also contains some functions:

* '''wesnoth.music_list.add(''track_name'', [''immediate'',] [''ms_before'', [''ms_after'']])''': Appends a track to the playlist. If true is passed, also start playing the new track.
* '''wesnoth.music_list.remove(''n1'', ...)''': Removes one or more tracks by their index. You can pass as many indices as you wish. If one of the removed tracks is currently playing, it continues to play.
* '''wesnoth.music_list.clear()''': Clears the playlist. The currently-playing track continues to play.
* '''wesnoth.music_list.next()''': Stop playing the current track and move on to the next one. This honours the shuffle settings.
* '''wesnoth.music_list.play(''track_name'')''': Start playing a track without appending it to the playlist.

Each track contains the following fields:

* '''shuffle''' (read-write)
* '''once''' (read-write): generally only true for '''wesnoth.music_list.current'''
* '''ms_before''' (read-write)
* '''ms_after''' (read-write)
* '''immediate''' (read-only)
* '''name''' (read-only): the unresolved track filename
* '''title''' (read-only): a user-friendly track title

==== wesnoth.sound_volume ====

{{DevFeature1.13|8}}

* '''wesnoth.sound_volume(''new_volume'')'''

Sets the current sound volume, as a percentage of the user's preferred volume set in preferences.
Returns the previous sound volume in the same format.

==== wesnoth.show_menu ====

* '''wesnoth.show_menu(''items'' [, ''initial''] [, ''markup''])'''

Shows a popup menu onscreen at the current mouse location. This could be used for example to produce a sort of submenu in a <tt>[set_menu_item]</tt>. The items are specified as a Lua array of tables, each of which supports the following keys:

* ''icon'': An icon to display in the leftmost column of the menu.
* ''image'': An image to display in the main column of the menu. If this is present, ''label'' is ignored.
* ''label'': A label to display in the main column of the menu.
* ''second_label'': A secondary label to display in the right column of the menu.
* ''tooltip'': Text to display when mousing over this option.

The ''initial'' argument must be a valid index into the ''items'' array, or 0 to indicate that no element is initially selected (which is the default but typically not what you want).

The ''markup'' argument specifies whether Pango markup will be parsed in the menuitems. It defaults to false.

The ''initial'' and ''markup'' arguments can be passed in either order; the game will understand which is meant based on the type of the argument.

==== wesnoth.show_message_box ====

* '''wesnoth.show_message_box(''title'', ''message'' [, ''button''] [, ''markup''])'''
* '''wesnoth.confirm([''title'',] ''message'')'''
* '''wesnoth.alert([''title''], ''message'')'''

Shows a standard message box onscreen (similar to the quit confirmation message, for example). The button can be any arbitrary potentially-translatable string (in which case, there will be one button with that label), or it can be one of the following special values:

* ''ok'' or nil: A single OK button; this is the default
* ''cancel'': A single Cancel button
* ''close'': A single Close button
* ''ok_cancel'': Two buttons labelled OK and Cancel
* ''yes_no'': Two buttons labelled Yes and No
* an empty string: No buttons; the dialog automatically closes after a few seconds

The alert and confirm functions are simpler wrappers for this function, using a single OK button and a pair of Yes/No buttons, respectively. Both confirm and show_message_box return false if No or Cancel was clicked, and true otherwise.

==== wesnoth.show_message_dialog ====

* '''wesnoth.show_message_dialog(''attributes'', [''options'', [''text_input_attributes'']])'''

{{DevFeature1.13|2}}

Shows a message dialog, of the type used by the [message] ActionWML tag. Unlike the [message] tag, this is unsynced; if you need it synced, you must do it yourself. The first argument is a table describing the dialog with the following keys:

* ''title'' - The title to show on the message. For example, the speaker's name.
* ''message'' - The message content.
* ''portrait'' - An image to show along with the message. By default, no image is shown.
* ''left_side'' - The default is true; set to false to show the image on the right.
* ''mirror'' - If true, the image will be flipped horizontally.

The second argument is a list of options as a Lua array. Each option is either a (possibly-translatable) string or a config with [[DescriptionWML#WML_Format|DescriptionWML]] keys. The array itself can also have an optional '''default''' key which if present should be the index of the initially selected option (useful if you don't need full DescriptionWML but want to set a default). If present it overrides any defaults set in individual options.

The third argument is a table describing the text input field with the following keys:

* ''label'' - A label to show to the left of the text field.
* ''text'' - Initial contents of the text field.
* ''max_length'' - Maximum input length in characters (defaults to 256).

You need at least one key for the text input to be shown. Both the second arguments are option, but if you want text input with no options, you must pass nil for the second parameter.

This function returns two values. The first is the numeric result of the dialog. If there are no options and no text input, this is -2 if the user closed by pressing Escape, otherwise it's -1. If there are options, this is the index of the option chosen (starting from 1). If there is text input but no options, the first return value is 0. If there was text input, the second value contains the text entered.

Example:

wesnoth.show_message_dialog({
title = "Make your choice:",
message = "Select an option and enter some text.",
portrait = "wesnoth-icon.png",
}, {
"The first choice is always the best!",
"Pick me! Second choices are better!",
"You know you want the third option!",
}, {
label = "Text:",
text = "?",
max_length = 16
})

(You don't have to format it like that, of course.)

==== wesnoth.show_popup_dialog ====

* '''wesnoth.show_popup_dialog(''title'', ''message'', [''image''])'''

{{DevFeature1.13|2}}

Shows a simple popup dialog in the centre of the screen. Takes three arguments, which in order are:

# A title string for the dialog
# The message content for the dialog.
# An image to show.

Both the title and the message support Pango markup. The image is optional.

==== wesnoth.show_story ====

* '''wesnoth.show_story(''story_config'', ''default_title'')'''

{{DevFeature1.13|8}}

Shows the storyscreen. The passed config is identical to the contents of [[IntroWML|[story]]]. The second parameter is the default title used if a part does not specify one — unlike intro storyscreens, a Lua-invoked one does not default to the scenario name.

==== wesnoth.show_dialog ====

* '''wesnoth.show_dialog(''wml_dialog_table'', [''pre_show_function'', [''post_show_function'']])'''

Displays a dialog box described by a WML table and returns:
* if the dialog was dismissed by a button click, the integer value associated to the button via the "return_value" keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the resolution section of a GUI window as described in [[GUIToolkitWML#Window_definition|GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

<syntaxhighlight lang=lua>
local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { return_value = -1, T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))
</syntaxhighlight>

==== wesnoth.set_dialog_value ====

* '''wesnoth.set_dialog_value(''value'', ''path, to, widget, id'')'''

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_dialog_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

* '''wesnoth.get_dialog_value(''path, to, widget, id'')'''

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

{{DevFeature1.13|0}}
For treeviews this function returns a table descibing the currently selected node.
If for example in this treeview
+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12
Item 9 is selcted the value will be {2,1,3}

==== wesnoth.set_dialog_active ====

* '''wesnoth.set_dialog_active(''active?'', ''path, to, widget, id'')'''

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

* '''wesnoth.set_dialog_callback(''callback_function'', ''path, to, widget, id'')'''

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_markup ====

* '''wesnoth.set_dialog_markup(''allowed?'', ''path, to, widget, id'')'''

Sets the flag associated to a widget to enable or disable Pango markup. The new flag value is passed as the first argument (boolean), and the widget to modify is obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). Most widgets start with Pango markup disabled unless this function is used to set their flag to true.

wesnoth.set_dialog_markup(true, "notice_label")
wesnoth.set_dialog_value("<big>NOTICE!</big>", "notice_label")

==== wesnoth.set_dialog_focus ====

* '''wesnoth.set_dialog_focus(''focused?'', ''path, to, widget, id'')'''

{{DevFeature1.13|2}}

Switches the keyboard focus to the widget found following the given path (see [[#wesnoth.set_dialog_value]]). This is often useful for dialogs containing a central listbox, so that it can be controlled with the keyboard as soon as it is displayed.

wesnoth.set_dialog_focus("my_listbox")

==== wesnoth.set_dialog_visible ====

* '''wesnoth.set_dialog_visible(''visible?'', ''path, to, widget, id'')'''

{{DevFeature1.13|2}}

Sets a widget's visibility status. The new status is passed as the first argument, and the path to the widget is specified by the remaining arguments (see [[#wesnoth.set_dialog_value]]). The following visibility statuses are recognized:

{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

wesnoth.set_dialog_visible(false, "secret_button")

==== wesnoth.set_dialog_canvas ====

* '''wesnoth.set_dialog_canvas(''index'', ''content'', ''path, to, widget, id'')'''

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

==== wesnoth.add_dialog_tree_node ====

* '''wesnoth.add_dialog_tree_node(''type'', ''index'', ''path, to, widget, id'')'''

{{DevFeature1.13|0}}

Adds a childnode to a treeview widget or a treeview node. The type (id of the node definition) of the node is passed in the first parameter. The second parameter (integer) spcifies where the node should be inserted in the parentnode. The other arguments describe the path of the parent treeview (-node)

==== wesnoth.remove_dialog_item ====

* '''wesnoth.remove_dialog_item(''index'', ''count'', ''path, to, widget, id'')'''

{{DevFeature1.13|1}}

Removes an item from a listbox, a multipage or a treeview. First parameter is the index of the item to delete, second parameter is the number of items to delete and the remaining parameters describe the path to the listbox, the multipage or the parent treview node.

==== wesnoth.is_skipping_messages ====

* '''wesnoth.is_skipping_messages()'''

{{DevFeature1.13|2}}

Returns true if messages are currently being skipped, for example because the player has chosen to skip replay, or has pressed escape to dismiss a message.

==== wesnoth.skip_messages ====

* '''wesnoth.skip_messages([''skip?'')'''

{{DevFeature1.13|2}}

Sets the skip messages flag. By default it sets it to true, but you can also pass false to unset the flag.

==== wesnoth.get_displayed_unit ====

* '''wesnoth.get_displayed_unit()'''

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.log ====

* '''wesnoth.log([''logger''], ''message', ''in_chat'')'''

{{DevFeature1.13|5}} Logs a message to the console. These messages are normally not visible unless Wesnoth is run from the command-line or (in Windows) with the --wconsole switch. The in_chat argument, however, can be set to true to also echo the message to the in-game chat area.

Possible loggers are info, debug, warning, error, and wml. The wml logger is special and is intended for WML errors; it always goes to chat, so the in_chat argument is ignored and can be omitted. The default logger is info.

==== wesnoth.theme_items ====

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

<syntaxhighlight lang=lua>
local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local _ = wesnoth.textdomain "mydomain"
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end
</syntaxhighlight>

The things that would need to be to modified in the above code are:

* the domain of your addon ("mydomain"), assuming that you are using translations. Otherwise just remove the underscore in the tooltip line.
* the name of the status (u.status.entangled). Note that if the attribute happens to be inside [variables], so be it: u.variables.whatever.
* the path to the image ("entangled.png").
* the tooltip of the status ("entangled: This unit ...").

The following is a list of valid entries in wesnoth.theme_items which will have an effect in the game. Unfortunately when this feature was created the full range of capabilities of the feature was never properly documented. The following list is automatically generated. To find out what each entry will do, you will have to make guesses and experiment, or read the source code at src/reports.cpp. If you find out what an entry does, you are more than welcome to edit the wiki and give a proper description to any of these fields.

* '''unit_name'''
* '''selected_unit_name'''
* '''unit_type'''
* '''selected_unit_type'''
* '''unit_race'''
* '''selected_unit_race'''
* '''unit_side'''
* '''selected_unit_side'''
* '''unit_level'''
* '''selected_unit_level'''
* '''unit_amla'''
* '''unit_traits'''
* '''selected_unit_traits'''
* '''unit_status'''
* '''selected_unit_status'''
* '''unit_alignment'''
* '''selected_unit_alignment'''
* '''unit_abilities'''
* '''selected_unit_abilities'''
* '''unit_hp'''
* '''selected_unit_hp'''
* '''unit_xp'''
* '''selected_unit_xp'''
* '''unit_advancement_options'''
* '''selected_unit_advancement_options'''
* '''unit_defense'''
* '''selected_unit_defense'''
* '''unit_vision'''
* '''selected_unit_vision'''
* '''unit_moves'''
* '''selected_unit_moves'''
* '''unit_weapons'''
* '''highlighted_unit_weapons'''
* '''selected_unit_weapons'''
* '''unit_image'''
* '''selected_unit_image'''
* '''selected_unit_profile'''
* '''unit_profile'''
* '''tod_stats'''
* '''time_of_day'''
* '''unit_box'''
* '''turn'''
* '''gold'''
* '''villages'''
* '''num_units'''
* '''upkeep'''
* '''expenses'''
* '''income'''
* '''terrain_info'''
* '''terrain'''
** <nowiki>Text for terrain of the active hex. Same as the one displayed on the UI. It probably returns an empty table when no hex is active. Otherwise, it returns something like {{"element",{text="Grassland (Flat)"}}}.</nowiki>
* '''zoom_level'''
* '''position'''
* '''side_playing'''
* '''observers'''
** <nowiki>When there is no observer, it returns an empty table. When there are observers, it gives
{{"element",
{tooltip="Observers\n<observer1>\n<observer2>\n", image="misc/eye.png"}
}}

</nowiki>
* '''selected_terrain'''
* '''edit_left_button_function'''
* '''report_clock'''
** <nowiki>wesnoth.theme_items.report_clock() gives a table {{"element", text=<time>}}, where <time> is HH:MM of local time. It probably return 12hr or 24hr formats depending on user preference. </nowiki>
* '''report_countdown'''
** <nowiki>wesnoth.theme_items.report_countdown() gives a table {{"element", text=<time>}}, where <time> is MM:SS of time limit for player's turn. If turn limit < 120 or 60, add 
or html tags. </nowiki>

==== helper.get_user_choice ====

* '''helper.get_user_choice(''message_table'', ''options'')'''

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

==== wesnoth.zoom ====

{{DevFeature1.13|8}}

* '''wesnoth.zoom(''factor''[, ''relative''])'''

Changes the zoom level of the map. If relative is false, which is the default, it simply sets the zoom level. If relative is true, it zooms relative to the current zoom level. So, for example, if the zoom level is currently 0.5, then wesnoth.zoom(2) sets it to 2, while wesnoth.zoom(2, true) sets it to 1 (2 * 0.5).

This function also returns the resulting zoom level. Because of this, you can call wesnoth.zoom(1) to simply get the current zoom level.

Note that this function cannot zoom to a level that the user would not be able to reach from the UI. Attempting to do so will simply select the nearest allowed zoom level.

LuaWML/Misc

2014-03-05T20:03:04Z

EliDupree: /* wesnoth.synchronize_choice */

This page describes miscellaneous [[LuaWML]] objects and helpers.

==== wesnoth.game_config ====

Contrarily to the other values of the ''wesnoth'' table, ''game_config'' is simply a proxy table. Its fields offer an interface to the global settings of Wesnoth:

* '''version''': string (read only)
* '''base_income''': integer (read/write)
* '''village_income''': integer (read/write)
* '''poison_amount''': integer (read/write)
* '''rest_heal_amount''': integer (read/write)
* '''recall_cost''': integer (read/write)
* '''kill_experience''': integer (read/write)
* '''last_turn''': integer (read/write) turn limit, maximum number of turns
* '''debug''': boolean (read only)
* '''mp_debug''': boolean (read only) {{DevFeature1.11}}
* '''campaign_type''': string (read only) {{DevFeature1.11}} Indicates what type of game this is, e.g. "multiplayer"
* '''mp_settings''': table {{DevFeature1.11}} In a multiplayer game, this is a proxy table which gives read only access to all MP-only configuration options which appear as attributes of [multiplayer] tag in a save game file:
** '''active_mods''': string (read only) A list of all active modifications
** '''hash''': string (read only) A hash of mp data
** '''mp_campaign''': string (read only) Name of mp campaign
** '''mp_scenario''': string (read only) ID of this mp scenario
** '''mp_scenario_name''': string (read only) Name of this mp scenario
** '''scenario''': string (read only) MP lobby title
** '''difficulty_define''': string (read only) The campaign difficulty string for an mp campaign
** '''mp_village_gold''': integer (read only)
** '''mp_village_support''': integer (read only)
** '''mp_num_turns''': integer (read only)
** '''mp_era''': string (read only) The id of the era
** '''mp_fog''': boolean (read only)
** '''mp_shroud''': boolean (read only)
** '''mp_random_start_time''': boolean (read only)
** '''experience_modifier''': integer (read only)
** '''mp_use_map_settings''': boolean (read only)
** '''mp_countdown''': boolean (read only) Whether the timer is enabled
** '''mp_countdown_action_bonus''': integer (read only)
** '''mp_countdown_init_time''': integer (read only)
** '''mp_countdown_reservoir_time''': integer (read only)
** '''mp_countdown_turn_bonus''': integer (read only)
** '''observer''': boolean (read only)
** '''shuffle_sides''': boolean (read only)
** '''savegame''': boolean (read only) Whether this is a reloaded game
** '''side_users''': string (read only) List of how sides are assigned to users (at game start)
* '''era''': table {{DevFeature1.11}} A proxy table for the entire era tag corresponding to the current era. Its id will always match wesnoth.game_config.mp_settings.mp_era
Note: wesnoth.game_config.mp_settings, and wesnoth.game_config.era, will only exist if wesnoth.game_config.campaign_type == "multiplayer"

-- Poison a bit weak? Let's boost it!
wesnoth.game_config.poison_amount = 15

-- Warn users when they use bad settings:
if (wesnoth.game_config.shuffle_sides) then
wesnoth.message("Warning: This scenario is not intended to be played with shuffle sides!")
end

-- Collect basic info about the current era:
local era = wesnoth.game_config.era
local helper = wesnoth.require("lua/helper.lua")
local count = 0
wesnoth.set_variable("era_name", era.name)
for multiplayer_side in helper.child_range(era, "multiplayer_side") do
count = count + 1
wesnoth.set_variable("faction" .. tostring(count) .. "_name", multiplayer_side.name)
wesnoth.set_variable("faction" .. tostring(count) .. "_recruit", multiplayer_side.recruit)
end
wesnoth.set_variable("num_factions", count)

==== wesnoth.current ====

As with ''game_config'', ''current'' is a proxy table. Its fields are getter for game-related properties:

* '''side''': integer (read only)
* '''turn''': integer (read only)
* '''event_context''': WML table with attributes ''name'', ''x1'', ''y1'', ''x2'', ''y2'', and children ''weapon'', ''second_weapon'', describing the trigger for the current event.

wesnoth.message(string.format("Turn %d, side %d is playing.", wesnoth.current.turn, wesnoth.current.side))

==== wesnoth.synchronize_choice ====

Recovers a WML table that was computed on one client only or was stored in a replay. The actual computation is performed by the function passed as the first argument, assuming that the client is the side currently playing. For all the other clients, the function will not be called. An optional second function can be passed; if present, it will be used instead of the first one when the client happens to be an AI (hence not enable to interact with a user interface).

local result = wesnoth.synchronize_choice(
function()
-- Called only on the client handling the current side, if it is a human.
local choice = 0
wesnoth.show_dialog(
some_dialog_cfg, nil,
function()
choice = wesnoth.get_dialog_value "some_list"
end)
return { value = choice }
end,
function()
-- Called only on the client handling the current side, if it is an AI.
return { value = math.random(some_list_size) }
end)
wesnoth.message(string.format("Selected item: %d", result.value))

Note: The return value must be a valid WML table - the same kind of thing you could store to a WML variable, and not, for instance, a proxy unit, anything else that uses metatables, or a lua table with another table as the value of a string attribute. Unlike other lua functions, wesnoth.synchronize_choice will NOT throw an error if the table is invalid, but will silently strip out the contents of any invalid subtag.

==== wesnoth.get_image_size ====

Returns the width and height of an image.

local w, h = wesnoth.get_image_size "units/transport/galleon.png"

==== wesnoth.compare_versions ====

Takes two versions strings and an operator, returns whether the comparison yields true.
Follows the same rules like the #ifver preprocessor statement.

local function version_is_sufficient(required)
if not wesnoth.compare_versions then return false end
return wesnoth.compare_versions(wesnoth.game_config.version, ">=", required)
end
local required = "1.9.6"
if not version_is_sufficient(required) then wesnoth.message(string.format(
"Your BfW version is insufficient, please get BfW %s or greater!", required)) end

==== wesnoth.have_file ====

{{DevFeature1.11}}Checks if the file (not necessarily a Lua file) or the directory passed as argument exists. Returns true if the file exists, false otherwise. Follows the same rules like the #ifhave preprocessor statement.

-- Does the user have installed the UMC Music Book 1?
local umc_music = wesnoth.have_file( "~add-ons/UMC_Music_Book_1/_main.cfg" )
-- and if we want to check for the folder?
local music_folder = wesnoth.have_file( "~add-ons/UMC_Music_Book_1/" )

==== wesnoth.debug ====

Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string.
wesnoth.set_variable("number", 100)
local vconfig = wesnoth.tovconfig({ key = "$number", another_key = true,
{"a_subtag", { a_key_in_the_subtag = "foo" }}
})
wesnoth.message(wesnoth.debug(vconfig))
wesnoth.message(wesnoth.debug(vconfig.__literal))

==== wesnoth.get_time_stamp ====

{{DevFeature1.11}}This function retrieves the current time stamp, that is the amount of milliseconds passed from when the SDL library was initialized. It takes no arguments and returns an integer.
'''WARNING:''' this function uses the same code as [set_variable] time=stamp, and so it is MP-unsafe. It is provided only for benchmark purposes and AI development, although it should work inside wesnoth.synchronize_choice() as well.
local stamp = wesnoth.get_time_stamp()

==== helper.set_wml_tag_metatable ====

Sets the metable of a table so that it can be used to create subtags with less brackets. Returns the table. The fields of the table are simple wrappers around table constructors.

T = helper.set_wml_tag_metatable {}
W.event { name = "new turn", T.message { speaker = "narrator", message = "?" } }

==== helper.modify_unit ====

Modifies all the units satisfying the given filter (argument 1) with some WML attributes/objects (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MODIFY_UNIT] macro.

helper.modify_unit({ id="Delfador" }, { moves=0 })

==== helper.move_unit_fake ====

Fakes the move of a unit satisfying the given filter (argument 1) to the given position (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MOVE_UNIT] macro.

helper.move_unit_fake({ id="Delfador" }, 14, 8)

==== helper.rand ====

(A shortcut to set_variable's rand= since math.rand is an OOS magnet and therefore disabled.) Pass a string like you would to set_variable's rand=.

create a random unit at (1, 1) on side=1 :
wesnoth.put_unit(1, 1, { type = helper.rand("Dwarvish Fighter,Dwarvish Thunderer,Dwarvish Scout") })

==== helper.round ====

{{DevFeature1.11}}Unlike other languages (Python, Perl, Javascript, ...), Lua does not include a round function. This helper function allows rounding numbers, following the "round half away from zero method", see Wikipedia [[http://en.wikipedia.org/wiki/Rounding_numbers#Round_half_away_from_zero]]. Returns the number rounded to the nearest integer.

-- this number will be rounded up
helper.round(345.67) -- returns 346
-- this one will be rounded down
helper.round(543.21) -- returns 543
-- an integer stays integer
helper.round(123) -- returns 123
-- works also for negative numbers
helper.round(-369.84) -- returns -370
helper.round(-246.42) -- returns -246

==== helper.shuffle ====

{{DevFeature1.11}}This function randomly sorts in place the elements of the table passed as argument, following the Fisher-Yates algorithm. It returns no value.
'''WARNING:''' this function uses Lua's math.random(), and so it is MP-unsafe. It is provided mainly for AI development, although it should work inside wesnoth.synchronize_choice() as well.
local locs = wesnoth.get_locations( { terrain="G*" } )
helper.shuffle( locs )

[[Category: Lua Reference]]

FilterWML

2014-02-12T00:23:44Z

EliDupree: /* Filtering Vision */

{{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".

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> or http://www.wesnoth.org/units/ 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''': filter on the attack's special power. For values see [[AbilitiesWML]].

{{DevFeature1.11}} Also, '''[and]''', '''[or]''', and '''[not]''' subfilters are supported.

== Filtering Terrains ==

''This section describes basically the same as "Filtering Locations" above, namely a [[StandardLocationFilter]].''

Use '''[filter_location]''' within '''[filter]''' , for example:

[event]
[filter]
[filter_location]
terrain=Ch
[/filter_location]
[/filter]
[/event]

At some places the terrains can be filtered with a
match list. The list is a comma separated list and matching will stop
at the first matched [[TerrainCodesWML|terrain string]]. There's one special character
''!'' which inverts the meaning of a match. Terrain strings can
use the wildcard * to match zero or more following letters, characters
behind the * are not allowed and the result is undefined.

Example 1: 
ww* matches ww, www, wwW but not WWW 
!, ww returns false if ww found and true if not 
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.

Example 2: 
<nowiki>*</nowiki>^V* matches all village-terrain 
Notice how the * can be used separately for both layers (base and overlay layers are separated by the ^-character).

For a list of terrain types and their string codes see [[TerrainCodesWML|TerrainCodesWML]].

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or {{DevFeature1.11}} 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 ''viewing_side'' or, when in a SUF, the unit is hiding. {{DevFeature1.11}} The bug in this logic has been fixed to "and, when in a SUF, the unit is not hiding".
** '''no''': matches when the location is obscured by fog or shroud for the ''viewing_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.
* '''viewing_side''': the observing side, or list of observing sides. {{DevFeature1.11}} '''viewing_side''' is deprecated; see StandardSideFilter below
** 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]]''' {{DevFeature1.11}} 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. viewing_side= is renamed to just the [[StandardSideFilter]]'s side=.

'''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]
viewing_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.

== See Also ==

* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter Examples - How to use filters]

[[Category: WML Reference]]