The Battle for Wesnoth Wiki - User contributions [en]

CompatibilityBreakingChanges

2026-04-13T12:12:24Z

Laela: /* Compatibility breaking changes between 1.18 and 1.19/1.20 */

This lists removed WML functionality and helpful hints for avoiding pitfalls.

The previous list is available [https://forums.wesnoth.org/viewtopic.php?t=58532 here].

== Compatibility breaking changes between 1.18 and 1.19/1.20 ==
* The following macros were removed ([https://github.com/wesnoth/wesnoth/pull/11126 #11126])
** EARLY_FINISH_BONUS_NOTE
** NO_EARLY_FINISH_BONUS_NOTE
** NO_GOLD_CARRYOVER_NOTE
** NEW_GOLD_CARRYOVER_NOTE_100
** NEW_GOLD_CARRYOVER_NOTE_40
** NEW_GOLD_CARRYOVER_NOTE_20
** MISSILE_FRAME_FIREBALL
** MESSAGE
** STORY_PART_SPEECH
** LOYAL_UNDEAD_UNIT
** ON_SIGHTING
** MAKE_AI_SIDE_PERSISTENT
** DRAKE_FLYING_ANIM
** NO_INTERRUPT_NO_UNDO
** ENABLE_NIGHTBLADE

<nowiki>This lists removed WML functionality and helpful hints for avoiding pitfalls.

A similar thread for changes before 1.18 can be found [url=https://forums.wesnoth.org/viewtopic.php?t=57288]here[/url].

[b][u]Compatibility breaking (requires updates to work)[/u][/b]
[list][*][c][kill][/c] now reduces target unit hitpoints to 0 before triggering [c]last_breath, die[/c] events. This affects mentioned events that rely on [have_unit] conditions.
[*]WFL Removed properties [c]unit.side[/c] and [c]terrain.owner[/c]. Use [c]unit.side_number[/c] and [c]terrain.owner_side[/c] instead. They return 1-indexed side, removed properties returned 0-indexed side.
[*]Abilities with both [c]add[/c] and [c]sub[/c] now calculate value differently
[*]rotate_loc_around formula now works
[*][era] with id=era_dunefolk does not exist anymore
[*][side]'s leader attribute has been removed
[*][side]'s [variables] tag is now used to set side variables. Use [side]'s [leader] tag to set a unit variable.
[*]Setting gold to decimal value fails with error. Previously it was converted to int automatically. As of 1.19.21, automatic conversion is only done in [gold], but not in Lua or [modify_side].
[/list]

[b][u]Deprecations (will continue to work for now)[/u][/b]
[list][*]rechange [experimental_filter_ability/active] and [experimental_filter_specials] to [filter_ability] and [filter_specials] and make "experimental_" deprecated.
[/list]

[b][u]New features (help fill this list, https://wiki.wesnoth.org/Special:WhatLinksHere/Template:DevFeature1.19)[/u][/b]
[list]
[*]StandardAbilityFilter, including [pr]7814[/pr]
[*][resistance] min_value
[*][attack] alignment
[*]New events [c]unit_hits[/c], [c]unit_misses[/c]
[*]Positive [c]attack_weight[/c] now affects weapon selection
[*]Unit attack [effect]+Lua+formula API min_range and max_range
[*]Lua unit attributes fearless and healthy
[*]wesnoth.game_config shows some color-related values
[*]wesnoth.units.rebuild
[*]stringx.ends_with, stringx.starts_with
[*]Unit formula new attributes objects, advancements_taken, traits_count, objects_count, advancements_taken_count, fearless, healthy
[*]Formula functions lerp_index, ends_with, replace_all, starts_with, get_palette
[*]Custom themes https://wiki.wesnoth.org/GUIToolkit#Custom_themes
[*]Abilities and specials now support [event] (does not work correctly due to [issue]10819[/issue])
[*]Ability & Weapon specials registry ([pr]10644[/pr]) (does not work correctly if ability contains [event] due to [issue]10819[/issue])
[*][effect][remove_specials]
[*]Expose unit pick dialog to Lua as a simple API call ([pr]8829[/pr])
[*][fire_event][data] can be accessed from other event as $data
[*]Unit Type Editor
[*][era]auto_sort allows to use custom faction ordering
[*][terrain_defaults] formula is now working as expected in case formula evaluates to null
[*][set_menu_item] description substitutes variables when rightclick is used
[*][defense]
[*][resistance_defaults] is not causing OOS in random maps anymore
[*]Ability/weapon special descriptions support po variables in descriptions like [c]$add[/c], [c]$sub[/c] etc that contain the value of the relevant key. ([pr]10053[/pr], [pr]10293[/pr], [pr]10749[/pr])
[*]Ability/weapon special help page ids now follow the format: [c]ability_<unique_id>[/c] or [c]weaponspecial_<unique_id>[/c] ([pr]11012[/pr]).
[*]A lot more functions were added to https://wiki.wesnoth.org/LuaAPI/types/widget with https://wiki.wesnoth.org/index.php?title=LuaAPI%2Ftypes%2Fwidget&type=revision&diff=74843&oldid=74842
[/list]</nowiki>

ConditionalActionsWML

2026-03-22T15:17:31Z

Laela: /* [variable] */

{{WML Tags}}

Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside '''[if]''' aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
** [[#Condition Tags|Condition Tags]]: Specifies the conditions, just like in '''[if]'''.
** '''[then]''': Specifies actions, exactly like the '''[then]''' tag inside '''[if]'''.

* '''[else]''': Contains [[ActionWML|actions]] which should be executed if all condition tags in the '''[if]''' and any directly nested '''[elseif]''' all evaluate as false.

'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.

Example usage:
<syntaxhighlight lang=wml>
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[elseif]
[variable]
name=we.gold
equals=$they.gold
[/variable]
[then]
[message]
message=This should be fair!
[/message]
[/then]
[/elseif]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
</syntaxhighlight>

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
<syntaxhighlight lang=wml>
[switch]
variable=foo
[case]
value="A"
# ... WML if foo=A ...
[/case]
[case]
value="B"
# ... WML if foo=B ...
[/case]
[else]
# ... WML if not foo=A nor foo=B ...
[/else]
[/switch]
</syntaxhighlight>

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false. Multiple '''[do]''' tags can be used, and they will be executed in sequence on each iteration. However, there is usually no reason to do this.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros. Note: This macro is deprecated; you should just use the '''[foreach]''' WML tag instead.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [for] ===

{{DevFeature1.13|2}}

Loops over an integer range. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.

* '''variable''': The name of the variable containing the current index. Defaults to ''i''. If there is already a variable with this name, it will be automatically saved before the start of the loop, and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, it will be automatically deleted, there is no need to do a '''[clear_variable]''' afterwards
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [foreach] ===

{{DevFeature1.13|2}}

Loops over an array variable. This is not used to implement the {FOREACH} macro because [foreach] doesn't support adding or removing elements while looping (and will usually raise an error), use '''[for]''' instead.

* '''array''': The array variable to loop over.
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

The '''[foreach]''' tag simulates local-scoping of its index variables. If there was already a WML variable with the same name (by default ''i'' and ''this_item'' respectively), it will be automatically saved before the start of the '''[do]''', and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, there is no need to do a '''[clear_variable]''' afterwards.

It's possible to nest '''[foreach]''' loops, however 1.16 does not support using the same ''variable='' name for both loops ([https://github.com/wesnoth/wesnoth/issues/6305 issue 6305], fixed in {{DevFeature1.17|13}}).

=== [repeat] ===

{{DevFeature1.13|2}}

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use '''[for]''' instead.)

* '''times''': The number of times to repeat the actions.
* '''[do]''': The actions to repeat. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

=== [true] ===

Represents a condition that always yields true. Takes no arguments.

=== [false] ===

Represents a condition that always yields false. Takes no arguments.

=== [have_unit] ===

A unit with greater than zero hit points matching this filter exists.

* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.
* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')

=== [have_location] ===

A location matching this filter exists.

* [[StandardLocationFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

=== [have_side] ===

{{DevFeature1.19|10}}

* [[StandardSideFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, exactly this number of sides must match the filter. Accepts only a number.

=== [has_achievement] ===

{{DevFeature1.17|13}}

The specified achievement has been completed.

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

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

=== [has_sub_achievement] ===

{{DevFeature1.17|17}}

The specified achievement has been completed.

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

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different sub-achievements completed. As such it will always be treated as if the sub-achievement is not completed.

=== [variable] ===

Test the value of a WML [[VariablesWML|variable]] against another value.

* '''name''': The name of the variable to test.
* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
** '''contains''': ''$name'' contains this string value.
** '''equals''': ''$name'' is equal (string wise) to this value.
** '''not_equals''': ''$name'' is not equal (string wise) to this value.
** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
** '''greater_than''': ''$name'' is numerically greater than this value.
** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.
** '''less_than''': ''$name'' is numerically less than this value.
** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.
** '''boolean_equals''': ''$name'' has an equivalent boolean value.
** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.
** '''formula''': {{DevFeature1.15|0}} ''$name'' satisfies the given [[Wesnoth_Formula_Language|WFL]] formula.
** '''blank''': {{DevFeature1.19|19}} ''$name'' is blank when this value is ''yes'' and not blank when this value is ''no''.

====Boolean Values====
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.

* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true.

'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

====Formulas====
When using a formula, the variable's value can be referenced as '''value''' in the formula. This is a WFL representation of a config object that supports the following fields:

* '''__all_children''': A list of key-value pairs, where the key is the tag name and the value is another config object representing the tag content.
* '''__children''': A map from tag name to a list of all children with that tag name.
* '''__attributes''': A map from attribute to value. Only useful if you specifically require a map for some reason.
* ''Any attribute name'': The value of that attribute
* ''Any tag name'': A list of all children with that tag name.
* Note that if there is a tag and an attribute with the same name, accessing it by name will return the attribute. You would need to use '''__children''' to access the tag.

For example, suppose you had a variable with the following WML content:

<syntaxhighlight lang=wml>
[my_variable]
stuff=777
something=a value
[something]
value=42
[/something]
[another_tag]
value=21
[/another_tag]
[subarray]
value=8
[/subarray]
[subarray]
value=91
[/subarray]
[another_tag]
value=12
[/another_tag]
[/my_variable]
</syntaxhighlight>

Then the formula could access the following variables on the '''value''' object:
* '''__all_children''': A list of ordered key-value pairs roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> ['value' -> 42], 'another_tag' -> ['value' -> 21], 'subarray' -> ['value' -> 8], 'subarray' -> ['value' -> 91], 'another_tag' -> ['value' -> 12]]</syntaxhighlight>
* '''__children''': A map roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> [['value' -> 42]], 'another_tag' -> [['value' -> 21], ['value' -> 12]], 'subarray' -> [['value' -> 8], ['value' -> 91]]]</syntaxhighlight>
* '''__attributes''': A map equivalent to <syntaxhighlight lang=wfl inline>['stuff' -> 777, 'something' -> 'a value']</syntaxhighlight>
* '''stuff''': The number <syntaxhighlight lang=wfl inline>777</syntaxhighlight>
* '''something''': The string <syntaxhighlight lang=wfl inline>'a value'</syntaxhighlight>
* '''another_tag''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 21], ['value' -> 12]]</syntaxhighlight>
* '''subarray''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 8], ['value' -> 91]]</syntaxhighlight>

{{DevFeature1.17|11}} When using a formula, you can now specify an additional key:

* '''as_type''': Specifies the type of the '''value''' object in the formula. The default is ''wml'', which uses the structure as described above. The other supported options are:
** ''unit'': Interprets the variable's value as a stored unit, allowing you to write the formula the same way you would in a [[StandardUnitFilter]].
** ''weapon'': Interprets the variable's value as an attack type, allowing you to write the formula the same way you would in a [[StandardWeaponFilter]].

=== [found_item] ===

{{DevFeature1.13|2}} Test if an item (i.e., a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event in the same scenario. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function, nor objects added in a previous scenario in a campaign.

* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

=== [proceed_to_next_scenario] ===

{{DevFeature1.13|10}} In SP, true if the scenario has been won.

=== [lua] ===

{{DevFeature1.13|11}} Evaluate a lua expression, which must return a boolean value. Useful for writing one-off conditions that are difficult to express with other tags, but for much-used conditions it's better to define a custom condition tag using [[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]].

* '''code''': The Lua expression.
* '''name''': A name used to identify the tag in error messages.
* '''[args]''': Arbitrary data passed to the expression, accessible via <tt>...</tt> in the Lua code.

For example

<syntaxhighlight lang=wml>
[event]
name=new turn
first_time_only=no
[filter_condition]
[lua]
code = << return (wml.variables.turn_number % 2 == 0) >>
[/lua]
[/filter_condition]
[message]
speaker=narrator
message= "Hello world $turn_number|"
[/message]
[/event]
</syntaxhighlight>

=== Meta-Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
# this true or false result is combined with the top meta-condition to produce another true or false result
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.

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

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

LuaAPI/wml

2026-03-20T21:09:25Z

Laela:

<div class="tright"> __TOC__ </div>

The <tt>wml</tt> module contains functions for working with WML tables. This module is available starting in 1.14.0.

A WML table is a specially-formatted Lua table representing WML tags and values. For more detail on the format of WML tables, see [[LuaWML#Encoding_WML_objects_into_Lua_tables|LuaWML]].

== Functions ==

=== wml.attribute_count ===

{{DevFeature1.15|3}}

* '''wml.attribute_count'''(''config'') → ''count''

Returns the number of attributes in the specified WML table.

=== wml.child_array ===

* '''wml.child_array'''(''config'', ''child_tag_name'') → ''array''

Like [[#wml.child_range]], but returns an array instead of an iterator. Useful if you need random access to the children.

=== wml.child_count ===

* '''wml.child_count'''(''config'', ''child_tag_name'') → ''count''

Returns the number of children in the config with the given tag name.

=== wml.child_range ===

* '''wml.child_range'''(''config'', ''child_tag_name'') → ''iterator'' ⇒ ''wml table''

Returns an iterator over all the sub-tags of a WML object with the given name.

<syntaxhighlight lang=lua>
local u = wesnoth.units.find_on_map{ id = "Delfador" }[1]
for att in wml.child_range(u.__cfg, "attack") do
wesnoth.message(tostring(att.description))
end
</syntaxhighlight>

=== wml.find_child ===

{{DevFeature1.15|3}}

* '''wml.find_child'''(''config'', [''tag_name''], ''filter'') → ''child or nil'', ''index''

Finds a child of the given config that matches the given filter, and returns the child or nil if not found. The index of the child is also returned. If a tag name is specified, the search is restricted to that tag.

=== wml.get_child ===

* '''wml.get_child'''(''config'', ''child_tag_name'', [''id'']) → ''child_table''

Returns the first sub-tag of a WML object with the given name.

<syntaxhighlight lang=lua>
local u = wesnoth.units.find_on_map{ id = "Delfador" }[1]
local costs = wml.get_child(u.__cfg, "movement_costs")
wesnoth.message(string.format("Delfador needs %d points to move through a forest.", costs.forest))
</syntaxhighlight>

If a third parameter is passed, only children having a ''id'' attribute equal to it are considered.

=== wml.get_nth_child ===

* '''wml.get_nth_child'''(''config'', ''child_tag_name'', ''n'') → ''child_table''

Returns the ''n''th sub-tag of a WML object with the given name.

=== wml.remove_child ===

* '''wml.remove_child'''(''config'', ''child_tag_name'')

Deletes the first child tag with the given name. This does not work on vconfig objects, however.

=== wml.remove_children ===

{{DevFeature1.17|0}}

* '''wml.remove_children'''(''config'', ''child_tag_name'', ...)

Deletes all child tags with the given names. This does not work on vconfig objects, however. You can pass as many tag names as you want as separate arguments.

=== wml.tag ===

* '''wml.tag'''.''tag_name''(''contents'') → ''tag_table''

Returns a table representing a tag within a WML table; can be used to create subtags with less brackets. It's common to use direct-table invocation for this, omitting the function parentheses.

<syntaxhighlight lang=lua>
wesnoth.wml_actions.event { name = "new turn", wml.tag.message { speaker = "narrator", message = "?" } }
</syntaxhighlight>

=== wml.clone ===

{{DevFeature1.15|0}}

* '''wml.clone'''(''wml_table'') → ''cloned_table''

Returns a clone (deep copy) of the passed WML table.

=== wml.equal ===

{{DevFeature1.15|3}}

* '''wml.equal'''(''config'', ''config'') → ''true or false''

Tests whether two WML objects are equal. Equal objects will produce an empty diff, and will be serialized to the same string.

=== wml.valid ===

{{DevFeature1.15|3}}

* '''wml.valid'''(''table'') → ''is_wml''

Tests whether the passed table represents a valid WML table. It will also return true if passed a vconfig.

=== wml.valid_var ===

{{DevFeature1.19|19}}

* '''wml.valid_var'''(''string'') → ''true or false''

Returns true if input looks like WML variable path for [set_variables].

=== wml.matches_filter ===

* '''wml.matches_filter'''(''WML table'', ''filter'')''' → ''boolean''

Test if a config matches a WML filter (as [[FilterWML#Filtering_on_WML_data|<tt>[filter_wml]</tt>]]).

=== wml.load ===

{{DevFeature1.15|0}}

* '''wml.load'''(''file'', [''defines'', [''schema'']]) → ''config''

Loads WML from a file and optionally validates it against a schema. The file and schema (if present) must both be a valid WML path, and the schema must point to a [[SchemaWML]] file. All built-in schema files can be found directly in the "schema" folder – for example, "schema/game_config.cfg" is the schema for an add-on's (and core's) _main.cfg.

The second parameter can either be a boolean specifying whether or not to preprocess the file (defaults to true), or an array of macros to be defined in the preprocessor (which of course implies the file will be preprocessed). The second form only allows specifying names to be defined. It does not allow setting a value or anything more complex.

=== wml.parse ===

{{DevFeature1.15|0}}

* '''wml.parse'''(''string'', [''schema'']) → ''config''

Parses a string containing WML code and optionally validates it against the provided schema. Unlike load, this function does ''not'' run the preprocessor, though <tt>#textdomain</tt> directives will still be recognized.

=== wml.merge ===

{{DevFeature1.15|3}}

* '''wml.merge'''(''base table'', ''merge data'', [''mode'']) → ''merged config''

Merges two WML tables recursively, using the specified mode. Possible modes are '''merge''', '''replace''', and '''append'''. The modes work the same as in [[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]. The mode only affects how child tags are merged; merging of attributes is always done the same way. The default mode is '''merge'''.

=== wml.diff ===

{{DevFeature1.15|3}}

* '''wml.diff'''(''left'', ''right'') → ''diff config''

Compares two WML tables and produces an output table in [[DiffWML]] detailing their differences.

=== wml.patch ===

{{DevFeature1.15|3}}

* '''wml.patch'''(''base'', ''diff'') → ''patched config''

Takes a WML table and a diff in [[DiffWML]] format and returns a new WML table modified according to the diff's instructions.

=== wml.interpolate ===

{{DevFeature1.15|3}}

* '''wml.interpolate'''('''template''', '''variables''') → ''interpolated config''

Interpolates variables into a WML table, including '''[insert_tag]'''. This is the same as what a vconfig does implicitly, but can use any valid WML table as a source of variables.

<syntaxhighlight lang=lua>
local variables = {
-- A scalar variable
number = 100,
-- An array variable with two entries
wml.tag.list{value = 42, rank = 3},
wml.tag.list{value = 21, rank = 1},
}
local subst = {
key = "$number",
wml.tag.insert_tag{
name = "entry",
variable = "list"
}
}
local result = wml.interpolate(subst, variables)
print(wml.tostring(result))
</syntaxhighlight>

The above code will output the following WML in the Lua console:

<syntaxhighlight lang=wml>
key=100
[entry]
rank=3
value=42
[/entry]
[entry]
rank=1
value=21
[/entry]
</syntaxhighlight>

=== wml.tostring ===

* '''wml.tostring'''(''wml_table'') → ''string''

Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string. {{DevFeature1.15|0}} The string output is syntactically valid WML that if parsed would produce the same config.

<syntaxhighlight lang=lua>
wml.variables["number"] = 100
local vconfig = wml.tovconfig({ key = "$number", another_key = true,
{"a_subtag", { a_key_in_the_subtag = "foo" }}
})
wesnoth.message(wml.tostring(vconfig))
wesnoth.message(wml.tostring(vconfig.__literal))
</syntaxhighlight>

=== wml.tovconfig ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.tovconfig'''(''config'') → ''vconfig''

Converts a WML table into a proxy object which performs variable substitution on the fly. The proxy object can for most intents and purposes be treated as a read-only table - the length operator works as expected, as does the ipairs function. The pairs function also works, but it is a little different than on a plain table - it will return only the attributes of the vconfig and not the tags. See [[LuaWML#Encoding_WML_objects_into_Lua_tables|LuaWML]] for more information about the structure of a vconfig (which is the same as the structure of a WML table). A vconfig has four special keys (''__literal'', ''__parsed'', ''__shallow_literal'', ''__shallow_parsed'') which correspond to the functions in this module by the same name, but in most cases it is better to use the functions.

<syntaxhighlight lang=lua>
wml.variables["varname"] = "to_be_deleted"

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

=== wml.literal ===

* '''wml.literal'''(''config'') → ''wml_table''

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. If the argument is ''nil'', it returns an empty table. 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 = wml.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.

=== wml.parsed ===

* '''wml.parsed'''(''config'') → ''wml_table''

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

=== wml.shallow_literal ===

* '''wml.shallow_literal'''(''config'') → ''wml_table''

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

=== wml.shallow_parsed ===

* '''wml.shallow_parsed'''(''config'') → ''wml_table''

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

=== wml.all_variables ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.all_variables''' → ''table''

Returns a copy of all the WML variables currently set in the form of a WML table.

<syntaxhighlight lang=lua>
for key, value in pairs(wml.all_variables) do
if type(value) == "table" then
print(key, value[1], value[2])
else
print(key, value)
end
end
</syntaxhighlight>

=== wml.variables ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables'''.''variable'' ↔ ''variable_contents''
* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables'''[''variable_path''] ↔ ''variable_contents''

This table grants read-write access to the WML variables by their fully-qualified name. Looking up a non-existent variable yields nil; otherwise, it returns a scalar for a WML attribute and a table for a WML object. The format of the table is described in [[LuaWML#Encoding WML objects into Lua tables]].

<syntaxhighlight lang=lua>
wesnoth.fire("store_unit", { variable="my_unit", { "filter", { id="hero" } } })
local heros_hp = wml.variables["my_unit[0].hitpoints"]
wesnoth.message(string.format("The 'hero' unit has %d hitpoints.", heros_hp))
</syntaxhighlight>

Note that, if the variable name happens to designate a sequence of WML objects, only the first one (index 0) is fetched. If all the WML objects with this name should have been returned, use [[#wml.array_access.get]] instead. If you need a specific one, include the index in the lookup key.

Assigning to a key in this table converts the Lua object to a WML variable if possible. For a table, a WML object is created; otherwise, an attribute is created. Note that you cannot assign a simple array as it will be mistaken for a WML table and give an error. Assigning nil clears the variable.

<syntaxhighlight lang=lua>
wml.variables["my_unit.hitpoints"] = heros_hp + 10
</syntaxhighlight>

=== wml.variables_proxy ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables_proxy'''.''variable'' ↔ ''proxy''
* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables_proxy'''[''variable_path''] ↔ ''proxy''

Similar to <tt>wml.variables</tt>, but if the variable is a container, then the fields of the returned table are then proxies to the WML objects with the same names; reading/writing to them will directly access the WML sub-variables. Note that this is still somewhat experimental and doesn't allow you to fully treat variables as if they were standard Lua tables.

=== wml.array_access.get ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_access.get'''(''var_name'', [''context'']) → ''array of variable_contents''

Fetches all the WML container variables with given name and returns a table containing them (starting at index 1). The context specifies where to get variables from. You can pass either a unit or a side as the context in order to get an array from the unit variables or side variables, respectively.

<syntaxhighlight lang=lua>
function get_recall_list(side)
wesnoth.fire("store_unit", { x = "recall", variable = "LUA_recall_list" })
local l = wml.array_access.get "LUA_recall_list"
wml.variables.LUA_recall_list = nil
return l
end
</syntaxhighlight>

=== wml.array_access.get_proxy ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_access.get_proxy'''(''var_name'') → ''array of proxies''

Creates proxies for all the WML container variables with given name and returns a table containing them (starting at index 1). This function is similar to [[#wml.array_access.get]], except that the proxies can be used for modifying WML containers. Note that changes to the returned array itself will not be reflected in the variable, however; only changes to the array elements.

=== wml.array_access.set ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_access.set'''(''varname'', ''array'', [''context''])

Creates WML container variables with given name from given table. The context specifies where to put the variables. You can pass either a unit or a side as the context in order to set an array in the unit variables or side variables, respectively.

<syntaxhighlight lang=lua>
wml.array_access.set("target", { {t=t1}, {t=t2}, {t=t3} })
-- target[0].t <- t1; target[1].t <- t2; target[2].t <- t3
</syntaxhighlight>

=== wml.array_variables ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_variables'''.''variable'' ↔ ''array of variable_contents''
* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_variables'''[''variable_path''] ↔ ''array of variable_contents''

Like '''wml.variables''', except that it works on arrays as with '''wml.array_access.get''' and '''wml.array_access.set'''. This is a little more convenient when working with global WML variables rather than unit or side variables.

=== wml.eval_conditional ===

* {{LuaGameOnly}} '''wml.eval_conditional'''(''conditional_tags'') → ''boolean''

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

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

Note: Prior to 1.15.13, this was available as '''wesnoth.eval_conditional'''.

=== wml.fire ===

* {{LuaGameOnly}} '''wml.fire'''(''tag'', ''parameters'')
* {{DevFeature1.17|17}} {{LuaGameOnly}} '''wml.fire'''.''tag''(''parameters'')

Fire a WML action tag. Note: WML variables are substituted into the parameters table.

Note: Prior to 1.15.13, this was available as '''wesnoth.fire'''. The second form was available through '''helper.set_wml_action_metatable'''.

=== wml.error ===

* {{LuaGameOnly}} '''wml.error'''(''message'')

Interrupts the current execution and displays a WML error message. This is intended for error messages in the implementaton of custom ActionWML or ConditionalWML tags. For errors in a Lua API, the built-in '''error''' function is a more suitable choice.

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

[[Category: Lua Reference]]

Distributing content

2025-09-17T08:00:08Z

Laela:

{{Create}}

You've completed your creation. You've tested it, polished it, and tweaked it. You feel confident that your add-on is the greatest achievement since the sandwich was invented. Now what? Make it available to the world!

== The Add-on Server ==

The add-on server is the preferred way to distribute your creations, whether it's a single map or a large campaign. The rules for publishing to the add-ons server are [https://forums.wesnoth.org/viewtopic.php?f=15&t=24320 here].

In in order to publish an add-on to the server, you need to create a _server.pbl file inside your add-on's directory. Detailed instructions on the syntax of the file are located on the [[PblWML]] page. The _main.cfg file is also required, even for resource add-ons.

Once you are ready to publish:
* Open Wesnoth
* Select Add-ons from the main menu
* Connect to the default add-ons.wesnoth.org add-on server
* In 1.12: Select your add-on, which will be the last entry in the list of add-ons. Then select Publish add-on: Your Add-on Name
* In 1.14: In the "State" drop-down above the list, select "Publishable", and the list will show only your add-on. Select your add-on, then click on the shield icon with the upwards arrow.

Note: If you haven't included a passphrase in the _server.pbl file then Wesnoth will add a randomly-generated password to it. This password can be used to upload updates. {{DevFeature1.15|12}} it will prompt for a passphrase instead of randomly generating one.

Note: By default, all files and folders inside the add-on's directory are uploaded, except those that begin with '.' and those that end in '~'. If you want to exclude any others, you may do so by creating a _server.ign file and listing within it the files or folders you wish not to be uploaded (see [[IGNFileFormat]] for more information).

Note: A command-line interface to publish add-ons exists for those who prefer it. The script is located in a path like "/share/wesnoth/data/tools/wesnoth_addon_manager" (may depend on your OS and wesnoth version).

==== License ====

Whenever you upload or update your add-on, you will have to confirm that it is licensed as required by
* [[Wesnoth:Copyrights#User_Made_Content_-_Code]] and
* [[Wesnoth:Copyrights#User_Made_Content_-_Visual_and_Audio_Content]]

When a user downloads your add-on, it will include the ART_LICENSE that you included and a COPYING.txt file containing a copy of the GNU GPL version 2, signifying the content is licensed under such.

== The Forum ==

Creating a thread on the [http://www.wesnoth.org/forum/ Wesnoth forums] is a good way to receive feedback for your add-on. Making use of the [feedback] tag in your _server.pbl is also highly recommended.

While it is possible to upload your add-on directly to the forums, that is not recommended since it requires extra steps on the part of the downloader and limits the add-on's exposure to players who regularly visit the forum.

== Version control distribution ==

It is recommended that you create your own personal repository on a service such as [https://github.com/ GitHub]. This will allow tracking changes you make to your content, as well as make it easier for others to collaborate with you.

== See Also ==

* [[Create]]
* [[PblWML]]
* [[IGNFileFormat]]
* [[Wesnoth:Copyrights]]
* [[Guide_to_UMC_Campaigns|Guide to UMC Campaigns]]
* [[AddonServers]]

[[Category:Create]]

LuaWML/Reorganization

2025-07-23T21:53:59Z

Laela:

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

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

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

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

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

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

The categories and names being proposed are as follows:

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

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

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

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

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

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

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

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

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

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

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

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

Template:WML Tags

2025-07-14T09:01:43Z

Laela: remove SavefileWML links from template

{| class="reference-sidebar"
|-
|
[[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit]]'''[[ReferenceWML|WML Tags]]'''
|-
|''A:''
[[AbilitiesWML#The .5Babilities.5D tag|abilities]],
[[CreditsWML#.5Babout.5D|about]],
[[AchievementsWML#.5Bachievement.5D|achievement]],
[[AchievementsWML#.5Bachievement_group.5D|achievement_group]],
[[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions|add_ai_behavior]],
[[AdvancedPreferenceWML|advanced_preference]],
[[UnitTypeWML#advancefrom|advancefrom]],
[[UnitTypeWML#After_max_level_advancement_.28AMLA.29|advancement]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],
[[AbilitiesWML#affect_adjacent|affect_adjacent]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|ai]],
[[StandardSideFilter#allied_with|allied_with]],
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],
[[ConditionalActionsWML#Meta-Condition_Tags|and]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],
[[AnimationWML#The .5Banimation.5D tag|animation]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|aspect]],
attack ([[ReplayWML#attack|replay]], [[UnitTypeWML#Attacks|weapon]]),
[[AnimationWML#short-attack|attack_anim]],
attacks ([[AbilitiesWML#The_.5Bspecials.5D_tag|special]], [[StatisticalScenarioWML#The_.5Bteam.5D_tag|stats]]),
[[AiWML#avoid|avoid]];
|-
|''B:''
[[UnitTypeWML#base_unit|base_unit]],
[[IntroWML#.5Bbackground_layer.5D|background_layer]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|berserk]],
[[BinaryPathWML|binary_path]],
[[InternalActionsWML#Flow_control_actions|break]],
[[EditorWML#The_.5Bbrush.5D_tag|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML#.5Bcancel_action.5D|cancel_action]],
[[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|candidate_action]],
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|chance_to_hit]],
[[InterfaceActionsWML#.5Bchange_theme.5D|change_theme]],
[[InterfaceActionsWML#.5Bchat.5D|chat]],
[[OptionWML#checkbox|checkbox]],
[[OptionWML#choice|choice]],
[[ReplayWML#choose|choose]],
[[PersistenceWML#WML Syntax|clear_global_variable]],
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],
[[InternalActionsWML#.5Bclear_variable.5D|clear_variable]],
[[InterfaceActionsWML#.5Bcolor_adjust.5D|color_adjust]],
[[GameConfigWML#Color_Palettes|color_palette]],
[[GameConfigWML#Color_Palettes|color_range]],
command ([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]),
[[InternalActionsWML#Flow_control_actions|continue]],
[[CoreWML|core]],
[[CreditsWML#.5Bcredits_group.5D|credits_group]],
[[AiWML#The_.5Bgoal.5D_Tag|criteria]];
|-
|''D:''
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage_type]],
[[AnimationWML#short-death|death]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|deaths]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|default]],
[[AnimationWML#short-defend|defend]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|defends]],
[[UnitsWML#defense|defense]],
[[InterfaceActionsWML#.5Bdelay.5D|delay]],
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],
[[ReplayWML#attack|destination]],
[[CampaignWML#difficulty|difficulty]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|disable]],
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]],
[[DirectActionsWML#.5Bdo_command.5D|do_command]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|drains]],
[[AnimationWML#short-draw_weapon|draw_weapon_anim]];
|-
|''E:''
[[EditorWML#The_.5Beditor_group.5D_tag|editor_group]],
[[EditorWML#The_.5Beditor_music.5D_tag|editor_music]],
[[EditorWML#The_.5Beditor_times.5D_tag|editor_times]],
[[EffectWML|effect]],
else ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#Conditional Branches|animation]]), [[ConditionalActionsWML#.5Bif.5D|elseif]],
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],
end_turn ([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML#end_turn|replay]]),
[[StandardSideFilter#enemy_of|enemy_of]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Engines|engine]],
entry ([[CreditsWML#.5Bentry.5D|credits]], [[OptionWML#entry|options]]),
[[EraWML|era]],
[[EventWML|event]],
[[StandardUnitFilter#filter_ability|experimental_filter_ability]],
[[StandardUnitFilter#filter_ability_active|experimental_filter_ability_active]],
[[AbilitiesWML#filter_specials|experimental_filter_specials]],
[[AnimationWML#short-extra|extra_anim]];
|-
|''F:''
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]],
[[InterfaceActionsWML#.5Banimate_unit.5D|facing]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|fake_unit]],
[[ConditionalActionsWML#.5Bfalse.5D|false]],
[[PblWML#.5Bfeedback.5D|feedback]],
[[UnitTypeWML#variation|female]],
filter ([[FilterWML|concept]], [[EventWML#.5Bfilter.5D|event]]),
[[StandardUnitFilter#filter_adjacent|filter_adjacent]],
[[StandardLocationFilter#filter_adjacent_location|filter_adjacent_location]],
[[FilterWML#Filtering_Weapons|filter_attack]],
[[AbilitiesWML#filter_attacker|filter_attacker]],
[[AbilitiesWML#filter_base_value|filter_base_value]],
[[EventWML#.5Bfilter_condition.5D|filter_condition]],
[[AbilitiesWML#filter_defender|filter_defender]],
[[AiWML#Filtering_Combat_with_the_attacks_Aspect|filter_enemy]],
[[StandardLocationFilter|filter_location]],
[[AbilitiesWML#filter_opponent|filter_opponent]],
[[AiWML#Filtering_Combat_with_the_attacks_Aspect|filter_own]],
[[StandardLocationFilter#filter_owner|filter_owner]],
[[StandardLocationFilter#filter_radius|filter_radius]],
[[SingleUnitWML#filter_recall|filter_recall]],
[[StandardUnitFilter|filter_second]],
[[FilterWML#Filtering_Weapons|filter_second_attack]],
[[AbilitiesWML#filter_self|filter_self]],
[[StandardSideFilter|filter_side]],
[[AbilitiesWML#filter_student|filter_student]],
[[FilterWML#Filtering_Vision|filter_vision]],
[[FilterWML#Filtering_Weapons|filter_weapon]],
[[FilterWML#Filtering_on_WML_data|filter_wml]],
[[InternalActionsWML#.5Bfind_path.5D|find_path]],
[[InternalActionsWML#.5Bfire_event.5D|fire_event]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]],
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],
[[FontsWML|fonts]],
[[ConditionalActionsWML#.5Bfor.5D|for]],
[[ConditionalActionsWML#.5Bforeach.5D|foreach]],
[[ConditionalActionsWML#.5Bfound_item.5D|found_item]],
[[AnimationWML#The .5Bframe.5D tag|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[PersistenceWML#WML Syntax|get_global_variable]],
[[AiWML#The_.5Bgoal.5D_Tag|goal]],
[[DirectActionsWML#.5Bgold.5D|gold]],
[[InterfaceActionsWML#objectives-gold_carryover|gold_carryover]];
|-
|''H:''
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],
[[StandardSideFilter#has_ally|has_ally]],
[[StandardUnitFilter#has_attack|has_attack]],
[[StandardSideFilter#has_unit|has_unit]],
[[ConditionalActionsWML#.5Bhas_achievement.5D|has_achievement]],
[[ConditionalActionsWML#.5Bhave_location.5D|have_location]],
[[ConditionalActionsWML#.5Bhave_side.5D|have_side]],
[[ConditionalActionsWML#.5Bhave_unit.5D|have_unit]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|heal_on_hit]],
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],
[[AnimationWML#short-healed|healed_anim]],
[[AnimationWML#short-healing|healing_anim]],
[[AbilitiesWML#The_.5Babilities.5D_tag|heals]],
[[UnitsWML#.5Bhide_help.5D|hide_help]],
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]],
[[AbilitiesWML#The_.5Babilities.5D_tag|hides]];
|-
|''I:''
[[AnimationWML#short-idle|idle_anim]],
if ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#Conditional Branches|animation]], [[IntroWML|intro]]),
[[AbilitiesWML#The_.5Babilities.5D_tag|illuminates]],
image ([[IntroWML#.5Bimage.5D|intro]], [[TerrainGraphicsWML#The_.5Bimage.5D_subtag|terrain]]),
[[ReplayWML#init_side|init_side]],
[[VariablesWML#.5Binsert_tag.5D|insert_tag]],
[[InterfaceActionsWML#.5Binspect.5D|inspect]],
[[InterfaceActionsWML#.5Bitem.5D|item]],
[[EditorWML#The_.5Bitem_group.5D_tag|item_group]];
|-
|''J:''
[[UnitsWML#jamming_costs|jamming_costs]],
[[InternalActionsWML#join|join]];
|-
|''K:''
[[DirectActionsWML#.5Bkill.5D|kill]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|killed]];
|-
|''L:''
[[InterfaceActionsWML#.5Blabel.5D|label]],
[[LanguageWML|language]],
[[SideWML#leader|leader]],
[[AiWML#leader_goal|leader_goal]],
[[AbilitiesWML#The_.5Babilities.5D_tag|leadership]],
[[AnimationWML#short-leading|leading_anim]],
[[AnimationWML#short-levelin|levelin_anim]],
[[AnimationWML#short-levelout|levelout_anim]],
[[DirectActionsWML#.5Blift_fog.5D|lift_fog]],
[[AI_Recruitment#instructions-limit|limit]],
[[InternalActionsWML#set_variables-literal|literal]],
[[AddonsWML#load_resource|load_resource]],
[[LocaleWML|locale]],
[[InterfaceActionsWML#.5Block_view.5D|lock_view]],
[[LuaWML|lua]];
|-
|''M:''
[[UnitTypeWML#variation|male]],
[[ReplayWML#map_data|map_data]],
[[InterfaceActionsWML#.5Bmessage.5D|message]],
[[Micro AIs|micro_ai]],
[[AnimationWML#The .5Bframe.5D tag|missile_frame]],
[[ModificationWML|modification]],
[[SingleUnitWML#modifications|modifications]],
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],
[[AddonsWML#modify_unit_type|modify_unit_type]],
[[ReplayWML#move|move]],
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],
[[AnimationWML#short-movement|movement_anim]],
[[UnitsWML#movement_costs|movement costs]],
[[UnitsWML#.5Bmovetype.5D|movetype]],
[[ScenarioWML#The_.5Bmultiplayer.5D_tag|multiplayer]],
[[EraWML#Defining_Factions|multiplayer_side]],
[[MusicListWML#.5Bmusic.5D|music]];
|-
|''N:''
[[ConditionalActionsWML#Meta-Condition_Tags|not]],
[[InterfaceActionsWML#objectives-note|note]];
|-
|''O:''
[[DirectActionsWML#.5Bobject.5D|object]],
[[InterfaceActionsWML#objectives-objective|objective]],
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],
[[DirectActionsWML#.5Bon_undo.5D|on_undo]],
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],
[[InterfaceActionsWML#.5Bmessage.5D|option]],
[[OptionWML|options]],
[[ConditionalActionsWML#Meta-Condition_Tags|or]];
|-
|''P:''
[[IntroWML#.5Bpart.5D|part]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]],
[[DirectActionsWML#.5Bpetrify.5D|petrify]],
[[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|plague]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|poison]],
[[AnimationWML#short-post_movement|post_movement_anim]],
[[AnimationWML#short-pre_movement|pre_movement_anim]],
[[InternalActionsWML#.5Bfire_event.5D|primary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|primary_unit]],
[[InterfaceActionsWML#.5Bprint.5D|print]],
[[DirectActionsWML#.5Bprogress_achievement.5D|progress_achievement]],
[[DirectActionsWML#.5Bput_to_recall_list.5D|put_to_recall_list]];
|-
|''R:''
[[UnitsWML#.5Brace.5D|race]],
[[InternalActionsWML#.5Brandom_placement.5D|random_placement]],
recall ([[DirectActionsWML#.5Brecall.5D|action]], [[ReplayWML#recall|replay]]),
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|recalls]],
[[ReplayWML#recruit|recruit]],
[[AnimationWML#short-recruit|recruit_anim]],
[[AnimationWML#short-recruiting|recruiting_anim]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|recruits]],
[[InterfaceActionsWML#.5Bredraw.5D|redraw]],
[[AbilitiesWML#The_.5Babilities.5D_tag|regenerate]],
[[InternalActionsWML#.5Bremove_event.5D|remove_event]],
[[InterfaceActionsWML#.5Bremove_item.5D|remove_item]],
[[DirectActionsWML#.5Bremove_object.5D|remove_object]],
[[DirectActionsWML#.5Bremove_shroud.5D|remove_shroud]],
[[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]],
[[DirectActionsWML#.5Bremove_time_area.5D|remove_time_area]],
[[DirectActionsWML#.5Bremove_trait.5D|remove_trait]],
[[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],
[[ConditionalActionsWML#.5Brepeat.5D|repeat]],
[[DirectActionsWML#.5Breplace_map.5D|replace_map]],
[[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]],
[[ReplayWML|replay]],
[[DirectActionsWML#.5Breset_fog.5D|reset_fog]],
resistance ([[AbilitiesWML#The_.5Babilities.5D_tag|ability]], [[UnitsWML#resistance|unit]]),
[[UnitsWML#.5Bresistance_defaults.5D|resistance_defaults]],
[[ThemeWML#The_toplevel_.5Btheme.5D_tag|resolution]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|resource]],
[[InternalActionsWML#Flow_control_actions|return]],
[[InternalActionsWML#.5Brole.5D|role]],
[[TerrainMaskWML#rule|rule]];
|-
|''S:''
[[ScenarioWML#The_.5Bscenario.5D_tag|scenario]],
[[InterfaceActionsWML#.5Bscreen_fade.5D|screen_fade]],
[[InterfaceActionsWML#.5Bscroll.5D|scroll]],
[[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_unit]],
[[HelpWML#section|section]],
[[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]],
[[ReplayWML#sequence|sequence]],
[[DirectActionsWML#.5Bset_achievement.5D|set_achievement]],
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],
[[PersistenceWML#WML_Syntax|set_global_variable]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]],
[[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],
[[EffectWML#set_specials|set_specials]],
[[InternalActionsWML#.5Bset_variable.5D|set_variable]],
[[InternalActionsWML#.5Bset_variables.5D|set_variables]],
[[AnimationWML#short-sheath_weapon|sheath_weapon_anim]],
show_if ([[InterfaceActionsWML#.5Bmessage.5D|message]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]]),
[[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],
[[SideWML|side]],
[[AbilitiesWML#The_.5Babilities.5D_tag|skirmisher]],
[[OptionWML#slider|slider]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|slow]],
[[InterfaceActionsWML#.5Bsound.5D|sound]],
[[InterfaceActionsWML#.5Bsound_source.5D|sound_source]],
source ([[ReplayWML#attack|replay]], [[DirectActionsWML#.5Btunnel.5D|teleport]]),
[[UnitTypeWML#Special Notes|special_note]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|specials]],
[[InternalActionsWML#set_variables-split|split]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Stages|stage]],
[[AnimationWML#short-standing|standing_anim]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[SingleUnitWML#status|status]],
[[InternalActionsWML#.5Bstore_gold.5D|store_gold]],
[[InternalActionsWML#.5Bstore_items.5D|store_items]],
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],
[[InternalActionsWML#.5Bstore_relative_direction.5D|store_relative_direction]],
[[InternalActionsWML#.5Bstore_side.5D|store_side]],
[[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]],
[[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]],
[[InternalActionsWML#.5Bstore_turns.5D|store_turns]],
[[InternalActionsWML#.5Bstore_unit.5D|store_unit]],
[[InternalActionsWML#.5Bstore_unit_defense.5D|store_unit_defense]],
[[InternalActionsWML#.5Bstore_unit_defense_on.5D|store_unit_defense_on]],
[[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]],
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]],
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]],
[[IntroWML|story]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]],
[[AchievementsWML#.5Bsub_achievement.5D|sub_achievement]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]],
[[InternalActionsWML#.5Bsync_variable.5D|sync_variable]];
|-
|''T:''
[[DirectActionsWML#.5Btunnel.5D|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
teleport ([[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|ability]], [[DirectActionsWML#.5Bteleport.5D|action]]),
[[AnimationWML#short-teleport|teleport_anim]],
[[DirectActionsWML#.5Bterrain.5D|terrain]],
[[UnitsWML#.5Bterrain_defaults.5D|terrain_defaults]],
[[TerrainGraphicsWML|terrain_graphics]],
[[TerrainMaskWML|terrain_mask]],
[[TerrainWML|terrain_type]],
[[ScenarioWML#The_.5Btest.5D_tag|test]],
[[InterfaceActionsWML#.5Btest_condition.5D|test_condition]],
[[TestWML#The_.5Btest_do_attack_by_id.5D_tag|test_do_attack_by_id]],
[[InterfaceActionsWML#message-text_input|text_input]],
[[GettextForWesnothDevelopers#The_textdomain_tag|textdomain]],
[[ThemeWML|theme]],
[[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML#The_.5Btile.5D_subtag|tile]],
[[TimeWML|time]],
[[DirectActionsWML#.5Btime_area.5D|time_area]],
[[HelpWML#topic|topic]],
[[HelpWML#toplevel|toplevel]],
[[UnitsWML#.5Btrait.5D|trait]],
[[DirectActionsWML#.5Btransform_unit.5D|transform_unit]],
[[InternalActionsWML#.5Bfind_path.5D|traveler]],
[[ConditionalActionsWML#.5Btrue.5D|true]],
[[DirectActionsWML#.5Btunnel.5D|tunnel]];
|-
|''U:''
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]],
unit ([[DirectActionsWML#.5Bunit.5D|action]], [[SingleUnitWML|scenario]]),
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]],
[[UnitTypeWML|unit_type]],
[[InternalActionsWML#.5Bunit_worth.5D|unit_worth]],
[[UnitsWML|units]],
[[InterfaceActionsWML#.5Bunlock_view.5D|unlock_view]],
[[DirectActionsWML#.5Bunpetrify.5D|unpetrify]],
[[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]],
[[InternalActionsWML#.5Bunsynced.5D|unsynced]];
|-
| ''V:''
[[InternalActionsWML#set_variables-value|value]],
[[ConditionalActionsWML#.5Bvariable.5D|variable]],
[[VariablesWML#The_.5Bvariables.5D_tag|variables]],
[[TerrainGraphicsWML#variant|variant]],
[[UnitTypeWML#variation|variation]],
[[AnimationWML#short-victory|victory_anim]],
[[SideWML#village|village]],
[[UnitsWML#vision_costs|vision_costs]],
[[InterfaceActionsWML#.5Bvolume.5D|volume]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]],
[[SchemaWML|wml_schema]];
|-
| ''Z:''
[[InterfaceActionsWML#.5Bzoom.5D|zoom]];
|}<includeonly>[[Category:WML Reference]]</includeonly><noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the [[ReferenceWML|WML reference]] pages.</noinclude>

InterfaceActionsWML

2025-07-06T12:14:08Z

Laela: /* [message] */ second_image https://github.com/wesnoth/wesnoth/commit/cb63cd3778b870cd51c058fabaacc28db8b99e54

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

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

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

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

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

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). [message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

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

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

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

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

<nowiki>You are victorious!</nowiki>

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

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

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

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

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

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

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

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

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

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item. All menus will be sorted lexicographically by the id string. The ordering is underscores, digits, and finally letters.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item, defaults to "buttons/WML-custom.png"
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

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

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

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

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

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

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

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

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

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

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

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

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

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

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

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

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

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

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

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

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

=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

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

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

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music] ===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax

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

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

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

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

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

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit
* '''object_id''': object id to use, defaults to the '''image''' key with an "overlay_" prefix; this allows using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']]
* '''duration''': object duration

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

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

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

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

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

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

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

The meanings of the deprecation levels are as follows:

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

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

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. WML wrapper of [[LuaAPI/wesnoth#wesnoth.log]], see the link for more description.
* '''message''': the message to show.
* '''to_chat''': controls whether message is visible in chat, though logger=wml means message is visible anyways. Default ''no''.
* '''logger''': one of '''info''', '''debug''', '''warning''', '''error''', '''wml'''. Default ''info''.

=== [test_condition] ===

{{DevFeature1.13|2}}

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

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

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

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

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

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

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

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

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

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

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

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

LuaAPI/wesnoth

2025-06-22T09:24:16Z

Laela: /* wesnoth.current */ user_is_replaying

<div class="tright"> __TOC__ </div>

The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.

== Functions ==

=== wesnoth.dofile ===

* '''wesnoth.dofile'''(''file_path'', [...]) → ...

Loads and executes a file. The rules for locating the files are the same as for WML files, except that they require a ''.lua'' extension instead of ''.cfg.'' Any extra parameters to '''dofile''' are forwarded to the script (which can access them via the special <tt>...</tt> variable), and '''dofile''' returns all the values returned by the script.

=== wesnoth.require ===

* '''wesnoth.require'''(''module'') → ''module_contents''

Returns the contents of the specified module, loading it if necessary. The module can either be a simple name or a file path similar to that used by '''wesnoth.dofile'''. In addition, the ''.lua'' extension will automatically be appended if necessary. The module script is invoked with no arguments, and '''wesnoth.require''' then passes back its first return value, discarding any additional ones. If the module is a directory, then all lua files are loaded, and a table containing the resulting modules is returned, with the keys being the filenames minus the ''.lua'' extension.

'''wesnoth.require''' returns nil on failure, for example if it could not locate the module. If it did locate the module, but the module did not return anything (or returned nil), then '''wesnoth.require''' returns an empty table with a metatable that raises an error on any attempt to access it.

=== wesnoth.textdomain ===

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

Returns a callable userdata that can be used to construct translatable strings. A typical use is:

<syntaxhighlight lang=lua>
local _ = wesnoth.textdomain "example"
wesnoth.alert(_ "This is an example translated string!")
</syntaxhighlight>

The full syntax for using the result of this function is:

* ''textdomain_constructor''(''string'', [''string_plural'', ''number'']) → ''translatable_string''

By passing the optional arguments, you can vary the string based on a number that will be substituted into it. As with all Lua functions, the parentheses are optional when passing a single string argument, as in the above example. This plural syntax returns a form of the string that's grammatically suitable for the indicated number, but doesn't actually substitute the number in – you need to do that yourself with either '''string.format''' or '''stringx.vformat'''.

The returned translatable string can be treated in many ways like a regular string. Translatable strings can be compared with other translatable strings or concatenated with each other or with regular strings or integers. The length operator also works, though it should be noted that its value may change if the language is changed. If you need to pass a translatable string to a function that doesn't understand them, it can be converted to a regular string with tostring.

=== wesnoth.log ===

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

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.

''logger'' is the log level.

In any context, ''logger'' can be the standard log levels of '''info''', '''debug''', '''warning''', or '''error'''. Various abbreviations of the standard four are also recognised. The default logger is '''info'''.

In the game context, you can also set the ''logger'' to '''wml'''. The '''wml''' log level 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 logdomain to enable these logs depends on the context. In the game context, they are written to the '''wml''' logdomain. In other contexts, the logdomain is '''scripting/lua/user'''.

=== wesnoth.as_text ===

{{DevFeature1.15|10}}

* {{LuaGameOnly}} '''wesnoth.as_text'''(''value1'', ''value2'', ...)

Accept one or more values as arguments and returns them as a string. This is intended for use as an easy way to view the contents of lua tables. Using the returned string for any other purpose is not supported.

{{DevFeature1.17|0}} This is now available in all contexts.

=== wesnoth.simulate_combat ===

* {{LuaGameOnly}} '''wesnoth.simulate_combat'''(''attacker'', [''attacker_weapon_index''], ''defender'', [''defender_weapon_index'']) → ''attacker stats evaluation'', ''defender stats evaluation'', ''attacker weapon evaluation'', ''defender weapon evaluation''

Computes the hitpoint distribution and status chance after a combat between two units. The first unit is the attacker. The attacker does not have to be on the map, but its location should be meaningful - that is, it can be a private-to-Lua clone of a unit with the '''x''' and '''y''' values changed, but whatever it is it has to have '''x''' and '''y''' values that allow attacking the defender (with '''max_range''' of the attack set appropriately it's possible to simulate attacking non-adjacent units). The second unit is the defender; it has to be on the map.

Optional integers can be passed after each unit to select a particular weapon, otherwise the "best" one is selected. When giving the weapon, the parameter is the weapon number (integer, starting at 1) and not the attack definition.

The function returns four tables describing the evaluation of the combat. The first two contain an evaluation of the combatant's stats over the course of the fight, while the second two contains more detailed information on their weapons.

The stats evaluation tables contain the following keys:

* ''stats''.'''poisoned''' → ''probability''
* ''stats''.'''slowed''' → ''probability''
* ''stats''.'''untouched''' → ''probability''

The probability that the unit will be poisoned or slowed, or that it will survive with no damage taken. (A scenario where the unit's hitpoints increase counts as untouched.)

* ''stats''.'''average_hp''' → ''number''

The expected value of the unit's hitpoints after the fight.

* ''stats''.'''hp_chance''' → ''mapping of hp to probability''

The probability that the unit's hitpoints will be at a specific value after the fight. Though it looks almost like an array, it begins at index 0 unlike a typical Lua array. Thus, it's better understood as an associated mapping from the resulting hitpoints value to the probability of ending the combat with that value. Therefore, the value at index 0 represents the chance that the unit will die.

The weapon evaluation tables contain the following keys:

{| class="wikitable"
!Key !!Description
|-
|attack_num
| DEPRECATED (use '''number'''). Attack number (0 based, -1 for no attack).
|-
|chance_to_hit
|Effective chance to hit as a percentage (all factors accounted for).
|-
|damage
|Effective damage of the weapon (all factors accounted for).
|-
|drains
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|drains]] opponent when it hits.
|-
|drain_constant
|Base HP drained regardless of damage dealt.
|-
|drain_percent
|Percentage of damage recovered as health.
|-
|firststrike
|Attack has [[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]] special.
|-
|name
|Name (not description) of the attack.
|-
|number
|Attack number (1 based, 0 for no attack).
|-
|num_blows
|Effective number of blows (takes [[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]] into account).
|-
|petrifies
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]] opponent when it hits.
|-
|plagues
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|turns opponent into a zombie]] when fatal.
|-
|plague_type
|The [[AbilitiesWML#Extra_keys_used_by_the_.5Bplague.5D_special|plague type]] used by the attack, if any.
|-
|poisons
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|poisons]] opponent when it hits.
|-
|rounds
|[[AbilitiesWML#The_.5Bspecials.5D_tag|Berserk]] special can force us to fight more than one round.
|-
|slows
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|slows]] opponent when it hits.
|}

<syntaxhighlight lang='lua'>
local function display_stats(n, t)
wesnoth.interface.add_chat_message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def, def_weapon)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

local att_stats, def_stats, att_weapon, def_weapon = wesnoth.simulate_combat(attacker, att_weapon_number, defender)
wesnoth.interface.add_chat_message(string.format(
"The attack %s should be countered with %s, which does %d damage, has %d%% chance to hit and forces %d attack rounds due to its berserk ability.",
att_weapon.name, def_weapon.name or "no weapon", def_weapon.damage, def_weapon.chance_to_hit, def_weapon.rounds))
</syntaxhighlight>

=== wesnoth.name_generator ===

* '''wesnoth.name_generator'''('''"markov"''', ''definition'', [''chain_size'', [''max_length'']]) → ''generator function''
* '''wesnoth.name_generator'''('''"cfg"''', ''definition'') → ''generator function''
* ''generator function''() → ''random name''

Constructs a name generator for use in generating names using either the Markov chain algorithm used in older versions of Wesnoth or the context-free grammar generator used since 1.13.5. The type parameter indicates which algorithm to use (either markov or cfg). The definition can be a string, just like it would be in a config file, or it can be formatted as a table. Additional parameters may be passed, depending on the type of generator. The function returns a callable userdata, which will return a new name each time it is called (with no parameters).

* '''Markov chain''': A Markov chain generator works by analyzing a list of input names and noticing tendencies in the way the letters are strung together. It can then apply those tendencies to produce new similar names that were not in the original list. Longer lists give better results. The definition is a list of names, formatted either as a comma-separated string or as an array-like table. The Markov generator can take two additional parameters.
** ''chain_size'': A value greater than 1 for the ''chain_size'' causes the analyzer to consider the words in chunks, which is similar to analyzing them syllable by syllable instead of letter by letter. The default chain size is 2, meaning that the analyzer treats words as consisting of 2-character syllables.
** ''max_length'': Places a cap on the total length of the name. The default value is 12 characters.
<syntaxhighlight lang=lua>
local markov_names = wesnoth.name_generator('markov', {'Kaasa', 'Kayya', 'Keyya', 'Kiira', 'Korra'}, 1)
print(markov_names(), markov_names(), markov_names())
</syntaxhighlight>
* '''Context-free grammar''': A [[context-free grammar]] is a way of specifying how strings can be constructed. The definition may be specified as a multi-line string, just as described in the preceding link, or it can be formatted as a table where the keys are non-terminals and the values are what they expand to. The expansion of each non-terminal can be formatted either as a |-separated list as described in the preceding link, or as an array-like table. (Mixing the two forms is permissible too.) The context-free generator has no additional parameters.
<syntaxhighlight lang=lua>
local cfg_names = wesnoth.name_generator('cfg', {
main = {'{prefix}{suffix}', '{prefix}{centre}{suffix}'},
prefix = 'Kaa|Ka|Ke|Kuu|Ko',
suffix = 'sa|yya|ra|rra',
centre = 'err|aash|eez|azz'
})
print(cfg_names(), cfg_names(), cfg_names())
</syntaxhighlight>

'''Note''': If you want to generate a name using any of the default generators, you can use the predefined generators in the [[LuaAPI/types#race|race]] instead of constructing one with this function.

=== wesnoth.compile_formula ===

* '''wesnoth.compile_formula'''(''formula'') → ''compiled formula''

Compiles a [[Wesnoth Formula Language]] formula into a Lua callable userdata. A compiled formula can be converted back to valid code using the built-in <code>tostring</code> function.

=== wesnoth.eval_formula ===

* '''wesnoth.eval_formula'''(''formula'', [''variables'']) → ''result''
* ''compiled formula''([''variables'']) → ''result''

Evaluate a [[Wesnoth Formula Language]] formula and return the result it computed (which can be '''nil''').

The passed in variables can be an arbitrary Lua table, which defines variables available to the formula. Unlike with WML tables, there is no restriction on the format of this table. The formula can access the variables as a list using the special WFL variable '''__list''', or as a map using the special WFL variable '''__map'''. Directly accessing keys on the table is also possible.

It is also possible to pass a unit proxy as the variables, which evaluates the formula in that unit's context just as if it had been used in a [[StandardUnitFilter]].

When calling '''wesnoth.eval_formula''', the first argument may either be an already-compiled formula or a string, in which case it will be automatically compiled on the fly.

<syntaxhighlight lang=lua>
local f = wesnoth.compile_formula('if(x > y, x - y, x + y)')

print(f{x=1,y=2}) -- prints 3.0
print(f{x=1,y=3}) -- prints 4.0
print(f{x=2,y=3}) -- prints 5.0
print(f{x=1,y=1}) -- prints 2.0
print(f{x=3,y=1}) -- prints 2.0
print(f{x=3,y=2}) -- prints 1.0
</syntaxhighlight>

=== wesnoth.version ===

* '''wesnoth.version'''(''version string'') → ''version''
* '''wesnoth.version'''(''major'', [''minor'', [''patch'']], [''suffix'')) → ''version''

Creates a version object, either by parsing a string or by building it from its component parts. The resulting version object can be compared with other version objects using the standard Lua comparison operators, which follows the same rules as the [[PreprocessorRef#.23ifver_and_.23ifnver|#ifver]] preprocessor statement. It can also be decomposed by accessing the following keys on the object:

* ''integer'': Grab any integer version component by index. A non-canonical version may have more than three components.
* '''major''': The major version number (index 1).
* '''minor''': The minor version number (index 2).
* '''revision''': The patch revision number (index 3).
* '''is_canonical''': True if the version has at most three components (plus an optional suffix).
* '''sep''': The character that separates the version components from the suffix (usually either + or nil).
* '''special''': The version suffix, for example the "dev" in "1.15.14+dev".

The version can be converted to a string using the built-in '''tostring''' function.

<syntaxhighlight lang=lua>
local function version_is_sufficient(required)
return wesnoth.current_version() >= required
end
local required = wesnoth.version "1.9.6"
if not version_is_sufficient(required) then
gui.alert(string.format("Your BfW version is insufficient, please get BfW %s or greater!", tostring(required)))
end
</syntaxhighlight>

=== wesnoth.current_version ===

* '''wesnoth.current_version'''() → ''current version''

Returns the current version of Wesnoth as a version object.

=== wesnoth.ms_since_init ===

* '''wesnoth.ms_since_init'''() → ''milliseconds''

This function returns the amount of milliseconds that have passed since Wesnoth started up the current session. Its only use is to track the passage of real time.

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

=== wesnoth.deprecated_message ===

* '''wesnoth.deprecated_message'''(''element_name'', ''level'', ''version'', ''detail_message'')

Displays a deprecation warning in the Lua console. The level is an integer from 1 to 4 inclusive (see [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|deprecation levels]]), and the version can be left nil for levels 1 and 4. Otherwise it must be a version ''string'' (not a version object from [[#wesnoth.version|wesnoth.version]]).

=== wesnoth.deprecate_api ===

* '''wesnoth.deprecate_api'''(''original_name'', ''new_name'', ''level'', ''version'', ''element'', ''detail_message'') → ''deprecated wrapper''

Creates a deprecated wrapper for a function or table. A deprecated function will raise the deprecated message the first time it's called, and then suppress it thereafter. A deprecated table will raise the deprecated message the first time a key is read or assigned, and then suppress it thereafter.

The ''element'' is the function or table to wrap. It can be the original function or the new function (which may happen if the function was renamed without any interface changes), or a wrapper function that calls the new function while providing the interface of the old function. The ''level'' and ''version'' are as in [[#wesnoth.deprecated_message|wesnoth.deprecated_message]].

If ''level'' is 4, then the ''element'' is ignored (you can pass '''nil''') and a generic deprecated wrapper is returned that does nothing but raises the deprecated message the first time you call it, assign a key, or read a key, and suppresses it thereafter. This is intended for a function that was removed without deprecation, to leave behind a more informative message if someone still attempts to use it.

If Wesnoth is run with the <tt>--strict-lua</tt> command-line option, this function will return '''nil''' instead of the deprecated wrapper. Since the normal use-case of this function is to assign the deprecated wrapper to the original name, this has the effect of erasing any deprecated functions from the API.

The result of this function always contains a '''__deprecated''' attribute set to true, which can allow identifying if something is deprecated.

=== wesnoth.type ===

{{DevFeature1.17|?}}

* '''wesnoth.type'''(''value'') → ''type name''

Returns a string describing the value's type. This is the same as the built-in type function, except that it returns a more specific string in the case of userdata or tables, based on the metatable. For example, it would return 'unit' if called on a unit.

=== wesnoth.named_tuple ===

{{DevFeature1.17|?}}

* '''wesnoth.named_tuple'''(''array'', ''names'') → ''named tuple''

Decorates a numeric based array so that the indices can be accessed by name instead of by index. This function is used internally for a number of things, most notably map locations and WML tags. Most end-users will not need to use it, but it could be useful if you wish to build a Lua API that returns locations (or similar data) in the engine-standard format.

For example:

<syntaxhighlight lang=lua>
local t = wesnoth.named_tuple({42,21,36}, {'x', 'y', 'z'})

print(t[1]) -- prints 42
print(t[2]) -- prints 21
print(t[3]) -- prints 36
print(t.x) -- prints 42
print(t.y) -- prints 21
print(t.z) -- prints 36
</syntaxhighlight>

=== wesnoth.get_language ===

* '''wesnoth.get_language'''() → ''string''

Gets the language the UI is currently set to. Note that this may return an empty string if using the system default language.

=== wesnoth.print_attributes ===

* '''wesnoth.print_attributes'''(''object'', [''function''])

Prints out a list of attributes that can be accessed on the object, excluding deprecated functionality. The function defaults to '''print''', and receives a formatted line usually containing multiple attributes. They are annotated by type – &fnof; for a function, &dagger; for a table, ! if there was an error attempting to determine the type (which includes write-only attributes). Other types are unannotated.

For tables, by default this iterates the table using '''pairs''' to discover the attributes available, walking the metatable hierarchy if there is an '''__index''' table and filtering out anything that contains a '''__deprecated''' attribute set to '''true'''. However, if finds a function as the '''__index''', and the table's metatable also has a member '''__dir''', it will be used instead. The '''__dir''' can either be an array of strings, or a function that returns an array of strings. It will automatically be sorted and have any duplicates filtered out.

For custom objects defined by the engine, there is special handling so that this function shows the correct result. For example, if used on a GUI2 widget object, it will show the attributes available for that type of widget, as well as the IDs of any sub-widgets that can be accessed by name.

In the Lua console only, this function can also be referenced by a shorter alias, '''dir'''.

== Hooks ==

=== wesnoth.persistent_tags ===

* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''read''' ↔ '''function'''(''wml content'')
* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''write''' ↔ '''function'''(''add_tag_function'')

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 to 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.wml_actions ===

* {{LuaGameOnly}} '''wesnoth.wml_actions'''.''action'' ↔ '''function'''(''wml parameters table'')

This is a hook table that exposes and defines WML actions. Each function in this table corresponds to a single ActionWML tag, allowing you to invoke tags, define custom tags, and even modify the behavior of built-in tags. The single argument to these functions is a WML table, the content of the tag.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or wml.error "[freeze_unit] expects an id= attribute."
local unit = wesnoth.units.get(unit_id)
if unit then unit.moves = 0 end
wesnoth.units.modify({ 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)
local modified_cfg = setmetatable({}, {__index = cfg})
modified_cfg.size = (cfg.size or 12) + 10
wesnoth.wml_actions.print(modified_cfg)
end
</syntaxhighlight>

An action handler should be able to handle being called with either a WML table or a WML vconfig userdata. It is recommended to pass the argument through ''wml.tovconfig'' before doing anything with it, both in the action's definition and when calling it directly (in case its definition did not do that). The engine always passes a vconfig when calling a WML action.

=== wesnoth.wml_conditionals ===

* {{LuaGameOnly}} '''wesnoth.wml_conditionals'''.''action'' ↔ '''function'''(''wml parameters table'') → ''boolean result''

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

Use it like this:

<syntaxhighlight lang=lua>
function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or wml.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>

Note that the basic logic tags of ConditionalWML (true, false, and, or, not) do not pass through this table and cannot be overridden.

=== wesnoth.effects ===

* {{LuaGameOnly}} '''wesnoth.effects'''.''name'' ↔ '''function'''(''unit'', ''wml table'')
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ ''description''
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ '''function'''(''unit'', ''wml table'') → ''description''

This table contains the implementation of [[EffectWML|[effect]]]s. Each value is a callable value that takes a unit and the effect config. It can be a function or a callable table. If it is a callable table, its metatable may have a '''__descr''' field which is either a string or a function. Built-in effects are present in this table, and you may register your own custom effects too.

<syntaxhighlight lang='lua'>
function wesnoth.effects.min_resistance(u, cfg)
local resistance_new = {}
local resistance_old = wml.parsed(wml.get_child(cfg, "resistance"))
for k,v in pairs(resistance_old) do
if type(k) == "string" and type(v) == "number" and u:resistance_to(k) >= v then
resistance_new[k] = v
end
end
wesnoth.effects.resistance(u, {
apply_to = "resistance",
replace = true,
T.resistance (resistance_new),
})
end
</syntaxhighlight>

The code above adds a new <code>min_resistance</code> effect that will set the resistances to specific values if they are currently below that value. It can then be used like this (for example, in [[DirectActionsWML#.5Bobject.5D|[object]]]):

<syntaxhighlight lang='wml'>
[effect]
apply_to=min_resistance
[resistance]
cold=50
[/resistance]
[/effect]
</syntaxhighlight>

Note that in order work properly, effects must be registered before any units are created. This means it must be placed into a global or scenario level [lua] tag. In particular, the preload event is too late.

You can also specify description modifiers, which will be used if a custom effect is placed in a <code>[trait]</code> tag. Instead of setting a function as the effect, you set a table with a <code>__call</code> metafunction which does what the function would have done. The table can then have an additional <code>__descr</code> metafunction which updates descriptions as necessary. The built-in effects all use this structure. This metafunction takes the same arguments as the regular effect function, but should not modify the unit. Instead, it returns a string to be appended to the trait's effect description.

=== wesnoth.micro_ais ===

* {{LuaGameOnly}} '''wesnoth.micro_ais'''.''ai_name'' ↔ ''function''(''cfg'') → ''required'', ''optional'', ''ca_params''

Registers a new [[Micro_AIs#Custom_Micro_AIs|MicroAI]] with '''ai_type'''=''ai_name''. The function will be called by the [micro_ai] tag to set up the AI. See the link for more details on how this works.

=== wesnoth.custom_synced_commands ===

* {{LuaGameOnly}} '''wesnoth.custom_synced_commands'''.''command_name'' ↔ ''function''(''cfg'')

Registers a custom synced command, which can be invoked by AI to enable unusual behaviour. The command can do basically anything, and is guaranteed to run on all clients. The WML table passed to the callback is the same table passed to [[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]].

== Data ==

Access to most of the game data is available via various tables in the <tt>wesnoth</tt> module.

=== wesnoth.colors ===

{{DevFeature1.15|4}}

* {{LuaGameOnly}} '''wesnoth.colors'''.''color_name'' → ''color info''

Access defined [[GameConfigWML#Color_Palettes|color ranges]]. This can be used to translate the color name available from '''wesnoth.sides[n].color''' to RGB values.

Each color info table contains the following keys:

* '''mid''' - average shade for recoloring with the team color
* '''min''' - minimum shade for recoloring with the team color (this is likely to be black)
* '''max''' - maximum shade for recoloring with the team color (this is likely to be almost white)
* '''minimap''' - representative color to use on the mini-map
* '''pango_color''' - {{DevFeature1.15|13}} a hex string such as '''#ff0000''' suitable for use in formatted text

Each of '''mid''', '''min''', '''max''' and '''minimap''' have the following keys:

* '''r''' - red component of that color
* '''g''' - green component of that color
* '''b''' - blue component of that color
* '''a''' - alpha component of that color (probably fully opaque)

Reference usage in mainline: see data/multiplayer/eras.lua

=== wesnoth.current ===

Contains various information about the current game and event state.

* {{LuaGameOnly}} '''wesnoth.current.side''' → ''side number''

The number of the currently active side.

* {{LuaGameOnly}} '''wesnoth.current.turn''' → ''turn number''

The current turn number.

* {{LuaGameOnly}} '''wesnoth.current.synced_state''' → ''state''

Allows you to determine whether the current code runs in a synced context. Returns one of the following strings:

:* '''synced''' - The current code runs on all mp clients. This is the normal context, in which all gamestate changing actions should take place.
:* '''unsynced''' - The current code runs only on the local machine, so changing the gamestate here will cause out-of-sync errors. For example, during '''select''' events or during the calculation of a [[LuaAPI/wesnoth/interface#wesnoth.interface.game_display|game_display]] hook. Typical things to do here are UI related things, or entering the synced state via '''[do_command]'''.
:* '''local_choice''' - The current code was invoked by [[#wesnoth.synchronize_choice|synchronize_choice]] and runs only on one local client to calculate the return value for the choice. You cannot enter the synced context with '''[do_command]''' now.
:* '''preload''' - We are currently running a preload event or an even earlier event. This behaves similar to '''local_choice'''.

* {{LuaGameOnly}} '''wesnoth.current.user_can_invoke_commands''' → ''boolean''

Indicates whether the player is currently able to take actions in the game.

* {{LuaGameOnly}} '''wesnoth.current.user_is_replaying''' → ''boolean'' {{DevFeature1.19|7}}

Indicates whether the player is currently in replay mode.

* {{LuaGameOnly}} '''wesnoth.current.map''' → ''map userdata''

The current active game map. See [[LuaAPI/types/map]] and [[LuaAPI/wesnoth/map]] for information on how this data can be used.

* {{LuaGameOnly}} '''wesnoth.current.schedule''' → ''schedule userdata''

The current global time schedule. This is a special object with the following properties:

:* #''schedule''
:The Lua length operator will return the number of turns in the schedule.

:* ''schedule''[''index''] ↔ ''time of day info''
:Get the information for a particular time of day, or replace it with new info.

:* ''schedule''.'''time_of_day''' ↔ ''id''
:Get the ID of the current active time of day, or switch to a new one. If the time of day occurs more than once in the schedule, the time will be set to the first occurrence.

:* ''schedule''.'''liminal_bonus''' ↔ ''bonus''
:Get the maximum bonus for liminal units in the current schedule. You can also override the default by assigning a different value, or revert to the default by assigning nil.

* {{LuaGameOnly}} '''wesnoth.current.event_context''' → ''WML table''

Contains information on the current active event. Returns a table with the following keys:

:* '''name''' - The event name. This is the actual event that fired, not the name in the [event] tag, so it never contains commas or variables.
:* '''id''' - The event's unique ID, if it has one.
:* '''weapon''' - The first weapon relevant to the event, if any.
:* '''second_weapon''' - The second weapon relevant to the event, if any.
:* '''damage_inflicted''' - The damage inflicted in the event, if applicable.
:* '''x1''', '''y1''' - The first location relevant to the event, if any.
:* '''x2''', '''y2''' - The second location relevant to the event, if any.
:* '''unit_x''', '''unit_y''' - The location of the first unit relevant to the event, if any. This is the same as '''x1''', '''y1''' in most cases. Currently the only exceptions are enter and exit hex events.
:* '''data''' - {{DevFeature1.17|6}} The event data. Can contain anything at all if the event was fired by [[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]]. In a village capture event, '''owner_side''' will contain the former owner of the village.

=== wesnoth.game_config ===

Contains static global information about the game. Some of this information can also be modified on the fly, but only in the game context, not in the plugin or map generator context.

* '''wesnoth.game_config.base_income''' ↔ ''integer''
* '''wesnoth.game_config.village_income''' ↔ ''integer''
* '''wesnoth.game_config.village_support''' ↔ ''integer''
* '''wesnoth.game_config.poison_amount''' ↔ ''integer''
* '''wesnoth.game_config.rest_heal_amount''' ↔ ''integer'
* '''wesnoth.game_config.recall_cost''' ↔ ''integer''
* '''wesnoth.game_config.combat_experience''' ↔ ''integer''
* '''wesnoth.game_config.kill_experience''' ↔ ''integer''

Values of various game settings.

* '''wesnoth.game_config.global_traits'''[''trait id''] →

A table with named fields (trait id strings) holding the wml tables defining the traits. This contains all global traits the engine knows about, but race-specific traits are not included. The known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].

<syntaxhighlight lang=lua>
print(wesnoth.game_config.global_traits.strong.male_name)
</syntaxhighlight>

* {{LuaGameOnly}} '''wesnoth.game_config.do_healing''' ↔ ''boolean''

Whether healing will occur at the beginning of each side's turn.

* {{LuaGameOnly}} '''wesnoth.game_config.theme''' ↔ ''theme id''

The currently active in-game theme.

* '''wesnoth.game_config.debug''' → ''boolean''

Whether debug mode is currently active. Debug mode is activated by the --debug command-line parameter or the :debug in-game command.

* '''wesnoth.game_config.debug_lua''' → ''boolean''

Whether Lua debug is enabled. Lua debug is activated by the --debug-lua command-line parameter. This does not seem to do anything by default.

* '''wesnoth.game_config.mp_debug''' → ''boolean''

Whether MP debug is enabled. MP debug is activated in the same way as debug mode, but is only active in multiplayer games.

* '''wesnoth.game_config.strict_lua''' → ''boolean''

Whether strict Lua mode is enabled. Strict Lua mode is activated by the --strict-lua command-line parameter and causes all deprecated Lua APIs to be completely removed from the engine.

* {{DevFeature1.19|4}} '''wesnoth.game_config.palettes'''.''palette'' → ''list of colors''

Returns the color palette with the given name, as defined by a '''[color_palette]''' tag in the [[GameConfigWML#Color_Palettes|game config]].

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale''' → ''list of colors''

Returns the gradient used for health bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale_text''' → ''list of colors''

Returns the gradient used for health numbers.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale''' → ''list of colors''

Returns the gradient used for experience bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale_text''' → ''list of colors''

Returns the gradient used for experience numbers.

=== wesnoth.races ===

* {{LuaGameOnly}} '''wesnoth.races'''.''id'' → ''race info''

Access defined [[UnitsWML#.5Brace.5D|races]]. Returns a [[LuaAPI/types#Race|race userdata]].

=== wesnoth.scenario ===

Contains information about the current scenario

* {{LuaGameOnly}} '''wesnoth.scenario.turns''' ↔ ''turn limit''

The current turn limit of the scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.next''' ↔ ''scenario id''

The ID of the scenario to transition to when this scenario ends.

* {{LuaGameOnly}} '''wesnoth.scenario.id''' → ''scenario id''

The ID of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.name''' →

The name of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.defeat_music''' ↔ ''list of music tracks''

The music to play if you lose this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.victory_music''' ↔ ''list of music tracks''

The music to play if you win this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.show_credits''' ↔ ''boolean''

Whether credits should be shown when this scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text''' ↔ ''text''

The end text to show when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text_duration''' ↔ ''duration''

How long to show the end text for when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.difficulty''' → ''difficult''

The difficulty level this scenario is being played on.

* {{LuaGameOnly}} '''wesnoth.scenario.type''' → ''tag name''

The type of this scenario. One of the strings '''scenario''', '''multiplayer''', or '''test'''.

* {{LuaGameOnly}} '''wesnoth.scenario.era''' → ''era tag''

The [era] tag active in this scenario. Accessing this will throw an error in single-player games. This exists only for players which have the era installed, so for an era with ''require_era=yes'' it is safe to use.

* {{LuaGameOnly}} '''wesnoth.scenario.campaign''' → ''campaign tag''

The [campaign] tag active in this scenario. Accessing this will throw an error in multiplayer or test games, so be sure to check '''wesnoth.scenario.type''' first in generic code.

* {{LuaGameOnly}} '''wesnoth.scenario.resources''' → ''list of resource tags''

A list of [resource] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.modifications''' → ''list of modification tags''

A list of [modification] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.mp_settings''' → ''table''

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. This allows accessing basically everything that can be set in the create game screen. The following keys exist in the returned table:

* '''active_mods''' - A list of all active modification IDs
* '''hash''' - A hash of mp data
* '''mp_campaign''' - Name of mp campaign
* '''mp_scenario''' - ID of this mp scenario
* '''mp_scenario_name''' - Name of this mp scenario
* '''scenario''' - MP lobby title
* '''difficulty_define''' - The campaign difficulty string for an mp campaign
* '''mp_village_gold'''
* '''mp_village_support'''
* '''mp_num_turns'''
* '''mp_era''' - The id of the chosen era
* '''mp_eras''' - A list of all era ids
* '''mp_fog'''
* '''mp_shroud'''
* '''mp_random_start_time'''
* '''experience_modifier'''
* '''mp_use_map_settings'''
* '''mp_countdown''' - Whether the timer is enabled
* '''mp_countdown_action_bonus'''
* '''mp_countdown_init_time'''
* '''mp_countdown_reservoir_time'''
* '''mp_countdown_turn_bonus'''
* '''observer'''
* '''shuffle_sides'''
* '''savegame''' - Whether this is a reloaded game
* '''side_users''' - List of how sides are assigned to users (at game start)

=== wesnoth.terrain_types ===

{{DevFeature1.15|12}}

* {{LuaGameOnly}} '''wesnoth.terrain_types'''[''code''] → ''terrain info''

Access defined [[TerrainWML|terrain types]] by their terrain code. Returns a table with the following keys:

* '''id'''
* '''name'''
* '''editor_name'''
* '''description'''
* '''icon'''
* '''editor_image'''
* '''light'''
* '''village'''
* '''castle'''
* '''keep'''
* '''healing'''
* '''mvt_alias''' {{DevFeature1.19|10}}
* '''def_alias''' {{DevFeature1.19|10}}

=== wesnoth.unit_types ===

* {{LuaGameOnly}} '''wesnoth.unit_types'''[''id''] → ''unit type info''

Access defined [[UnitTypeWML|unit types]] by their ID. Returns a [[LuaAPI/types#Unit_Type|unit type userdata]].

== Submodules ==

The <tt>wesnoth</tt> module also contains a number of submodules for working with particular aspects of the game.

=== wesnoth.audio ===

A [[LuaAPI/wesnoth/audio|submodule]] containing functions for playing music and sound effects.

=== wesnoth.achievements ===

A [[LuaAPI/wesnoth/achievements|submodule]] containing functions for working with in-game achievements.

=== wesnoth.game_events ===

A [[LuaAPI/wesnoth/game_events|submodule]] containing functions for working with event handlers.

=== wesnoth.map ===

{{DevFeature1.15|11}}

A [[LuaAPI/wesnoth/map|submodule]] containing functions for querying and manipulating the game map.

=== wesnoth.interface ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/interface|submodule]] containing functions pertaining to the in-game UI.

=== wesnoth.paths ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/paths|submodule]] containing functions related to pathfinding.

=== wesnoth.schedule ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/schedule|submodule]] containing functions to manipulate the time of day schedule.

=== wesnoth.sides ===

{{DevFeature1.15|3}}

A [[LuaAPI/wesnoth/sides|submodule]] containing functions for manipulating the sides of a scenario.

=== wesnoth.sync ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/sync|submodule]] containing functions to deal with multiplayer synchronization.

=== wesnoth.units ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/units|submodule]] containing functions to manipulate units on the map.

[[Category: Lua Reference]]

== Unsupported Functions ==

The following functions exist in the '''wesnoth''' module but are not intended to be used:

* wesnoth.allow_undo
* wesnoth.cancel_action
* wesnoth.clear_menu_item
* wesnoth.set_menu_item
* wesnoth.kernel_type
* wesnoth.log_replay
* wesnoth.print
* wesnoth.redraw
* wesnoth.add_known_unit
* wesnoth.get_era
* wesnoth.get_resource

Some of these have WML equivalents, so if you need the functionality you should call the WML action directly (via [[#wesnoth.wml_actions|wml_actions]] or [[LuaAPI/wml#wml.fire|wml.fire]]). Others are internal functionality used in core Lua scripts, which are not intended for general use. These functions ''may'' be removed or changed without warning or going through a deprecation cycle.

Examination of the '''wesnoth''' module will also reveal two additional subtables - the '''package''' table, which is where packages loaded by [[#wesnoth.require|wesnoth.require]] persist (meaning you can force '''wesnoth.require''' to reload a file by nulling out its entry in this table), and the '''experimental''' module, which contains functions that are available for use but without warranty - they may change without warning or going through a deprecation cycle. Use of both of these tables is unsupported.

EraWML

2025-06-21T08:02:59Z

Laela: auto_sort

{{WML Tags}}
== The [era] top level tag ==

This [[AddonsWML|addon module]] tag describes one era. An era is a set of teams to play in multiplayer.

In the multiplayer game creation screen, an era is chosen by the host by the 'Era' option button.

The following key/tags are recognized for '''[era]''', in addition to the common [[AddonsWML|addon module keys and tags]]:
* '''require_era''': whether clients are required to have this era installed beforehand to be allowed join a game using this era. Possible values 'yes' (the default) and 'no'.
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this era.
* '''disallow_scenario''': a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this era. Cannot be used in parallel with allow_scenario.
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this era regardless their dependencies.
* '''allow_modification''': same as allow_scenario, but for modifications.
* '''disallow_modification''': same as disallow_scenario, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
* '''force_modification''': a list of modification ids. The specified modifications must be enabled to play this era.
* '''hide_help''': {{DevFeature1.13|0}} whether this era should show up in the help browser or not. Default no.

== Defining Factions ==

Each faction in the era is defined by a '''[multiplayer_side]''' tag. This tag contains most of the same keys as a [side] tag (see [[SideWML]]). When a multiplayer game is played, then the [side] tag for the scenario is merged with the keys (currently, not tags) of the '''[multiplayer_side]''' tag of the faction which the side chose.

Each faction needs to specify its recruit list with the '''recruit''' key, which is described in [[SideWML]].

The following additional keys are unique to '''[multiplayer_side]''':

* '''id''': faction ID - must be unique to your era. No gameplay effect
* '''name''': a description that Wesnoth displays as the option selecting that faction. This key is used for sorting factions in era.
* '''image''': an image to display in the option. This image will use the team color.
* '''leader''': a list of unit types. Must be present. When this faction is chosen, the side can choose any of these unit types to be the side's leader (i.e. "Choose your Leader"). They will also have the option of having one of these types being chosen randomly.
* '''random_leader''': if this list of types is present, it would use this list to instead to choose a random leader. If not it would use '''leader'''
* '''random_faction''': default 'no'. If 'yes', then when this faction is chosen, another non random faction will be randomly chosen instead. The leader will also be chosen randomly. All random_faction=yes factions are sorted before other factions.
* '''choices''': Empty by default. If non-empty and the faction has '''random_faction=yes''', it is the list of the IDs of the non random factions that will be choosen randomly. If empty, any faction can be chosen.
* '''except''': Empty by default. If the faction has random_faction=yes, it is the list of the IDs of the non random factions that will not be choosen randomly.
* '''type''': the unit type of the default leader for the side. This must be present. 'random' is a valid value here and will cause a random leader choice by default. As of 1.16.2 at least this key has no effect and is not required to be present.
* '''terrain_liked''': an unseparated list of terrains (see [[TerrainCodesWML]]). On random maps, these terrains will determine which keep the side is assigned, attempting to put it near the listed terrains.
* '''description''': a short description of the faction, displayed in the help browser.
* '''auto_sort''': {{DevFeature1.19|13}} default 'yes'. If 'no', factions will be displayed in the order written in WML instead of sorted by name. In older versions there are workarounds like https://github.com/wesnoth/wesnoth/issues/3177.

== See Also ==

* [[ReferenceWML]]
* [[SideWML]]

[[Category: WML Reference]]

StandardUnitFilter

2025-06-09T18:48:59Z

Laela:

{{WML Tags}}

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

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

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

The term [[StandardUnitFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardUnitFilter]] needs to be included in a [filter] tag. But many tags take the [[StandardUnitFilter]] directly as an argument, like [[DirectActionsWML#.5Bkill.5D|[kill]]] and [[ConditionalActionsWML#.5Bhave_unit.5D|[have_unit]]] (which each accept a few additional keys of their own). See [[Special:WhatLinksHere/StandardUnitFilter]] for tags which can contain a StandardUnitFilter.

__TOC__

The following attributes and sub-tags are allowed:

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

== [[Wesnoth Formula Language]] ==

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

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

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

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

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

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

== Tutorial ==

* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]

== See Also ==

* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AbilitiesWML

2025-06-09T18:47:55Z

Laela: /* Common keys and tags for every weapon special */

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''' {{DevFeature1.19|10}}: if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'' or ''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'' or ''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. '''Replaces''' '''[filter_self]''' of normal weapon specials.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''' {{DevFeature1.19|10}}: if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

AbilitiesWML

2025-06-09T18:46:55Z

Laela: /* Common keys and tags for every ability */

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''' {{DevFeature1.19|10}}: if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'' or ''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'' or ''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. '''Replaces''' '''[filter_self]''' of normal weapon specials.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

DirectActionsWML

2025-04-02T17:55:47Z

Laela: /* [gold] */ side is not used anymore

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

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

The following tags are actions:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* [[StandardSideFilter]] sides to give the gold to. Default is all sides.

=== [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 [[VariablesWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their current value. 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).

Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''. Setting value, including empty string, of ''type'' acts as shortcut of ''experience="$this_unit.max_experience"''.

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

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

=== [petrify] ===

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

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

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

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

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

Removes an object from matching units.

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

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

Note that [remove_object] works the following way:

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

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

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

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the trait to be removed. See [[UnitsWML#.5Btrait.5D|[trait]]].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{DevFeature1.15|0}}
In a '''capture'''/'''moveto''' [event], interrupt the attack.

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

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

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount. When harming multiple units, the special variable '''$this_unit''' can be used to access the current unit being harmed. This obviously does not work inside the filters though, as they give '''$this_unit''' a different meaning.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': (default yes) If there is a harmer, experience will be attributed similar to regular combat. Can take list of values. When any value is provided, all unspecified experience types default to not giving experience. Supported values: {{DevFeature1.17|25}} until that version only experience=yes and experience=no are supported
** no - none of involved units get any experience (this value only works if it is the only value in list)
** kill - the harming unit receives experience based on level of harmed unit in attack which kills harmed unit
** attack - the harming unit receives experience based on level of harmed unit in attack which does not kill harmed unit, or in attack which kills harmed unit while kill experience is disabled
** defend - the unit being harmed receives experience based on level of harming unit in attack which does not kill harmed unit
** fight - short form of experience=attack,defend
** yes - short form of experience=kill,attack,defend
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

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

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

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

=== [remove_time_area] ===

{{DevFeature1.13|2}}

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

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

=== [replace_map] ===

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement. ('''NB''': due to https://github.com/wesnoth/wesnoth/issues/5757 this attribute is ignored in versions 1.16.*. The fix was delivered in 1.17.* but wasn't backported due to backward-compatibility requirements)

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

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

=== [do_command] ===

{{DevFeature1.13|0}}

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

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

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

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

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

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

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

=== [set_achievement] ===

{{DevFeature1.17|13}}

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

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

=== [set_sub_achievement] ===

{{DevFeature1.17|17}}

Sets the specified sub-achievement as completed.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

=== [progress_achievement] ===

{{DevFeature1.17|13}}

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

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

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

== See Also ==

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

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

LuaAPI/wesnoth

2025-03-23T17:26:08Z

Laela: /* wesnoth.terrain_types */

<div class="tright"> __TOC__ </div>

The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.

== Functions ==

=== wesnoth.dofile ===

* '''wesnoth.dofile'''(''file_path'', [...]) → ...

Loads and executes a file. The rules for locating the files are the same as for WML files, except that they require a ''.lua'' extension instead of ''.cfg.'' Any extra parameters to '''dofile''' are forwarded to the script (which can access them via the special <tt>...</tt> variable), and '''dofile''' returns all the values returned by the script.

=== wesnoth.require ===

* '''wesnoth.require'''(''module'') → ''module_contents''

Returns the contents of the specified module, loading it if necessary. The module can either be a simple name or a file path similar to that used by '''wesnoth.dofile'''. In addition, the ''.lua'' extension will automatically be appended if necessary. The module script is invoked with no arguments, and '''wesnoth.require''' then passes back its first return value, discarding any additional ones. If the module is a directory, then all lua files are loaded, and a table containing the resulting modules is returned, with the keys being the filenames minus the ''.lua'' extension.

'''wesnoth.require''' returns nil on failure, for example if it could not locate the module. If it did locate the module, but the module did not return anything (or returned nil), then '''wesnoth.require''' returns an empty table with a metatable that raises an error on any attempt to access it.

=== wesnoth.textdomain ===

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

Returns a callable userdata that can be used to construct translatable strings. A typical use is:

<syntaxhighlight lang=lua>
local _ = wesnoth.textdomain "example"
wesnoth.alert(_ "This is an example translated string!")
</syntaxhighlight>

The full syntax for using the result of this function is:

* ''textdomain_constructor''(''string'', [''string_plural'', ''number'']) → ''translatable_string''

By passing the optional arguments, you can vary the string based on a number that will be substituted into it. As with all Lua functions, the parentheses are optional when passing a single string argument, as in the above example. This plural syntax returns a form of the string that's grammatically suitable for the indicated number, but doesn't actually substitute the number in – you need to do that yourself with either '''string.format''' or '''stringx.vformat'''.

The returned translatable string can be treated in many ways like a regular string. Translatable strings can be compared with other translatable strings or concatenated with each other or with regular strings or integers. The length operator also works, though it should be noted that its value may change if the language is changed. If you need to pass a translatable string to a function that doesn't understand them, it can be converted to a regular string with tostring.

=== wesnoth.log ===

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

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.

''logger'' is the log level.

In any context, ''logger'' can be the standard log levels of '''info''', '''debug''', '''warning''', or '''error'''. Various abbreviations of the standard four are also recognised. The default logger is '''info'''.

In the game context, you can also set the ''logger'' to '''wml'''. The '''wml''' log level 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 logdomain to enable these logs depends on the context. In the game context, they are written to the '''wml''' logdomain. In other contexts, the logdomain is '''scripting/lua/user'''.

=== wesnoth.as_text ===

{{DevFeature1.15|10}}

* {{LuaGameOnly}} '''wesnoth.as_text'''(''value1'', ''value2'', ...)

Accept one or more values as arguments and returns them as a string. This is intended for use as an easy way to view the contents of lua tables. Using the returned string for any other purpose is not supported.

{{DevFeature1.17|0}} This is now available in all contexts.

=== wesnoth.simulate_combat ===

* {{LuaGameOnly}} '''wesnoth.simulate_combat'''(''attacker'', [''attacker_weapon_index''], ''defender'', [''defender_weapon_index'']) → ''attacker stats evaluation'', ''defender stats evaluation'', ''attacker weapon evaluation'', ''defender weapon evaluation''

Computes the hitpoint distribution and status chance after a combat between two units. The first unit is the attacker. The attacker does not have to be on the map, but its location should be meaningful - that is, it can be a private-to-Lua clone of a unit with the '''x''' and '''y''' values changed, but whatever it is it has to have '''x''' and '''y''' values that allow attacking the defender (with '''max_range''' of the attack set appropriately it's possible to simulate attacking non-adjacent units). The second unit is the defender; it has to be on the map.

Optional integers can be passed after each unit to select a particular weapon, otherwise the "best" one is selected. When giving the weapon, the parameter is the weapon number (integer, starting at 1) and not the attack definition.

The function returns four tables describing the evaluation of the combat. The first two contain an evaluation of the combatant's stats over the course of the fight, while the second two contains more detailed information on their weapons.

The stats evaluation tables contain the following keys:

* ''stats''.'''poisoned''' → ''probability''
* ''stats''.'''slowed''' → ''probability''
* ''stats''.'''untouched''' → ''probability''

The probability that the unit will be poisoned or slowed, or that it will survive with no damage taken. (A scenario where the unit's hitpoints increase counts as untouched.)

* ''stats''.'''average_hp''' → ''number''

The expected value of the unit's hitpoints after the fight.

* ''stats''.'''hp_chance''' → ''mapping of hp to probability''

The probability that the unit's hitpoints will be at a specific value after the fight. Though it looks almost like an array, it begins at index 0 unlike a typical Lua array. Thus, it's better understood as an associated mapping from the resulting hitpoints value to the probability of ending the combat with that value. Therefore, the value at index 0 represents the chance that the unit will die.

The weapon evaluation tables contain the following keys:

{| class="wikitable"
!Key !!Description
|-
|attack_num
| DEPRECATED (use '''number'''). Attack number (0 based, -1 for no attack).
|-
|chance_to_hit
|Effective chance to hit as a percentage (all factors accounted for).
|-
|damage
|Effective damage of the weapon (all factors accounted for).
|-
|drains
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|drains]] opponent when it hits.
|-
|drain_constant
|Base HP drained regardless of damage dealt.
|-
|drain_percent
|Percentage of damage recovered as health.
|-
|firststrike
|Attack has [[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]] special.
|-
|name
|Name (not description) of the attack.
|-
|number
|Attack number (1 based, 0 for no attack).
|-
|num_blows
|Effective number of blows (takes [[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]] into account).
|-
|petrifies
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]] opponent when it hits.
|-
|plagues
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|turns opponent into a zombie]] when fatal.
|-
|plague_type
|The [[AbilitiesWML#Extra_keys_used_by_the_.5Bplague.5D_special|plague type]] used by the attack, if any.
|-
|poisons
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|poisons]] opponent when it hits.
|-
|rounds
|[[AbilitiesWML#The_.5Bspecials.5D_tag|Berserk]] special can force us to fight more than one round.
|-
|slows
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|slows]] opponent when it hits.
|}

<syntaxhighlight lang='lua'>
local function display_stats(n, t)
wesnoth.interface.add_chat_message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def, def_weapon)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

local att_stats, def_stats, att_weapon, def_weapon = wesnoth.simulate_combat(attacker, att_weapon_number, defender)
wesnoth.interface.add_chat_message(string.format(
"The attack %s should be countered with %s, which does %d damage, has %d%% chance to hit and forces %d attack rounds due to its berserk ability.",
att_weapon.name, def_weapon.name or "no weapon", def_weapon.damage, def_weapon.chance_to_hit, def_weapon.rounds))
</syntaxhighlight>

=== wesnoth.name_generator ===

* '''wesnoth.name_generator'''('''"markov"''', ''definition'', [''chain_size'', [''max_length'']]) → ''generator function''
* '''wesnoth.name_generator'''('''"cfg"''', ''definition'') → ''generator function''
* ''generator function''() → ''random name''

Constructs a name generator for use in generating names using either the Markov chain algorithm used in older versions of Wesnoth or the context-free grammar generator used since 1.13.5. The type parameter indicates which algorithm to use (either markov or cfg). The definition can be a string, just like it would be in a config file, or it can be formatted as a table. Additional parameters may be passed, depending on the type of generator. The function returns a callable userdata, which will return a new name each time it is called (with no parameters).

* '''Markov chain''': A Markov chain generator works by analyzing a list of input names and noticing tendencies in the way the letters are strung together. It can then apply those tendencies to produce new similar names that were not in the original list. Longer lists give better results. The definition is a list of names, formatted either as a comma-separated string or as an array-like table. The Markov generator can take two additional parameters.
** ''chain_size'': A value greater than 1 for the ''chain_size'' causes the analyzer to consider the words in chunks, which is similar to analyzing them syllable by syllable instead of letter by letter. The default chain size is 2, meaning that the analyzer treats words as consisting of 2-character syllables.
** ''max_length'': Places a cap on the total length of the name. The default value is 12 characters.
<syntaxhighlight lang=lua>
local markov_names = wesnoth.name_generator('markov', {'Kaasa', 'Kayya', 'Keyya', 'Kiira', 'Korra'}, 1)
print(markov_names(), markov_names(), markov_names())
</syntaxhighlight>
* '''Context-free grammar''': A [[context-free grammar]] is a way of specifying how strings can be constructed. The definition may be specified as a multi-line string, just as described in the preceding link, or it can be formatted as a table where the keys are non-terminals and the values are what they expand to. The expansion of each non-terminal can be formatted either as a |-separated list as described in the preceding link, or as an array-like table. (Mixing the two forms is permissible too.) The context-free generator has no additional parameters.
<syntaxhighlight lang=lua>
local cfg_names = wesnoth.name_generator('cfg', {
main = {'{prefix}{suffix}', '{prefix}{centre}{suffix}'},
prefix = 'Kaa|Ka|Ke|Kuu|Ko',
suffix = 'sa|yya|ra|rra',
centre = 'err|aash|eez|azz'
})
print(cfg_names(), cfg_names(), cfg_names())
</syntaxhighlight>

'''Note''': If you want to generate a name using any of the default generators, you can use the predefined generators in the [[LuaAPI/types#race|race]] instead of constructing one with this function.

=== wesnoth.compile_formula ===

* '''wesnoth.compile_formula'''(''formula'') → ''compiled formula''

Compiles a [[Wesnoth Formula Language]] formula into a Lua callable userdata. A compiled formula can be converted back to valid code using the built-in <code>tostring</code> function.

=== wesnoth.eval_formula ===

* '''wesnoth.eval_formula'''(''formula'', [''variables'']) → ''result''
* ''compiled formula''([''variables'']) → ''result''

Evaluate a [[Wesnoth Formula Language]] formula and return the result it computed (which can be '''nil''').

The passed in variables can be an arbitrary Lua table, which defines variables available to the formula. Unlike with WML tables, there is no restriction on the format of this table. The formula can access the variables as a list using the special WFL variable '''__list''', or as a map using the special WFL variable '''__map'''. Directly accessing keys on the table is also possible.

It is also possible to pass a unit proxy as the variables, which evaluates the formula in that unit's context just as if it had been used in a [[StandardUnitFilter]].

When calling '''wesnoth.eval_formula''', the first argument may either be an already-compiled formula or a string, in which case it will be automatically compiled on the fly.

<syntaxhighlight lang=lua>
local f = wesnoth.compile_formula('if(x > y, x - y, x + y)')

print(f{x=1,y=2}) -- prints 3.0
print(f{x=1,y=3}) -- prints 4.0
print(f{x=2,y=3}) -- prints 5.0
print(f{x=1,y=1}) -- prints 2.0
print(f{x=3,y=1}) -- prints 2.0
print(f{x=3,y=2}) -- prints 1.0
</syntaxhighlight>

=== wesnoth.version ===

* '''wesnoth.version'''(''version string'') → ''version''
* '''wesnoth.version'''(''major'', [''minor'', [''patch'']], [''suffix'')) → ''version''

Creates a version object, either by parsing a string or by building it from its component parts. The resulting version object can be compared with other version objects using the standard Lua comparison operators, which follows the same rules as the [[PreprocessorRef#.23ifver_and_.23ifnver|#ifver]] preprocessor statement. It can also be decomposed by accessing the following keys on the object:

* ''integer'': Grab any integer version component by index. A non-canonical version may have more than three components.
* '''major''': The major version number (index 1).
* '''minor''': The minor version number (index 2).
* '''revision''': The patch revision number (index 3).
* '''is_canonical''': True if the version has at most three components (plus an optional suffix).
* '''sep''': The character that separates the version components from the suffix (usually either + or nil).
* '''special''': The version suffix, for example the "dev" in "1.15.14+dev".

The version can be converted to a string using the built-in '''tostring''' function.

<syntaxhighlight lang=lua>
local function version_is_sufficient(required)
return wesnoth.current_version() >= required
end
local required = wesnoth.version "1.9.6"
if not version_is_sufficient(required) then
gui.alert(string.format("Your BfW version is insufficient, please get BfW %s or greater!", tostring(required)))
end
</syntaxhighlight>

=== wesnoth.current_version ===

* '''wesnoth.current_version'''() → ''current version''

Returns the current version of Wesnoth as a version object.

=== wesnoth.ms_since_init ===

* '''wesnoth.ms_since_init'''() → ''milliseconds''

This function returns the amount of milliseconds that have passed since Wesnoth started up the current session. Its only use is to track the passage of real time.

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

=== wesnoth.deprecated_message ===

* '''wesnoth.deprecated_message'''(''element_name'', ''level'', ''version'', ''detail_message'')

Displays a deprecation warning in the Lua console. The level is an integer from 1 to 4 inclusive (see [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|deprecation levels]]), and the version can be left nil for levels 1 and 4. Otherwise it must be a version ''string'' (not a version object from [[#wesnoth.version|wesnoth.version]]).

=== wesnoth.deprecate_api ===

* '''wesnoth.deprecate_api'''(''original_name'', ''new_name'', ''level'', ''version'', ''element'', ''detail_message'') → ''deprecated wrapper''

Creates a deprecated wrapper for a function or table. A deprecated function will raise the deprecated message the first time it's called, and then suppress it thereafter. A deprecated table will raise the deprecated message the first time a key is read or assigned, and then suppress it thereafter.

The ''element'' is the function or table to wrap. It can be the original function or the new function (which may happen if the function was renamed without any interface changes), or a wrapper function that calls the new function while providing the interface of the old function. The ''level'' and ''version'' are as in [[#wesnoth.deprecated_message|wesnoth.deprecated_message]].

If ''level'' is 4, then the ''element'' is ignored (you can pass '''nil''') and a generic deprecated wrapper is returned that does nothing but raises the deprecated message the first time you call it, assign a key, or read a key, and suppresses it thereafter. This is intended for a function that was removed without deprecation, to leave behind a more informative message if someone still attempts to use it.

If Wesnoth is run with the <tt>--strict-lua</tt> command-line option, this function will return '''nil''' instead of the deprecated wrapper. Since the normal use-case of this function is to assign the deprecated wrapper to the original name, this has the effect of erasing any deprecated functions from the API.

The result of this function always contains a '''__deprecated''' attribute set to true, which can allow identifying if something is deprecated.

=== wesnoth.type ===

{{DevFeature1.17|?}}

* '''wesnoth.type'''(''value'') → ''type name''

Returns a string describing the value's type. This is the same as the built-in type function, except that it returns a more specific string in the case of userdata or tables, based on the metatable. For example, it would return 'unit' if called on a unit.

=== wesnoth.named_tuple ===

{{DevFeature1.17|?}}

* '''wesnoth.named_tuple'''(''array'', ''names'') → ''named tuple''

Decorates a numeric based array so that the indices can be accessed by name instead of by index. This function is used internally for a number of things, most notably map locations and WML tags. Most end-users will not need to use it, but it could be useful if you wish to build a Lua API that returns locations (or similar data) in the engine-standard format.

For example:

<syntaxhighlight lang=lua>
local t = wesnoth.named_tuple({42,21,36}, {'x', 'y', 'z'})

print(t[1]) -- prints 42
print(t[2]) -- prints 21
print(t[3]) -- prints 36
print(t.x) -- prints 42
print(t.y) -- prints 21
print(t.z) -- prints 36
</syntaxhighlight>

=== wesnoth.get_language ===

* '''wesnoth.get_language'''() → ''string''

Gets the language the UI is currently set to. Note that this may return an empty string if using the system default language.

=== wesnoth.print_attributes ===

* '''wesnoth.print_attributes'''(''object'', [''function''])

Prints out a list of attributes that can be accessed on the object, excluding deprecated functionality. The function defaults to '''print''', and receives a formatted line usually containing multiple attributes. They are annotated by type – &fnof; for a function, &dagger; for a table, ! if there was an error attempting to determine the type (which includes write-only attributes). Other types are unannotated.

For tables, by default this iterates the table using '''pairs''' to discover the attributes available, walking the metatable hierarchy if there is an '''__index''' table and filtering out anything that contains a '''__deprecated''' attribute set to '''true'''. However, if finds a function as the '''__index''', and the table's metatable also has a member '''__dir''', it will be used instead. The '''__dir''' can either be an array of strings, or a function that returns an array of strings. It will automatically be sorted and have any duplicates filtered out.

For custom objects defined by the engine, there is special handling so that this function shows the correct result. For example, if used on a GUI2 widget object, it will show the attributes available for that type of widget, as well as the IDs of any sub-widgets that can be accessed by name.

In the Lua console only, this function can also be referenced by a shorter alias, '''dir'''.

== Hooks ==

=== wesnoth.persistent_tags ===

* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''read''' ↔ '''function'''(''wml content'')
* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''write''' ↔ '''function'''(''add_tag_function'')

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 to 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.wml_actions ===

* {{LuaGameOnly}} '''wesnoth.wml_actions'''.''action'' ↔ '''function'''(''wml parameters table'')

This is a hook table that exposes and defines WML actions. Each function in this table corresponds to a single ActionWML tag, allowing you to invoke tags, define custom tags, and even modify the behavior of built-in tags. The single argument to these functions is a WML table, the content of the tag.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or wml.error "[freeze_unit] expects an id= attribute."
local unit = wesnoth.units.get(unit_id)
if unit then unit.moves = 0 end
wesnoth.units.modify({ 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)
local modified_cfg = setmetatable({}, {__index = cfg})
modified_cfg.size = (cfg.size or 12) + 10
wesnoth.wml_actions.print(modified_cfg)
end
</syntaxhighlight>

An action handler should be able to handle being called with either a WML table or a WML vconfig userdata. It is recommended to pass the argument through ''wml.tovconfig'' before doing anything with it, both in the action's definition and when calling it directly (in case its definition did not do that). The engine always passes a vconfig when calling a WML action.

=== wesnoth.wml_conditionals ===

* {{LuaGameOnly}} '''wesnoth.wml_conditionals'''.''action'' ↔ '''function'''(''wml parameters table'') → ''boolean result''

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

Use it like this:

<syntaxhighlight lang=lua>
function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or wml.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>

Note that the basic logic tags of ConditionalWML (true, false, and, or, not) do not pass through this table and cannot be overridden.

=== wesnoth.effects ===

* {{LuaGameOnly}} '''wesnoth.effects'''.''name'' ↔ '''function'''(''unit'', ''wml table'')
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ ''description''
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ '''function'''(''unit'', ''wml table'') → ''description''

This table contains the implementation of [[EffectWML|[effect]]]s. Each value is a callable value that takes a unit and the effect config. It can be a function or a callable table. If it is a callable table, its metatable may have a '''__descr''' field which is either a string or a function. Built-in effects are present in this table, and you may register your own custom effects too.

<syntaxhighlight lang='lua'>
function wesnoth.effects.min_resistance(u, cfg)
local resistance_new = {}
local resistance_old = wml.parsed(wml.get_child(cfg, "resistance"))
for k,v in pairs(resistance_old) do
if type(k) == "string" and type(v) == "number" and u:resistance_to(k) >= v then
resistance_new[k] = v
end
end
wesnoth.effects.resistance(u, {
apply_to = "resistance",
replace = true,
T.resistance (resistance_new),
})
end
</syntaxhighlight>

The code above adds a new <code>min_resistance</code> effect that will set the resistances to specific values if they are currently below that value. It can then be used like this (for example, in [[DirectActionsWML#.5Bobject.5D|[object]]]):

<syntaxhighlight lang='wml'>
[effect]
apply_to=min_resistance
[resistance]
cold=50
[/resistance]
[/effect]
</syntaxhighlight>

Note that in order work properly, effects must be registered before any units are created. This means it must be placed into a global or scenario level [lua] tag. In particular, the preload event is too late.

You can also specify description modifiers, which will be used if a custom effect is placed in a <code>[trait]</code> tag. Instead of setting a function as the effect, you set a table with a <code>__call</code> metafunction which does what the function would have done. The table can then have an additional <code>__descr</code> metafunction which updates descriptions as necessary. The built-in effects all use this structure. This metafunction takes the same arguments as the regular effect function, but should not modify the unit. Instead, it returns a string to be appended to the trait's effect description.

=== wesnoth.micro_ais ===

* {{LuaGameOnly}} '''wesnoth.micro_ais'''.''ai_name'' ↔ ''function''(''cfg'') → ''required'', ''optional'', ''ca_params''

Registers a new [[Micro_AIs#Custom_Micro_AIs|MicroAI]] with '''ai_type'''=''ai_name''. The function will be called by the [micro_ai] tag to set up the AI. See the link for more details on how this works.

=== wesnoth.custom_synced_commands ===

* {{LuaGameOnly}} '''wesnoth.custom_synced_commands'''.''command_name'' ↔ ''function''(''cfg'')

Registers a custom synced command, which can be invoked by AI to enable unusual behaviour. The command can do basically anything, and is guaranteed to run on all clients. The WML table passed to the callback is the same table passed to [[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]].

== Data ==

Access to most of the game data is available via various tables in the <tt>wesnoth</tt> module.

=== wesnoth.colors ===

{{DevFeature1.15|4}}

* {{LuaGameOnly}} '''wesnoth.colors'''.''color_name'' → ''color info''

Access defined [[GameConfigWML#Color_Palettes|color ranges]]. This can be used to translate the color name available from '''wesnoth.sides[n].color''' to RGB values.

Each color info table contains the following keys:

* '''mid''' - average shade for recoloring with the team color
* '''min''' - minimum shade for recoloring with the team color (this is likely to be black)
* '''max''' - maximum shade for recoloring with the team color (this is likely to be almost white)
* '''minimap''' - representative color to use on the mini-map
* '''pango_color''' - {{DevFeature1.15|13}} a hex string such as '''#ff0000''' suitable for use in formatted text

Each of '''mid''', '''min''', '''max''' and '''minimap''' have the following keys:

* '''r''' - red component of that color
* '''g''' - green component of that color
* '''b''' - blue component of that color
* '''a''' - alpha component of that color (probably fully opaque)

Reference usage in mainline: see data/multiplayer/eras.lua

=== wesnoth.current ===

Contains various information about the current game and event state.

* {{LuaGameOnly}} '''wesnoth.current.side''' → ''side number''

The number of the currently active side.

* {{LuaGameOnly}} '''wesnoth.current.turn''' → ''turn number''

The current turn number.

* {{LuaGameOnly}} '''wesnoth.current.synced_state''' → ''state''

Allows you to determine whether the current code runs in a synced context. Returns one of the following strings:

:* '''synced''' - The current code runs on all mp clients. This is the normal context, in which all gamestate changing actions should take place.
:* '''unsynced''' - The current code runs only on the local machine, so changing the gamestate here will cause out-of-sync errors. For example, during '''select''' events or during the calculation of a [[LuaAPI/wesnoth/interface#wesnoth.interface.game_display|game_display]] hook. Typical things to do here are UI related things, or entering the synced state via '''[do_command]'''.
:* '''local_choice''' - The current code was invoked by [[#wesnoth.synchronize_choice|synchronize_choice]] and runs only on one local client to calculate the return value for the choice. You cannot enter the synced context with '''[do_command]''' now.
:* '''preload''' - We are currently running a preload event or an even earlier event. This behaves similar to '''local_choice'''.

* {{LuaGameOnly}} '''wesnoth.current.user_can_invoke_commands''' → ''boolean''

Indicates whether the player is currently able to take actions in the game.

* {{LuaGameOnly}} '''wesnoth.current.map''' → ''map userdata''

The current active game map. See [[LuaAPI/types/map]] and [[LuaAPI/wesnoth/map]] for information on how this data can be used.

* {{LuaGameOnly}} '''wesnoth.current.schedule''' → ''schedule userdata''

The current global time schedule. This is a special object with the following properties:

:* #''schedule''
:The Lua length operator will return the number of turns in the schedule.

:* ''schedule''[''index''] ↔ ''time of day info''
:Get the information for a particular time of day, or replace it with new info.

:* ''schedule''.'''time_of_day''' ↔ ''id''
:Get the ID of the current active time of day, or switch to a new one. If the time of day occurs more than once in the schedule, the time will be set to the first occurrence.

:* ''schedule''.'''liminal_bonus''' ↔ ''bonus''
:Get the maximum bonus for liminal units in the current schedule. You can also override the default by assigning a different value, or revert to the default by assigning nil.

* {{LuaGameOnly}} '''wesnoth.current.event_context''' → ''WML table''

Contains information on the current active event. Returns a table with the following keys:

:* '''name''' - The event name. This is the actual event that fired, not the name in the [event] tag, so it never contains commas or variables.
:* '''id''' - The event's unique ID, if it has one.
:* '''weapon''' - The first weapon relevant to the event, if any.
:* '''second_weapon''' - The second weapon relevant to the event, if any.
:* '''damage_inflicted''' - The damage inflicted in the event, if applicable.
:* '''x1''', '''y1''' - The first location relevant to the event, if any.
:* '''x2''', '''y2''' - The second location relevant to the event, if any.
:* '''unit_x''', '''unit_y''' - The location of the first unit relevant to the event, if any. This is the same as '''x1''', '''y1''' in most cases. Currently the only exceptions are enter and exit hex events.
:* '''data''' - {{DevFeature1.17|6}} The event data. Can contain anything at all if the event was fired by [[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]]. In a village capture event, '''owner_side''' will contain the former owner of the village.

=== wesnoth.game_config ===

Contains static global information about the game. Some of this information can also be modified on the fly, but only in the game context, not in the plugin or map generator context.

* '''wesnoth.game_config.base_income''' ↔ ''integer''
* '''wesnoth.game_config.village_income''' ↔ ''integer''
* '''wesnoth.game_config.village_support''' ↔ ''integer''
* '''wesnoth.game_config.poison_amount''' ↔ ''integer''
* '''wesnoth.game_config.rest_heal_amount''' ↔ ''integer'
* '''wesnoth.game_config.recall_cost''' ↔ ''integer''
* '''wesnoth.game_config.combat_experience''' ↔ ''integer''
* '''wesnoth.game_config.kill_experience''' ↔ ''integer''

Values of various game settings.

* '''wesnoth.game_config.global_traits'''[''trait id''] →

A table with named fields (trait id strings) holding the wml tables defining the traits. This contains all global traits the engine knows about, but race-specific traits are not included. The known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].

<syntaxhighlight lang=lua>
print(wesnoth.game_config.global_traits.strong.male_name)
</syntaxhighlight>

* {{LuaGameOnly}} '''wesnoth.game_config.do_healing''' ↔ ''boolean''

Whether healing will occur at the beginning of each side's turn.

* {{LuaGameOnly}} '''wesnoth.game_config.theme''' ↔ ''theme id''

The currently active in-game theme.

* '''wesnoth.game_config.debug''' → ''boolean''

Whether debug mode is currently active. Debug mode is activated by the --debug command-line parameter or the :debug in-game command.

* '''wesnoth.game_config.debug_lua''' → ''boolean''

Whether Lua debug is enabled. Lua debug is activated by the --debug-lua command-line parameter. This does not seem to do anything by default.

* '''wesnoth.game_config.mp_debug''' → ''boolean''

Whether MP debug is enabled. MP debug is activated in the same way as debug mode, but is only active in multiplayer games.

* '''wesnoth.game_config.strict_lua''' → ''boolean''

Whether strict Lua mode is enabled. Strict Lua mode is activated by the --strict-lua command-line parameter and causes all deprecated Lua APIs to be completely removed from the engine.

* {{DevFeature1.19|4}} '''wesnoth.game_config.palettes'''.''palette'' → ''list of colors''

Returns the color palette with the given name, as defined by a '''[color_palette]''' tag in the [[GameConfigWML#Color_Palettes|game config]].

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale''' → ''list of colors''

Returns the gradient used for health bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale_text''' → ''list of colors''

Returns the gradient used for health numbers.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale''' → ''list of colors''

Returns the gradient used for experience bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale_text''' → ''list of colors''

Returns the gradient used for experience numbers.

=== wesnoth.races ===

* {{LuaGameOnly}} '''wesnoth.races'''.''id'' → ''race info''

Access defined [[UnitsWML#.5Brace.5D|races]]. Returns a [[LuaAPI/types#Race|race userdata]].

=== wesnoth.scenario ===

Contains information about the current scenario

* {{LuaGameOnly}} '''wesnoth.scenario.turns''' ↔ ''turn limit''

The current turn limit of the scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.next''' ↔ ''scenario id''

The ID of the scenario to transition to when this scenario ends.

* {{LuaGameOnly}} '''wesnoth.scenario.id''' → ''scenario id''

The ID of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.name''' →

The name of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.defeat_music''' ↔ ''list of music tracks''

The music to play if you lose this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.victory_music''' ↔ ''list of music tracks''

The music to play if you win this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.show_credits''' ↔ ''boolean''

Whether credits should be shown when this scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text''' ↔ ''text''

The end text to show when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text_duration''' ↔ ''duration''

How long to show the end text for when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.difficulty''' → ''difficult''

The difficulty level this scenario is being played on.

* {{LuaGameOnly}} '''wesnoth.scenario.type''' → ''tag name''

The type of this scenario. One of the strings '''scenario''', '''multiplayer''', or '''test'''.

* {{LuaGameOnly}} '''wesnoth.scenario.era''' → ''era tag''

The [era] tag active in this scenario. Accessing this will throw an error in single-player games. This exists only for players which have the era installed, so for an era with ''require_era=yes'' it is safe to use.

* {{LuaGameOnly}} '''wesnoth.scenario.campaign''' → ''campaign tag''

The [campaign] tag active in this scenario. Accessing this will throw an error in multiplayer or test games, so be sure to check '''wesnoth.scenario.type''' first in generic code.

* {{LuaGameOnly}} '''wesnoth.scenario.resources''' → ''list of resource tags''

A list of [resource] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.modifications''' → ''list of modification tags''

A list of [modification] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.mp_settings''' → ''table''

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. This allows accessing basically everything that can be set in the create game screen. The following keys exist in the returned table:

* '''active_mods''' - A list of all active modification IDs
* '''hash''' - A hash of mp data
* '''mp_campaign''' - Name of mp campaign
* '''mp_scenario''' - ID of this mp scenario
* '''mp_scenario_name''' - Name of this mp scenario
* '''scenario''' - MP lobby title
* '''difficulty_define''' - The campaign difficulty string for an mp campaign
* '''mp_village_gold'''
* '''mp_village_support'''
* '''mp_num_turns'''
* '''mp_era''' - The id of the chosen era
* '''mp_eras''' - A list of all era ids
* '''mp_fog'''
* '''mp_shroud'''
* '''mp_random_start_time'''
* '''experience_modifier'''
* '''mp_use_map_settings'''
* '''mp_countdown''' - Whether the timer is enabled
* '''mp_countdown_action_bonus'''
* '''mp_countdown_init_time'''
* '''mp_countdown_reservoir_time'''
* '''mp_countdown_turn_bonus'''
* '''observer'''
* '''shuffle_sides'''
* '''savegame''' - Whether this is a reloaded game
* '''side_users''' - List of how sides are assigned to users (at game start)

=== wesnoth.terrain_types ===

{{DevFeature1.15|12}}

* {{LuaGameOnly}} '''wesnoth.terrain_types'''[''code''] → ''terrain info''

Access defined [[TerrainWML|terrain types]] by their terrain code. Returns a table with the following keys:

* '''id'''
* '''name'''
* '''editor_name'''
* '''description'''
* '''icon'''
* '''editor_image'''
* '''light'''
* '''village'''
* '''castle'''
* '''keep'''
* '''healing'''
* '''mvt_alias''' {{DevFeature1.19|10}}
* '''def_alias''' {{DevFeature1.19|10}}

=== wesnoth.unit_types ===

* {{LuaGameOnly}} '''wesnoth.unit_types'''[''id''] → ''unit type info''

Access defined [[UnitTypeWML|unit types]] by their ID. Returns a [[LuaAPI/types#Unit_Type|unit type userdata]].

== Submodules ==

The <tt>wesnoth</tt> module also contains a number of submodules for working with particular aspects of the game.

=== wesnoth.audio ===

A [[LuaAPI/wesnoth/audio|submodule]] containing functions for playing music and sound effects.

=== wesnoth.achievements ===

A [[LuaAPI/wesnoth/achievements|submodule]] containing functions for working with in-game achievements.

=== wesnoth.game_events ===

A [[LuaAPI/wesnoth/game_events|submodule]] containing functions for working with event handlers.

=== wesnoth.map ===

{{DevFeature1.15|11}}

A [[LuaAPI/wesnoth/map|submodule]] containing functions for querying and manipulating the game map.

=== wesnoth.interface ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/interface|submodule]] containing functions pertaining to the in-game UI.

=== wesnoth.paths ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/paths|submodule]] containing functions related to pathfinding.

=== wesnoth.schedule ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/schedule|submodule]] containing functions to manipulate the time of day schedule.

=== wesnoth.sides ===

{{DevFeature1.15|3}}

A [[LuaAPI/wesnoth/sides|submodule]] containing functions for manipulating the sides of a scenario.

=== wesnoth.sync ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/sync|submodule]] containing functions to deal with multiplayer synchronization.

=== wesnoth.units ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/units|submodule]] containing functions to manipulate units on the map.

[[Category: Lua Reference]]

== Unsupported Functions ==

The following functions exist in the '''wesnoth''' module but are not intended to be used:

* wesnoth.allow_undo
* wesnoth.cancel_action
* wesnoth.clear_menu_item
* wesnoth.set_menu_item
* wesnoth.kernel_type
* wesnoth.log_replay
* wesnoth.print
* wesnoth.redraw
* wesnoth.add_known_unit
* wesnoth.get_era
* wesnoth.get_resource

Some of these have WML equivalents, so if you need the functionality you should call the WML action directly (via [[#wesnoth.wml_actions|wml_actions]] or [[LuaAPI/wml#wml.fire|wml.fire]]). Others are internal functionality used in core Lua scripts, which are not intended for general use. These functions ''may'' be removed or changed without warning or going through a deprecation cycle.

Examination of the '''wesnoth''' module will also reveal two additional subtables - the '''package''' table, which is where packages loaded by [[#wesnoth.require|wesnoth.require]] persist (meaning you can force '''wesnoth.require''' to reload a file by nulling out its entry in this table), and the '''experimental''' module, which contains functions that are available for use but without warranty - they may change without warning or going through a deprecation cycle. Use of both of these tables is unsupported.

UnitsWML

2025-03-20T11:32:13Z

Laela: /* [terrain_defaults] */ 9676

{{WML Tags}}

The '''[units]''' tag is a [[ReferenceWML#WML_toplevel_tags|top-level WML tag]] which defines the unit types that will be available in the game.

A '''[units]''' tag primarily contains [[UnitTypeWML|[unit_type]]] tags, each of which defines one unit type, and can also contain other tags, which mostly provide definitions of things like races and movement types that are used in unit type definitions.

== Subtags of [units] ==

The following tags can be used as subtags of a '''[units]''' tag.

=== [unit_type] ===

{{Main|UnitTypeWML}}

In a '''[units]''' tag, a '''[unit_type]''' tag defines a unit type.

=== [trait] ===

The '''[trait]''' tag describes a trait. When it appears in the '''[units]''' toplevel, it describes a global trait, and all races with the attribute '''ignore_global_traits=no''' will have this trait.; it may also appear in other places.
* '''id''': unique identifier; needed for random trait generation to work properly
* '''availability''': describes whether a trait is "musthave" for a race/unit type or is available to "any" unit, including leaders. The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits.
* '''male_name''': text displayed in the status of unit with the trait if the unit is male.
* '''female_name''': text displayed in the status of unit with the trait if the unit is female.
* '''name''': text displayed in the status of unit with the trait if none of the two above is used.
* '''description''': text displayed for the description of the trait when moving the cursor over the trait.
* '''help_text''': {{DevFeature1.13|6}} text displayed for the description of the trait in the help. Defaults to ''description'' if not specified.
* '''[effect]''': described in [[EffectWML]]. More than one of these can be used.
* '''require_traits''': {{DevFeature1.17|13}} An optional comma-separated list of trait id keys that represent traits that are required by this one. Order is not important. If the unit not already has all of the traits that appear in this list, then this trait will not be generated for this unit.
* '''exclude_traits''': {{DevFeature1.17|13}} An optional comma-separated list of trait id keys that represent traits that are mutually exclusive to this one. Order is not important. If the unit already has any of the traits that appear once in this list, then this trait will not be generated for this unit. Of course, for this to really make two traits mutually exclusive, you need to add exclude_traits to both trait definitions.

=== [movetype] ===

The '''[movetype]''' tag is used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.
* '''name''': an ID for this movetype. Units with the attribute '''movement_type=''name''''' will be assigned this movetype.
* '''flies''' or {{DevFeature1.15|0}} '''flying''': either 'yes' or 'no' (default). A unit with ''flying=yes'' does not have its image's height adjusted for different terrains.
** This key corresponds to [unit]'s '''flying''' key.
** In Wesnoth 1.12 and 1.14, the value of '''flying''' sometimes overrides the value of '''flies''', but in other times '''flying''' is ignored
** {{DevFeature1.15|0}} '''flying''' always overrides the '''flies''' value, with the intention that '''flies''' will be deprecated.
* '''[special_note]''' {{DevFeature1.15|14}} note=Translatable string, which can be set if there’s something special about this movetype. It will be displayed in the unit's help page. For typical movetypes this is not set. An example are horses with the ''mounted'' movetype. See also [[UnitTypeWML#Special_Notes]].
* {{anchor|resistance|'''[resistance]'''}}: describes how much damage the unit takes from different types of attacks. The attribute '''''type''=''resistance''''' makes the unit receive ''resistance'' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%. The available attack types in mainline are blade, pierce, impact, fire, cold, and arcane.
* {{anchor|movement_costs|'''[movement_costs]'''}}: describes how fast the unit moves on different terrains. The attribute '''''terrain''=''cost''''' means that the unit will need to use ''cost'' move points to move onto that ''terrain''.
* {{anchor|vision_costs|'''[vision_costs]'''}}: describes how far the unit clears fog and shroud on different terrains. The attribute '''''terrain''=''cost''''' means that the unit will need to use ''cost'' vision points to view into that ''terrain''. (If not specified for a particular terrain, the vision cost defaults to the movement cost.)
* {{anchor|jamming_costs|'''[jamming_costs]'''}}: {{DevFeature1.13|0}} describes how far the unit interferes with the vision of other units over different terrains. This works the same as movement and vision costs. [https://forums.wesnoth.org/viewtopic.php?f=21&t=44577&p=644985#p644985 Example of jamming]
* {{anchor|defense|'''[defense]'''}}: describes how likely the unit is to be hit on different terrains. The attribute '''''terrain''=''defense''''' means that the unit will be hit ''defense'' percent of the time in that ''terrain''. If the defense value is negative, then that specifies an upper limit. The number in absolute terms is then also the best defense that the unit may have if there is more than one terrain type involved. For example '''forest=-70''' common for mounted units means the unit cannot get more than 30% defense on forest terrain. Regardless what other terrain the forest is on.

The available keys for the '''[movement_costs]''', '''[vision_costs]''', '''[jamming_costs]''' and '''[defense]''' tags are the '''id'''s of archetype terrains (those not aliased to any other terrain, see [[TerrainWML]]). 
In mainline that encompasses deep_water, shallow_water, reef, swamp_water, flat, sand, forest, hills, mountains, village, castle, cave, frozen, unwalkable, fungus, and impassable.

=== [race] ===

The '''[race]''' tag is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions. 'id' and 'plural_name' and ('name' or ('male_name' and 'female_name')) '''must''' be supplied.
* '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
* '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
* '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
* '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
* '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'.
* '''description''': text used in the in-game help.
* '''help_taxonomy''': {{DevFeature1.15|5}} in the help browser, show this race as a group of units from another race; the value of this attribute should be the other race's '''id''' attribute. This only affects the help browser, for all other purposes (such as WML filters) the two races are completely separate. (How this is visualised in the help browser is a GUI design decision, this attribute merely tells the engine that the relationship exists.)
* '''name_generator''' {{DevFeature1.13|5}}: [[Context-free grammar]] describing unit names, if absent or invalid, falls back to male_names or female_names
* '''male_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for male names
* '''female_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for female names
* '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.
* '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
* '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.
* '''ignore_global_traits''': 'yes' or 'no' (default). Determines whether global traits (see [traits] above) are applied.
* '''undead_variation''': sets the default undead variation for members of this race.
* '''[topic]''': describes extra help topics for this race.
* '''[trait]''': describes a trait for this race. See above for syntax.

=== [resistance_defaults] ===

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.9 ([https://github.com/wesnoth/wesnoth/issues/5308 issue #5308])

The '''[resistance_defaults]''' tag allows you to add resistance for custom damage types to already-defined movetypes (such as core movetypes).
* '''id''': The damage type you want to apply resistance defaults for.
* '''default''': The default resistance for all movetypes. You can set it to a number, or to a [[Wesnoth Formula Language|formula]] (enclosed in parentheses, but with no preceding dollar sign <code>$</code> or whitespace) which can reference any of the default resistance types - arcane, fire, etc. A common usage for formulas might be to set it to be equal to another resistance, eg '''default="(impact)"'''.
* Other keys reference the '''name=''' attribute of a defined movetype. For example, 'smallfoot=50' will set the resistance to 50 for the smallfoot movement type. Formulas can also be used here, for example 'smallfoot=(impact)'.

''Note:'' The '''default=''' key and other keys are handled slightly differently. A '''default=''' value will never override an explicitly specified value either in the same '''[resistance_defaults]''' tag or in a '''[movetype]''' definition, but other keys always take priority over values specified in a '''[movetype]''' definition.

{{DevFeature1.15|9}} The formulas can now access other parts of the movetype, for example "(resistance.arcane)" or "(movement_costs.flat)". For [resistance_defaults], "(arcane)" is shorthand for, and equivalent to, "(resistance.arcane)". See the documentation in the [terrain_defaults] section for more details about this.

=== [terrain_defaults] ===

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.11 ([https://github.com/wesnoth/wesnoth/issues/5308 issue #5308])

The '''[terrain_defaults]''' tag allows you to add costs and defenses for custom terrain types to already-defined movetypes (such as core movetypes).
* '''id''': The '''id=''' attribute of the terrain type you want to apply cost and defense defaults for.
* Subtags are used to specify the values using the same syntax as [resistance_defaults] - an optional default key, and subsequent keys which are movetype names. As with [resistance_defaults], you can use [[Wesnoth Formula Language|formulas]] if you enclose them in parentheses (but with no preceding dollar sign <code>$</code> or whitespace).
* Short names for the subtags are '''[movement]''', '''[jamming]''', '''[vision]''', and '''[defense]'''.
* Long names for the subtags are '''[movement_costs]''', '''[vision_costs]''', '''[jamming_costs]''', and '''[defense]'''.

1.14.16 and 1.15.11 recognise both the short and long names above. 1.15.9 and 1.15.10 only recognised the long names, and all other prior versions only recognised the short names.

{{DevFeature1.14|16}} {{DevFeature1.15|9}} The formulas can now access other parts of the movetype, for example '''(resistance.arcane)''' or '''(movement_costs.swamp_water)'''. Simply using '''(swamp_water)''' is shorthand for the value in whichever subtag is being patched. Formulas only recognise the long names.

The '''[terrain_defaults]''' tags are processed before any calculations of mixed terrains happen, and can only access the values for the basic terrain types. It's not useful to set a value for a mixed terrain type, as the calculations of mixed terrains' values decompose the mixed terrain to its base terrains before calculating the result, thus ignoring any patched values for mixed terrains.

Setting a '''default=''' value for '''[vision_costs]''' or '''[jamming_costs]''' means that that value will be used instead of falling back to using the movement_costs for calculating vision. For this reason, it's likely that '''default=''' should only be used when patching the '''[movement_costs]''' and '''[defense]''', not for vision or jamming.

A formula may use data added in a previous '''[terrain_defaults]'''. However, relying on data in the same '''[terrain_defaults]''' that creates or changes it is unsupported, because no guarantee is made of the order in which the subtags are processed.

While '''[terrain_defaults]''' formulas can use resistances, and '''[resistance_defaults]''' formulas can use movement costs, no guarantee is made of whether '''[terrain_defaults]''' tags will be processed before or after '''[resistance_defaults]''' tags. Therefore, formulas should only use base terrains and not rely on data added by the other kind of movetype-patching tag.

=== [hide_help] ===

The '''[hide_help]''' tag allows you to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. Only really useful for campaigns, not for eras. The following keys and their contents uses an 'OR' logic between them.
* '''type''': list of unit types.
* '''race''': list of races. Equivalent to all unit types of these races.
* '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.
* '''all''': 'yes' or 'no' (default). 'yes' is equivalent to all unit types (useful before [not])
* '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
<syntaxhighlight lang=wml>
[hide_help]
all=yes
[not]
type=Yeti
race=human
[not]
type_adv_tree=Mage
[/not]
[/not]
[/hide_help]
</syntaxhighlight>

== See Also ==

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

[[Category: WML Reference]]

UnitsWML

2025-03-20T11:31:37Z

Laela: /* [resistance_defaults] */ 9676

{{WML Tags}}

The '''[units]''' tag is a [[ReferenceWML#WML_toplevel_tags|top-level WML tag]] which defines the unit types that will be available in the game.

A '''[units]''' tag primarily contains [[UnitTypeWML|[unit_type]]] tags, each of which defines one unit type, and can also contain other tags, which mostly provide definitions of things like races and movement types that are used in unit type definitions.

== Subtags of [units] ==

The following tags can be used as subtags of a '''[units]''' tag.

=== [unit_type] ===

{{Main|UnitTypeWML}}

In a '''[units]''' tag, a '''[unit_type]''' tag defines a unit type.

=== [trait] ===

The '''[trait]''' tag describes a trait. When it appears in the '''[units]''' toplevel, it describes a global trait, and all races with the attribute '''ignore_global_traits=no''' will have this trait.; it may also appear in other places.
* '''id''': unique identifier; needed for random trait generation to work properly
* '''availability''': describes whether a trait is "musthave" for a race/unit type or is available to "any" unit, including leaders. The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits.
* '''male_name''': text displayed in the status of unit with the trait if the unit is male.
* '''female_name''': text displayed in the status of unit with the trait if the unit is female.
* '''name''': text displayed in the status of unit with the trait if none of the two above is used.
* '''description''': text displayed for the description of the trait when moving the cursor over the trait.
* '''help_text''': {{DevFeature1.13|6}} text displayed for the description of the trait in the help. Defaults to ''description'' if not specified.
* '''[effect]''': described in [[EffectWML]]. More than one of these can be used.
* '''require_traits''': {{DevFeature1.17|13}} An optional comma-separated list of trait id keys that represent traits that are required by this one. Order is not important. If the unit not already has all of the traits that appear in this list, then this trait will not be generated for this unit.
* '''exclude_traits''': {{DevFeature1.17|13}} An optional comma-separated list of trait id keys that represent traits that are mutually exclusive to this one. Order is not important. If the unit already has any of the traits that appear once in this list, then this trait will not be generated for this unit. Of course, for this to really make two traits mutually exclusive, you need to add exclude_traits to both trait definitions.

=== [movetype] ===

The '''[movetype]''' tag is used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.
* '''name''': an ID for this movetype. Units with the attribute '''movement_type=''name''''' will be assigned this movetype.
* '''flies''' or {{DevFeature1.15|0}} '''flying''': either 'yes' or 'no' (default). A unit with ''flying=yes'' does not have its image's height adjusted for different terrains.
** This key corresponds to [unit]'s '''flying''' key.
** In Wesnoth 1.12 and 1.14, the value of '''flying''' sometimes overrides the value of '''flies''', but in other times '''flying''' is ignored
** {{DevFeature1.15|0}} '''flying''' always overrides the '''flies''' value, with the intention that '''flies''' will be deprecated.
* '''[special_note]''' {{DevFeature1.15|14}} note=Translatable string, which can be set if there’s something special about this movetype. It will be displayed in the unit's help page. For typical movetypes this is not set. An example are horses with the ''mounted'' movetype. See also [[UnitTypeWML#Special_Notes]].
* {{anchor|resistance|'''[resistance]'''}}: describes how much damage the unit takes from different types of attacks. The attribute '''''type''=''resistance''''' makes the unit receive ''resistance'' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%. The available attack types in mainline are blade, pierce, impact, fire, cold, and arcane.
* {{anchor|movement_costs|'''[movement_costs]'''}}: describes how fast the unit moves on different terrains. The attribute '''''terrain''=''cost''''' means that the unit will need to use ''cost'' move points to move onto that ''terrain''.
* {{anchor|vision_costs|'''[vision_costs]'''}}: describes how far the unit clears fog and shroud on different terrains. The attribute '''''terrain''=''cost''''' means that the unit will need to use ''cost'' vision points to view into that ''terrain''. (If not specified for a particular terrain, the vision cost defaults to the movement cost.)
* {{anchor|jamming_costs|'''[jamming_costs]'''}}: {{DevFeature1.13|0}} describes how far the unit interferes with the vision of other units over different terrains. This works the same as movement and vision costs. [https://forums.wesnoth.org/viewtopic.php?f=21&t=44577&p=644985#p644985 Example of jamming]
* {{anchor|defense|'''[defense]'''}}: describes how likely the unit is to be hit on different terrains. The attribute '''''terrain''=''defense''''' means that the unit will be hit ''defense'' percent of the time in that ''terrain''. If the defense value is negative, then that specifies an upper limit. The number in absolute terms is then also the best defense that the unit may have if there is more than one terrain type involved. For example '''forest=-70''' common for mounted units means the unit cannot get more than 30% defense on forest terrain. Regardless what other terrain the forest is on.

The available keys for the '''[movement_costs]''', '''[vision_costs]''', '''[jamming_costs]''' and '''[defense]''' tags are the '''id'''s of archetype terrains (those not aliased to any other terrain, see [[TerrainWML]]). 
In mainline that encompasses deep_water, shallow_water, reef, swamp_water, flat, sand, forest, hills, mountains, village, castle, cave, frozen, unwalkable, fungus, and impassable.

=== [race] ===

The '''[race]''' tag is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions. 'id' and 'plural_name' and ('name' or ('male_name' and 'female_name')) '''must''' be supplied.
* '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
* '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
* '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
* '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
* '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'.
* '''description''': text used in the in-game help.
* '''help_taxonomy''': {{DevFeature1.15|5}} in the help browser, show this race as a group of units from another race; the value of this attribute should be the other race's '''id''' attribute. This only affects the help browser, for all other purposes (such as WML filters) the two races are completely separate. (How this is visualised in the help browser is a GUI design decision, this attribute merely tells the engine that the relationship exists.)
* '''name_generator''' {{DevFeature1.13|5}}: [[Context-free grammar]] describing unit names, if absent or invalid, falls back to male_names or female_names
* '''male_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for male names
* '''female_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for female names
* '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.
* '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
* '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.
* '''ignore_global_traits''': 'yes' or 'no' (default). Determines whether global traits (see [traits] above) are applied.
* '''undead_variation''': sets the default undead variation for members of this race.
* '''[topic]''': describes extra help topics for this race.
* '''[trait]''': describes a trait for this race. See above for syntax.

=== [resistance_defaults] ===

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.9 ([https://github.com/wesnoth/wesnoth/issues/5308 issue #5308])

The '''[resistance_defaults]''' tag allows you to add resistance for custom damage types to already-defined movetypes (such as core movetypes).
* '''id''': The damage type you want to apply resistance defaults for.
* '''default''': The default resistance for all movetypes. You can set it to a number, or to a [[Wesnoth Formula Language|formula]] (enclosed in parentheses, but with no preceding dollar sign <code>$</code> or whitespace) which can reference any of the default resistance types - arcane, fire, etc. A common usage for formulas might be to set it to be equal to another resistance, eg '''default="(impact)"'''.
* Other keys reference the '''name=''' attribute of a defined movetype. For example, 'smallfoot=50' will set the resistance to 50 for the smallfoot movement type. Formulas can also be used here, for example 'smallfoot=(impact)'.

''Note:'' The '''default=''' key and other keys are handled slightly differently. A '''default=''' value will never override an explicitly specified value either in the same '''[resistance_defaults]''' tag or in a '''[movetype]''' definition, but other keys always take priority over values specified in a '''[movetype]''' definition.

{{DevFeature1.15|9}} The formulas can now access other parts of the movetype, for example "(resistance.arcane)" or "(movement_costs.flat)". For [resistance_defaults], "(arcane)" is shorthand for, and equivalent to, "(resistance.arcane)". See the documentation in the [terrain_defaults] section for more details about this.

=== [terrain_defaults] ===

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.11 ([https://github.com/wesnoth/wesnoth/issues/5308 issue #5308])

The '''[terrain_defaults]''' tag allows you to add costs and defenses for custom terrain types to already-defined movetypes (such as core movetypes).
* '''id''': The '''id=''' attribute of the terrain type you want to apply cost and defense defaults for.
* Subtags are used to specify the values using the same syntax as [resistance_defaults] - an optional default key, and subsequent keys which are movetype names. As with [resistance_defaults], you can use [[Wesnoth Formula Language|formulas]] if you enclose them in parentheses (but with no preceding dollar sign <code>$</code>).
* Short names for the subtags are '''[movement]''', '''[jamming]''', '''[vision]''', and '''[defense]'''.
* Long names for the subtags are '''[movement_costs]''', '''[vision_costs]''', '''[jamming_costs]''', and '''[defense]'''.

1.14.16 and 1.15.11 recognise both the short and long names above. 1.15.9 and 1.15.10 only recognised the long names, and all other prior versions only recognised the short names.

{{DevFeature1.14|16}} {{DevFeature1.15|9}} The formulas can now access other parts of the movetype, for example '''(resistance.arcane)''' or '''(movement_costs.swamp_water)'''. Simply using '''(swamp_water)''' is shorthand for the value in whichever subtag is being patched. Formulas only recognise the long names.

The '''[terrain_defaults]''' tags are processed before any calculations of mixed terrains happen, and can only access the values for the basic terrain types. It's not useful to set a value for a mixed terrain type, as the calculations of mixed terrains' values decompose the mixed terrain to its base terrains before calculating the result, thus ignoring any patched values for mixed terrains.

Setting a '''default=''' value for '''[vision_costs]''' or '''[jamming_costs]''' means that that value will be used instead of falling back to using the movement_costs for calculating vision. For this reason, it's likely that '''default=''' should only be used when patching the '''[movement_costs]''' and '''[defense]''', not for vision or jamming.

A formula may use data added in a previous '''[terrain_defaults]'''. However, relying on data in the same '''[terrain_defaults]''' that creates or changes it is unsupported, because no guarantee is made of the order in which the subtags are processed.

While '''[terrain_defaults]''' formulas can use resistances, and '''[resistance_defaults]''' formulas can use movement costs, no guarantee is made of whether '''[terrain_defaults]''' tags will be processed before or after '''[resistance_defaults]''' tags. Therefore, formulas should only use base terrains and not rely on data added by the other kind of movetype-patching tag.

=== [hide_help] ===

The '''[hide_help]''' tag allows you to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. Only really useful for campaigns, not for eras. The following keys and their contents uses an 'OR' logic between them.
* '''type''': list of unit types.
* '''race''': list of races. Equivalent to all unit types of these races.
* '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.
* '''all''': 'yes' or 'no' (default). 'yes' is equivalent to all unit types (useful before [not])
* '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
<syntaxhighlight lang=wml>
[hide_help]
all=yes
[not]
type=Yeti
race=human
[not]
type_adv_tree=Mage
[/not]
[/not]
[/hide_help]
</syntaxhighlight>

== See Also ==

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

[[Category: WML Reference]]

InterfaceActionsWML

2025-02-12T20:12:12Z

Laela: /* [wml_message] */ update about rewrite to Lua during 1.13.x

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

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

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

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

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

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). [message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

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

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

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

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

<nowiki>You are victorious!</nowiki>

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

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

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

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

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

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

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

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

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

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item. All menus will be sorted lexicographically by the id string. The ordering is underscores, digits, and finally letters.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item, defaults to "buttons/WML-custom.png"
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

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

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

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

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

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

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

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

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

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

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

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

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

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

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

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

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

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

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

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

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

=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

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

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

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music] ===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax

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

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

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

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

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

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit
* '''object_id''': object id to use, defaults to the '''image''' key with an "overlay_" prefix; this allows using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']]
* '''duration''': object duration

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

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

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

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

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

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

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

The meanings of the deprecation levels are as follows:

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

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

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. WML wrapper of [[LuaAPI/wesnoth#wesnoth.log]], see the link for more description.
* '''message''': the message to show.
* '''to_chat''': controls whether message is visible in chat, though logger=wml means message is visible anyways. Default ''no''.
* '''logger''': one of '''info''', '''debug''', '''warning''', '''error''', '''wml'''. Default ''info''.

=== [test_condition] ===

{{DevFeature1.13|2}}

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

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

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

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

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

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

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

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

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

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

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

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

InternalActionsWML

2025-01-24T21:04:04Z

Laela: /* [fire_event] */ [data] as $data

{{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 [[VariablesWML|WML variables]]. The [https://www.wesnoth.org/macro-reference.html#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [https://www.wesnoth.org/macro-reference.html#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).

* {{anchor|join|'''[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.

* '''min''', '''max''': {{DevFeature1.15|9}} Specify a comma-separated list of numbers; either the smallest or largest number in the list will be assigned to the variable.

* '''reverse=yes''': {{DevFeature1.15|9}} Reverses the string value of the variable. For example, "delfador" becomes "rodafled".

* '''formula''': Calculate the new value of the variable from a [[Wesnoth_Formula_Language|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 clear the array '''name''' and replace it with given data. This is the default value.
** ''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''': set the array or container to the value of the given variable

* {{anchor|set_variables-value|'''[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]])

* {{anchor|set_variables-literal|'''[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

*{{anchor|set_variables-split|'''[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; defaults to ''value'' if omitted.
** '''separator''': separator to separate the elements; if omitted, each character of the string will become an element in the result array.
** '''remove_empty''': whether to ignore empty elements; ignored if '''separator''' is omitted

{{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. Defaults to '''location'''.

* '''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). See note below for ''vision''.
* '''moves''': possible values ''current'' (default), ''max''. For ''movement'' and ''attack'', specifies whether to use the current or maximum movement points when calculating the range. Ignored for ''vision''.
* '''viewing_side''': If left unset then fog and shroud are ignored, hidden ambushers are not ignored, and the real reach of the units is stored. If set to a non-zero number, then the area stored for each unit matching the SUF is based on the information visible to that unit's side; it doesn't matter which non-zero number is given. Ignored completely for ''vision''.
* '''variable''': the name of the variable (array) into which to store the locations.

In 1.14 and before, the ''vision'' range is calculated as max movement range ignoring ZoC + 1 hex.

{{DevFeature1.15|12}} ''vision'' uses the same calculations as the fog and shroud, and handles:
* units with vision costs different to movement costs
* units whose vision points aren't the same as their max movement points
* jamming by enemy units

==== [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''': Team color used for ellipses, sprites, and flags. Will be one of the id's found in data/core/team-colors.cfg or a custom color defined by [[GameConfigWML#Color_Palettes|[color_range]]].
* '''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
* '''side_name''': Translated string representing the side's description.
* '''team_name''': String representing the team's description. Sides with the same team_name are allied.
* '''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 [[ConditionalActionsWML#.5Bforeach.5D|[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}}

{{DevFeature1.15|7}} Fixed, was broken in 1.15.3

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. A footpad on castle has 70% defense, so this function stores the value 30.)

* 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_defense_on] ====

{{DevFeature1.15|7}} Similar to [store_unit_defense], but stores the same number that would be shown in the UI. For example, a footpad on castle has 70% defense, so this stores the value 70.

Takes the same attributes as [store_unit_defense], and defaults to storing the value in "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
*'''item_name''': {{DevFeature1.15|0}} if given, only items created with a matching '''[item]name=''' will be stored. As of 1.15.0, this does not support comma-separated lists.

==== [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 (including the starting hex).

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]]
*'''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.
*'''nearest_by''': {{DevFeature1.15|2}} possible values "movement_cost" (default), "steps", "hexes"; if the [destination] SLF matches multiple hexes, the one that would need the least movement points to reach may not be the one that's closest as measured by '''hexes''', or closest as measured by steps, from the starting point. This option chooses which measurement to prefer.

More detail about multiple destinations and the return structure is on [[FindPathExplanation]] (moved out of this page because it has an image in it).

This is the structure of the variable returned by [find_path]:
[path]
hexes = non-zero if a path was successfully found.
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 the 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 [https://www.wesnoth.org/macro-reference.html#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.

* {{DevFeature1.17|6}} '''[data]''': Additional arbitrary data to pass to the event. In addition to passing custom data, this can be used to set the '''damage_inflicted''' in an attack event or the '''owner_side''' in a village capture event. Values can be used by Lua. {{DevFeature1.19|9}} Values can be accessed as $data.

=== [remove_event] ===
{{DevFeature1.13|0}} Removes the event with the specified id.

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

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

* '''reassign''': {{DevFeature1.13|6}} Can be either yes or no, defaults to yes. If set to '''no''' then first search for a unit that already has this role, and if found use that unit.

* '''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. If '''reassign''' is '''no''', this setting also affects the search for a unit that already has the role.

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

* {{anchor|auto_recall|'''[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. There are several ways of specifying this:
** An integer, giving the exact number of locations to use. (Variable substitution is supported too.)
** {{DevFeature1.15|0}} A percentage, meaning that fraction of the total available spaces.
** {{DevFeature1.15|0}} A [[Wesnoth_Formula_Language|WFL]] formula. It has access to one variable, ''size'', which is the total number of available spaces. In order to identify it as a WFL formula, the entire expression must be enclosed in parentheses. (Do not use a '''$''', as that will cause it to see ''size'' as zero.)
** A Lua expression. As with a WFL expression, it can access the ''size'' variable. {{DevFeature1.15|0}} This is now deprecated.
* '''variable''': The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x, y, n and terrain.
* '''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|2}}

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

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

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

Wesnoth Formula Language

2025-01-23T20:47:02Z

Laela: /* Strings */ string to list

<div class="tright"> __TOC__ </div>

The Wesnoth Formula Language is a functional language used to evaluate expressions within the game engine. It allows performing calculations that would not otherwise be possible using only WML. For example, to have an event trigger when a unit has less than half its hitpoints, you could write the following as the event's filter:

<syntaxhighlight lang=wml>
[filter]
formula = "(hitpoints < max_hitpoints / 2)"
[/filter]
</syntaxhighlight>

The '''formula''' key is a part of [[StandardUnitFilter]] that accepts a condition written as WFL. The part inside the quotes is the WFL formula. This example will evaluate to true if the unit's '''hitpoints''' are less than half its '''max_hitpoints'''.

== Data Types and Operators ==

Wesnoth Formula Language has seven basic data types – [[#Numbers|integers]], [[#Numbers|real numbers]] (usually called "decimals"), [[#Strings|strings]], [[#Lists|lists]], [[#Maps|maps]], [[#Objects|objects]], and [[#Other Types and Operators|null]].

=== Numbers ===

The most common use of WFL is for simple calculations involving numbers. For this, the standard arithmetic operators (<code>+ - * / %</code>) work as you would expect, performing addition, subtraction, multiplication, division, and remainder. {{DevFeature1.13|5}} The remainder operator even works on decimal numbers, producing the integer remainder of the division.

The only caveat to watch out for is that <code>/</code> rounds down when used on integers. For example, <syntaxhighlight lang='wfl' inline>5 / 2</syntaxhighlight> will evaluate to <code>2</code>. To avoid this, make sure at least one of the numbers includes a decimal point - <syntaxhighlight lang='wfl' inline>5.0 / 2</syntaxhighlight> will evaluate to <code>2.5</code>.

Note that WFL supports only three decimal places of precision for decimal numbers; beyond that it will still be rounded down. (So <syntaxhighlight lang='wfl' inline>1.0 / 16</syntaxhighlight> will evaluate to <code>0.062</code> instead of <code>0.0625</code>.) The <code>^</code> operator performs exponentiation (raising to a power) - for example, <syntaxhighlight lang='wfl' inline>2 ^ 3</syntaxhighlight> evaluates to <code>8</code>

You can also use the standard comparison operators (<code>= != < <= > >=</code>) on numbers. This is often useful in unit filters - for example, a formula of <syntaxhighlight lang='wfl' inline>hitpoints < max_hitpoints / 2</syntaxhighlight> will match only if the unit is at less than half health. Comparison operators return 1 for true and 0 for false; there is no boolean type. Comparing values of different types will always return 0, with one exception – comparing an integer and decimal number will work as expected.

One final numeric operator exists - the dice roll. The syntax <syntaxhighlight lang='wfl' inline>3d12</syntaxhighlight> will roll three 12-sided dice and return the sum of the results. Note however that this is not multiplayer-safe, so using it can and will produce OOS errors. {{DevFeature1.13|5}} The dice operator is now synced and should be safe for use in multiplayer contexts.

'''Note:''' {{DevFeature1.13|5}} Some numeric operations will return null instead of a number. This usually involves the exponentiation operator - for example, <syntaxhighlight lang='wfl' inline>(-2) ^ 0.5</syntaxhighlight> attempts to take the square root of -2, which doesn't exist, so it returns null to indicate this. Dividing by zero also returns null, as well as certain [[#Numeric Functions|math functions]] in appropriate circumstances.

=== Strings ===

WFL also supports strings, which must be enclosed in single quotes (<syntaxhighlight lang='wfl' inline>'like this'</syntaxhighlight>). The comparison operators (<code>= != < <= > >=</code>) also work on strings, performing lexicographical comparison (ie, alphabetical order). The comparison is case sensitive.

{{DevFeature1.13|5}}

Strings can be concatenated with the concatenation operator <code>..</code>. They also support interpolations enclosed in square brackets, the contents of which can be any valid formula. For example:

<syntaxhighlight lang='wfl'>
'Some text: [a + b]' where a = 12, b = 10
</syntaxhighlight>

results in the string <code>Some text: 22</code>. (The <code>where</code> operator is explained [[#Variables|below]].)

If you need to include a literal square bracket in a string, write <code>[(]</code> or <code>[)]</code>. For a literal single quote, you can write <code>[']</code>. For example:

<syntaxhighlight lang='wfl'>
'[(]It[']s bracketed![)]'
</syntaxhighlight>

results in the string <code>[It's bracketed!]</code>.

You can index the characters or words of a string with the following syntax:

<syntaxhighlight lang='wfl'>
'Hello World'.char[4]
'Hello World'.word[1]
</syntaxhighlight>

These return <code>o</code> and <code>World</code>, respectively. A third option is also available, <code>item</code>, which splits the string on commas but allows parentheses to prevent a portion of the string from being split up. For example:

<syntaxhighlight lang='wfl'>
'First Item,Second Item,Third Item'.item[1]
'a,b,(c,d,e),f,g'.item[2]
</syntaxhighlight>

These return <code>Second Item</code> and <code>(c,d,e)</code>, respectively. When not providing index, list is returned.

<syntaxhighlight lang='wfl'>
'a,b,(c,d,e),f,g'.item = ['a', 'b', '(c,d,e)', 'f', 'g']
</syntaxhighlight>

=== Lists ===

A list is a sequence of values represented as square brackets, [], surrounding a comma-separated list. For instance:

<syntaxhighlight lang='wfl'>
[ 1, 5, 'abc' ]
</syntaxhighlight>

The comparison operators work on lists, performing lexicographical comparison. A specific list index can be obtained with the indexing operator, like this: <syntaxhighlight lang='wfl' inline>my_list[index]</syntaxhighlight>. The first element of a list is numbered 0.

There are four ''vector operators'' (<code>.+ .- .* ./</code>) that perform entrywise operations on lists. For example, <syntaxhighlight lang='wfl' inline>[1,2,3] .+ [12,2,8]</syntaxhighlight> produces <code>[13,4,11]</code>. Both lists must be of the same length to use these operators, and of course, they must contain only numbers.

{{DevFeature1.13|5}}

A negative list index now counts from the end of the list - <code>-1</code> refers to the last element. You can check if an element exists in a list using the <code>in</code> operator. Lists can also be joined with the concatenation operator <code>..</code>, and sliced using the range operator <code>~</code>. In fact, the range operator produces a list of consecutive numbers, and in fact any list of numbers can be used to index a list - the result is to take the elements at the requested indices, in order. Some examples:

<syntaxhighlight lang='wfl'>
[1, 7, 'abc', 2.5, 'foobar', 127][1~3]
(10~20)[[0,-1]]
[1, 7, 'abc', 2.5, 'foobar', 127][[2,4]]
</syntaxhighlight>

These result in the following lists:

[7, 'abc', 2.5]
[10,20]
['abc', 'foobar']

=== Maps ===

A map is a sequence of key-value pairs. For example:

<syntaxhighlight lang='wfl'>
[12 -> 'Hello', [1,2] -> 9, 'abc' -> 1.5]
</syntaxhighlight>

The comparison operators work on maps. A specific element of a map can be obtained with the indexing operation. In the above example, the following conditions are all true (assuming the map is in a variable called <code>self</code>):

* <syntaxhighlight lang='wfl' inline>self[12] = 'Hello'</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self[[1,2]] = 9</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self['abc'] = 1.5</syntaxhighlight>

{{DevFeature1.13|5}}

You can now use the <code>in</code> operator to test if a key exists in the map. You can also access string keys using the dot operator <code>.</code> as long as they are valid identifiers. (Valid identifiers contain letters and underscores only; no digits are permitted.)

Note that the selection indexing that lists use is ''not'' valid for maps - a list can be used as a key, after all.

=== Objects ===

An object is a container containing additional variables (see [[#Variables|below]] for further explanation of variables) which are not in the global scope. The ''dot operator'' can be used to evaluate a formula in the object's scope. For example, suppose ''u'' is a unit object referring to your leader, who is an Elvish Ranger who has taken 12 damage (thus has 30 hit points). Then <syntaxhighlight lang='wfl' inline>u.hitpoints</syntaxhighlight> will evaluate to the number 30. For a more advanced example, <syntaxhighlight lang='wfl' inline>u . (hitpoints < max_hitpoints - 10)</syntaxhighlight> will evaluate to true if the unit has taken more than 10 damage, which in this example, it has. (This could also be written <syntaxhighlight lang='wfl' inline>u.hitpoints < u.max_hitpoints - 10</syntaxhighlight> if you prefer; this enters the scope twice, instead of once, but the result is identical.)

Objects generally cannot be created directly by the code - they are created for you by the game when formulas are called in certain contexts. However, there are two types of object that ''can'' be created by your code. The first is the location object, which has variables ''x'' and ''y''; it can be created by the [[#loc|<code>loc()</code>]] function. The second is the map pair object, which is returned (or used internally) by several of the built-in functions and has variables ''key'' and ''value''.

==== Documentation of some common objects ====

There are a number of common objects that are given as the context object for formulas throughout the engine. Not all of these will be available in all formulas, but many of them are available in more than one formula. To learn what objects are available in a given location, see the WML documentation of that location.

* [[StandardUnitFilter#Wesnoth_Formula_Language|unit objects]]
* [[FilterWML#Filtering_Weapons|weapon objects]]
* [[StandardLocationFilter#Wesnoth_Formula_Language|terrain objects]]
* [[StandardSideFilter#Wesnoth_Formula_Language|side objects]]
* [[ImagePathFunctions#CHAN:_General function|pixel objects]]
* [[ConditionalActionsWML#.5Bvariable.5D|WML objects]]
* [[EventWML#filter_formula|game state objects]]

=== Other Types and Operators ===

There is one other basic type in WFL - the null type, which is used to mean "no value". It will be returned if you attempt to perform an invalid operation, such as dividing a string. It is also returned by the built-in <code>null()</code> function, which allows you to test if a value is null by writing <syntaxhighlight lang='wfl' inline>value = null()</syntaxhighlight>.

The logical operators <code>and</code> and <code>or</code> can be used to connect conditional expressions, and the unary operator <code>not</code> negates them. Note that <code>or</code> is inclusive - <syntaxhighlight lang='wfl' inline>A or B</syntaxhighlight> is false only if both ''A'' and ''B'' are false. These operators consider <code>0</code> or null to be false, while all other values count as true. The [[#if|<code>if()</code>]] function also follows the same rules to determine whether a value is true or false.

'''Note:''' Programmers familiar with other languages may occasionally be surprised by the fact that <code>and</code> and <code>or</code> do not short-circuit (which would mean that they will never evaluate their second argument if they can know their result solely from the first argument). This should not be a problem in general formula usage, since functions do not have side-effects, but it could make a difference when using the debug functions.

=== Operator Precedence ===

The precedence of various operators is, more or less, what you'd expect - you can write something like <syntaxhighlight lang='wfl' inline>a + b * 2 <= 5 and n - m / 4 > 7</syntaxhighlight> and the engine will do what you expect - first multiplication and division, then addition and subtraction, then comparison, and finally logical conjunction. The only thing to watch out for is when chaining exponentiation - all operators are left associative, so <syntaxhighlight lang='wfl' inline>a ^ b ^ c</syntaxhighlight> will be evaluated as <syntaxhighlight lang='wfl' inline>(a ^ b) ^ c</syntaxhighlight> instead of <syntaxhighlight lang='wfl' inline>a ^ (b ^ c)</syntaxhighlight> like you would expect. {{DevFeature1.13|5}} This has been fixed - exponentiation is now right-associative.

The full precedence list is as follows, from lowest to highest; operators on the same line have equal precedence.

# <code>not</code>
# <code>where</code> clauses
# <code>or</code>
# <code>and</code>
# Comparison operators <code>= != < <= > >= in</code>
# Range-generating operator <code>~</code>
# Additive operators <code>+ - ..</code>
# Multiplicative operators <code>* /</code>
# Modulus <code>%</code>
# Exponentiation <code>^</code>
# Dice operator <code>d</code>
# Dot operator <code>.</code>

== Functions ==

WFL is a ''functional'' language, so of course it has functions. There is a large library of [[#Core Functions|built-in functions]], and you can also [[#Defining Functions|define your own]].

Calling a function is simple, and works exactly how you would expect if you've worked with functions in a mathematical context: <syntaxhighlight lang=wfl inline>clamp(value, 0, 21)</syntaxhighlight>

Being a functional language, WFL does not have conditional or looping statements. Instead, these are provided by functions. For a simple conditional, you can use the <tt>if</tt> function, as in the following example:

<syntaxhighlight lang=wfl>
if(hitpoints > 37,
max_hitpoints / 2,
hitpoints - 3
)
</syntaxhighlight>

Similarly, looping is done via functions. There are several built-in higher-order functions that can be used to iterate over lists and maps, such as <tt>filter</tt>, <tt>choose</tt>, <tt>map</tt>, and <tt>reduce</tt>. See the corresponding function definitions for more information.

== Variables ==

Formulas may have a variety of variables, depending on the context in which they are evaluated. A string substitution formula like <code>$(3 + 5)</code> has no variables, but a [[StandardUnitFilter|unit filter]] formula has variables such as <code>hitpoints</code> and <code>max_hitpoints</code> which contain various properties of the unit being tested (the same unit which is also referred to in variable substitution as <code>$this_unit</code>). The special variable <code>self</code> typically refers to the "global context" - in the case of a unit filter formula, the unit itself. This means for example that <code>self.hitpoints</code> and <code>hitpoints</code> are equivalent when used in a unit filter formula. In a string substitution formula (the <code>$(formula)</code> syntax), <code>self</code> is null. Because of this, you should prefer not to use the substitution syntax in places where formulas are specifically supported.

A formula may declare additional variables using a <code>where</code> clause. This assigns a meaning to any unknown variables in the preceding formula. The general syntax is:

<formula> where <variable> = <value> [, <variable> = value ...]

This functions similarly to an operator, so if desired, you could have multiple where clauses in a single formula. Note that all variables in WFL are read-only - they are variables because they may have different values depending on the context in which the formula is evaluated, but for a given context, they are constant. A variable that has not been assigned a value is considered to have a value of null. Variables are lazily-evaluated - if a where clause declares a variable that is never used, the expression assigned to it will never be evaluated. (This only really matters if it contains a call to a debug function.)

Variable names can contain letters and underscores only. In particular, they cannot contain digits. Also, names are case-sensitive, so ''y'' and ''Y'' refer to two different variables. The following names are reserved and cannot be used for the name of a variable or function:

* <tt>d</tt> - dice operator
* <tt>or</tt> - logical operator
* <tt>in</tt> - containment operator
* <tt>def</tt> - defines a function
* <tt>and</tt> - logical operator
* <tt>not</tt> - logical operator
* <tt>fai</tt> - deprecated synonym of <tt>wfl</tt>
* <tt>wfl</tt> - declares filename
* <tt>where</tt> - declares variables
* <tt>faiend</tt> - deprecated synonym of <tt>wflend</tt>
* <tt>wflend</tt> - closes file scope
* <tt>functions</tt> - lists all defined functions

== Comments ==

Sometimes with particularly complicated formulas, it may be useful to document what's going on inline. Of course, you can use WML comments to do this, but in some cases it may be useful to put some comments in the middle of the formula. This is easily done - simply enclose them in <code>#</code> characters, like this:

<syntaxhighlight lang='wfl'>
#This is a Wesnoth Formula Language comment.#
</syntaxhighlight>

Note the final <code>#</code> - unlike WML, WFL requires this to indicate where the comment ends.

== Defining Functions ==

There are several predefined functions in the Wesnoth Formula Language, and if these are not enough, it is possible to define your own functions. The special variable <syntaxhighlight lang='wfl' inline>functions</syntaxhighlight> always evaluates to a list of all known function names. This is mainly useful only as a debugging tool, though.

To define a function, you use the <code>def</code> keyword. For example:

<syntaxhighlight lang='wfl'>
def sgn(x) if(x < 0, -1, x > 0, 1, 0);
</syntaxhighlight>

This defines a function called <code>sgn</code> which returns the sign of the input number. The semicolon marks the end of the function. It's optional if there's nothing else following the function, but in practice this will very rarely be the case.

Function names have the same limitation as variable names – they can contain only letters and underscores, and cannot contain digits.

You can select one of the function's arguments to be the "default" argument. If an object is passed to the default argument, then any attributes of that object are directly accessible in the global scope. For example:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u*) hitpoints < max_hitpoints / 2;
</syntaxhighlight>

This function takes a unit and returns 1 if it is at less than half hitpoints. The <code>*</code> indicates the default argument, without which it would instead have to be defined like this:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u) u.hitpoints < u.max_hitpoints / 2;
</syntaxhighlight>

It's important to remember that the function body has access to no variables other than its parameters. For example, the following function would not work (in an AI context) even though the my_leader variable is defined:

<syntaxhighlight lang='wfl'>
def endangers_leader(u) distance_between(u.loc, my_leader.loc) < u.moves;
</syntaxhighlight>

This is because the body of the function can't see the my_leader variable. To make this work, you would need to pass in my_leader as an additional parameter.

'''Note: Prior to 1.14, function definitions only work in AI code and GUI2 code.'''

== Where to Use Formulas ==

Formulas can only be used in specific attributes in WML. The documentation of a WML tag will note which keys can have a formula placed in them. Some common examples include [[FilterWML|filters]], [[GUIToolkit|GUI2 dialogs]], and [[AbilitiesWML|unit abilities]]. Another example is the [[VariablesWML#Variable_Substitution|<code>$(formula)</code> substitution]] syntax, which allows the use of formulas wherever variables are parsed.

When using a formula in WML (other than in a substitution, which is usually part of a longer already-quoted passage), it is highly recommended to place double quotes around the formula, to avoid ambiguity between the WML and WFL parsers. The double angle quotes are also acceptable for this purpose. If you don't quote your formulas, there are two issues you could run into:

# WML uses the <code>+</code> operator to represent concatenation of strings, as well as line continuation. Because of this, an unquoted <code>+</code> will be ''removed'', likely causing the WFL formula to fail to compile.
# Unquoted WML text has the whitespace collapsed. If using WFL strings where whitespace is significant, this can result in surprises. For example, the formula <syntaxhighlight lang=wfl inline>length('One Two Three')</syntaxhighlight> would return 13 instead of the expected 19 if double quotes are not placed around the formula.

Some attributes in WML ''require'' a formula, which means that anything placed in the attribute will always be considered to be a formula. In this case, the formula doesn't need to be enclosed in parentheses – just the double quotes will suffice. However, there are also attributes that take an ''optional'' formula. These are most common in GUI2, but are also found in other places. In such attributes, the formula ''must'' be enclosed in parentheses. Failure to do so will result in it being parsed as just a straight value. As a general guideline, if the attribute key contains the word "formula", it is usually required to be a formula, whereas attributes with optional formulas do ''not'' contain the word "formula" in the key.

'''Note''': Do ''not'' use a <code>$</code> to introduce a formula. The <code>$</code> is not part of WFL syntax. It introduces a ''substitution'', a concept which is covered in more detail at [[VariablesWML#Variable Substitution]]. Although WFL can be used ''inside'' a substitution, a substitution itself is not WFL, and you should ''never'' use a <code>$</code> in WFL. However, in practice, substitutions and WFL are often used together – as substitution is processed first, you may see WFL formulas that appear to contain a <code>$</code> inside them. This is ''not'' part of the WFL – it is more like a macro substitution to be carried out before the formula runs. So, of course, it will only work in places that support ''both'' WFL and substitution.

== Files ==

{{DevFeature1.13|5}}

On occasion, you may find yourself working with formulas complex enough to split them out into a separate file. The formula engine normally assumes that it is executing inline code and reports errors accordingly, but you can tell it to enter a file scope using the special <code>wfl</code> keyword. The convention is to frame your code, so that any file looks like this:

<syntaxhighlight lang='wfl'>
wfl 'filename.wfl'

# Put whatever code you need here, possibly including function definitions. #

wflend
</syntaxhighlight>

The matching <code>wflend</code> is required.

'''Note:''' This functionality was available prior to 1.13.5 using keywords <code>fai</code> and <code>faiend</code>. These keywords are now deprecated, but still work.

These directives have no effect on the formula code itself. They only change how error messages are reported if something goes wrong. Files using these directives are usually included using the WML preprocessor, though they could also be loaded in Lua with [[LuaAPI/filesystem#filesystem.read_file|filesystem.read_file]].

== Core Functions ==

Many of the core functions exhibit two features that (as of 1.13.4) cannot be used in user-defined functions. The first is the ability to accept a varying number of arguments - some core functions accept any number of arguments, while others have a few optional arguments. The second is that arguments are lazily-evaluated, and in some cases some arguments will not be evaluated at all, while others may be evaluated multiple times with different variable values. The description of each function will explain how and when its arguments are evaluated.

Most of the core functions can be used from any formula. However, there are some that are only available in formulas that have access to the game state. The following formulas have access to the game state and can use those functions:

* Formulas used in [[FilterWML]]
* Formulas used in [[AbilitiesWML]]
* <tt>filter_formula</tt> in [[EventWML#filter_formula|EventWML]]
* Formulas evaluated from the formula console (accessed by pressing F)

The following formulas do not have access to the game state and cannot use those functions:

* Formulas used in [[GUI2]]
* [[SyntaxWML#formula_substitution|Substitution]] formulas using <tt>$(...)</tt>
* [[ImagePathFunctions#CHAN: General function|IPF]] formulas used in <tt>~CHAN()</tt> or <tt>~ALPHA()</tt>
* Formulas compiled from [[LuaAPI/wesnoth#wesnoth.compile_formula|Lua]]

=== Conditional Functions ===

There are two functions which return one of their input values based on some condition - the <code>if</code> function, and the <code>switch</code> function. Both evaluate only as many parameters as is needed to determine which value to return. In particular, parameters that are neither returned nor part of the condition will never be evaluated.

==== if ====

* if(''condition'', ''if true'' [, ''condition 2'', ''if true 2'', ...] [, ''otherwise''])

This function first evaluates the ''condition'', which is a formula. If it evaluates to true, then the function evaluates and returns the ''if true'' parameter; otherwise, it tries the next condition (if any) with the same result. If none of the conditions evaluate to true, then it returns the ''otherwise'' parameter if present, or <code>null()</code> otherwise.

For instance, an AI that recruits Wolf Riders on the first turn, and Orcish Grunts thereafter might look like this:

<syntaxhighlight lang='wfl'>
if(turn = 1, recruit('Wolf Rider'), recruit('Orcish Grunt'))
</syntaxhighlight>

==== switch ====

* switch(''formula'', ''value 1'', ''outcome 1'' [, ... , ''value N'', ''outcome N''] [, ''default outcome''])

The switch function first evaluates the input ''formula'', and then checks if it is equal to any of the specified ''values''. If matching value is found, the ''outcome'' assigned to it is returned; if not, then function returns either ''default outcome'' (if specified) or null.

=== Numeric Functions ===

Several basic math functions are available. These generally work equally on integer and decimal values.

==== abs ====

* abs(''number'')

Returns the absolute value of an input number; for example

<syntaxhighlight lang='wfl'>
abs( -5 )
</syntaxhighlight>

will return 5.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== acos ====

{{DevFeature1.13|5}}

* acos(''number'')

Returns the arccosine of the input number, in degrees.

==== asin ====

{{DevFeature1.13|5}}

* asin(''number'')

Returns the arcsine of the input number, in degrees.

==== atan ====

{{DevFeature1.13|5}}

* atan(''number'')

Returns the arctangent of the input number, in degrees.
==== as_decimal ====

* as_decimal(''number'')

Ensures that the number is a decimal rather than an integer; useful if you're dividing two unknown values and want to ensure that the result is a decimal.

==== cbrt ====

{{DevFeature1.13|5}}

* cbrt(''number'')

Returns the cube root of the input number. This is better than using the exponentiation operator, because it will give the correct result for negative numbers.

==== ceil ====

* ceil(''number'')

Returns the ceiling of the specified number, ie rounding it up to the nearest integer.

==== clamp ====

{{DevFeature1.17|0}}

* clamp(''number'', ''min'', ''max'')

Combines min and max into a single call. If ''number'' is less than ''min'', returns ''min''; if it's greater than ''max'', returns ''max''. Otherwise, returns ''number''.

==== cos ====

* cos(''angle'')

Returns the cosine of the given angle, which is specified in degrees.

==== exp ====

{{DevFeature1.13|5}}

* exp(''number'')

Returns the exponential of the input number, which is the constant ''e'' raised to the specified power.

==== floor ====

* floor(''number'')

Returns the floor of the specified number, ie rounding it down to the nearest integer.

==== frac ====

{{DevFeature1.13|5}}

* frac(''number'')

Returns the fractional part of the specified number.

==== hypot ====

{{DevFeature1.13|5}}

* hypot(''x'', ''y'')

Returns the hypoteneuse length of a triangle with sides ''x'' and ''y''.

==== lerp ====

{{DevFeature1.17|0}}

* lerp(''min'', ''max'', ''fraction'')

Returns a linear interpolation between ''min'' and ''max'' according to the specified ''fraction''.

==== lerp_index ====

{{DevFeature1.19|4}}

* lerp_index(''list'', ''ratio'')

Returns the element of the list that is closest to being at the specified ratio of the list's length.

'''Example''': <syntaxhighlight lang=wfl inline>lerp_index([1, 12, 32, 10], 0.26])</syntaxhighlight> returns 12.

==== log ====

{{DevFeature1.13|5}}

* log(''number'', [, ''base''])

Returns the logarithm of the input number. If ''base'' is omitted, it returns the natural logarithm; otherwise, the logarithm to the specified base.

==== max ====

* max(''list of numbers'')

Returns the largest number from the list. For example:

<syntaxhighlight lang='wfl'>
max([2, 8, -10, 3])
</syntaxhighlight>

will return <code>8</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== min ====

* min(''list of numbers'')

Returns the smallest number from the list. For example:

<syntaxhighlight lang='wfl'>
min( [ 3, 7, -2, 6] )
</syntaxhighlight>

will return <code>-2</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== pi ====

{{DevFeature1.13|5}}

* pi()

Returns pi.

==== root ====

{{DevFeature1.13|5}}

* root(''number'', ''base'')

Returns the root of the input number, to the specified base. This is better than using the exponentiation operator, because it will give the correct result for negative numbers and odd bases (for example, the fifth root of -32, which is -2).

==== round ====

* round(''number'')

Returns the specified number rounded to the nearest integer.

==== sgn ====

{{DevFeature1.13|5}}

* sgn(''number'')

Returns the sign of the number, ie -1 if it is negative, 1 if it is positive, and 0 if it is zero.

==== sin ====

* sin(''angle'')

Returns the sine of the given angle, which is specified in degrees.

==== sqrt ====

{{DevFeature1.13|5}}

* sqrt(''number'')

Returns the square root of the input number.

==== sum ====

* sum(''list of numbers'')

This function evaluates to the sum of the numbers in the ''list of numbers''. For example:

<syntaxhighlight lang='wfl'>
sum([ 2, 5, 8])
</syntaxhighlight>

returns <code>15</code>, and:

<syntaxhighlight lang='wfl'>
sum(map(my_units, max_hitpoints - hitpoints))
</syntaxhighlight>

finds the total damage your units have taken.

==== tan ====

{{DevFeature1.13|5}}

* tan(''number'')

Returns the tangent of the given angle, which is specified in degrees.

==== trunc ====

{{DevFeature1.13|5}}

* trunc(''number'')

Returns the truncation of the specified number, ie rounding it towards zero. This is different from floor when applied to negative numbers - floor(-7.5) gives -8, but trunc(-7.5) gives -7.

==== wave ====

* wave(''number'')

Given a numeric value V, this returns:

sin(2*pi*V)

=== String Functions ===

There are a few useful functions for manipulating strings.

==== concatenate ====

* concatenate(''value1''[, ''value2'', ...])

Converts each of its arguments to a string, and concatenates the result together into a single string.

==== contains_string ====

* contains_string(''string'', ''search_string'')

Returns 1 if ''search_string'' can be found within ''string'' (as a substring), 0 otherwise. For example:

<syntaxhighlight lang='wfl'>
contains_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>1</code>.

==== length ====

* length(''string'')

Returns the length of the input string.

==== ends_with ====

{{DevFeature1.19|4}}

* ends_with(''string'', ''suffix'')

Determines whether the ''string'' ends with the specified ''suffix''.

==== find_string ====

{{DevFeature1.13|5}}

* find_string(''string'', ''search_string'')

Returns the index at which ''search_string'' starts within ''string'' (as a substring), or -1 if it is not found. For example:

<syntaxhighlight lang='wfl'>
find_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>4</code>.

==== replace ====

{{DevFeature1.13|5}}

* replace(''string'', ''offset'', [''size'',] ''replacement'')

Returns a new string obtained by replacing a portion of the input ''string'' with the contents of the ''replacement'' string. The ''offset'' and ''size'' work the same as for <code>substring</code>. Examples:

<syntaxhighlight lang='wfl'>
replace('The quick brown fox jumps over the lazy dog!', 4, 5, 'dumb')
replace('The quick brown fox jumps over the lazy dog!', -9, 4, 'sleeping')
replace('The quick brown fox jumps over the lazy dog!', -9, 'brook!')
replace('The quick brown fox jumps over the lazy dog!', -6, -4, 'yellow')
</syntaxhighlight>

return the following strings:

'The dumb brown fox jumps over the lazy dog!'
'The quick brown fox jumps over the sleeping dog!'
'The quick brown fox jumps over the brook!'
'The quick brown fox jumps over the yellow dog!'

==== replace_all ====

{{DevFeature1.19|4}}

* replace_all(''string'', ''match'', ''replacement'')

Returns a copy of ''string'' with all occurrences of ''match'' replaced by ''replacement''.

==== starts_with ====

{{DevFeature1.19|4}}

* starts_with(''string'', ''prefix'')

Determines whether the ''string'' begins with the specified ''prefix''.

==== substring ====

* substring(''string'', ''offset''[, ''size''])

Extracts a substring from the given input string. The ''offset'' specifies the first character to extract; the first character is <code>0</code>, and negative values count from the end, so the last character is <code>-1</code>. If specified, the ''size'' indicates the total number of characters to extract; it cannot be negative. If omitted, all characters from the ''offset'' to the end of the string are returned. For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', 4, 5)
substring('The quick brown fox jumps over the lazy dog!', -9, 4)
substring('The quick brown fox jumps over the lazy dog!', -9)
</syntaxhighlight>

return <code>'quick'</code>, <code>'lazy'</code>, and <code>'lazy dog!'</code> respectively.

{{DevFeature1.13|5}} The ''size'' can now be negative. This means to count backwards from the given ''offset'' (but always including the given offset, so a ''size'' of -1 gives the same result as 1). For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', -6, -4)
</syntaxhighlight>

returns <code>'lazy'</code>.

=== List and Map Functions ===

This section contains functions that directly manipulate a map or list.

==== head ====

* head(''list'' [, ''count''])

Returns the first item from the ''list''; for example

<syntaxhighlight lang='wfl'>
head([5, 7, 9])
</syntaxhighlight>

returns <code>5</code>, and

<syntaxhighlight lang='wfl'>
head( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Orc'</code>.

{{DevFeature1.13|5}} If a second argument is given, it returns a list containing the first ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>head(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>head(L,1)</syntaxhighlight> - the former returns the first element, while the latter returns a list containing only the first element.

==== index_of ====

* index_of(''value'', ''list'')

This function will return the first index where ''value'' can be found in the input ''list''. It will return -1 if the value is not found in the ''list'.

==== keys ====

* keys(''map'')

Extracts the key values from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
keys(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

['Elvish Fighter', 'Elvish Archer']

==== size ====

* size(''list'')

This function returns the number of elements in the ''list''.

For example, <syntaxhighlight lang='wfl' inline>size([5, 7, 9])</syntaxhighlight> returns <code>3</code> and <syntaxhighlight lang='wfl' inline>size(['Archer', 'Fighter'])</syntaxhighlight> returns <code>2</code>.

==== sort ====

* sort(''list'', ''formula'')

This function evaluates to a result list sorted according to the comparison ''formula'' for each item <code>a</code> and its successor <code>b</code>. For instance, sorting units according to hitpoints would be done by:

<syntaxhighlight lang='wfl'>
sort(my_units, a.hitpoints > b.hitpoints)
</syntaxhighlight>

To sort them in the reverse order, simply use <code><</code> instead of <code>></code>.

==== tail ====

{{DevFeature1.13|5}}

* tail(''list'' [, ''count''])

Returns the last item from the ''list''; for example

<syntaxhighlight lang='wfl'>
tail([5, 7, 9])
</syntaxhighlight>

returns <code>9</code>, and

<syntaxhighlight lang='wfl'>
tail( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Human'</code>.

If a second argument is given, it returns a list containing the last ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>tail(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>tail(L,1)</syntaxhighlight> - the former returns the last element, while the latter returns a list containing only the last element.

==== tolist ====

* tolist(''map'')

This function takes a map and return a list of key-value pair objects. For example:

<syntaxhighlight lang='wfl'>
tolist(['Elf' -> 10, 'Dwarf' -> 20])
</syntaxhighlight>

will return:

[{key->'Elf',value->10}, {key->'Dwarf',value->20}]

==== tomap ====

* tomap(''list A'' [, ''list B''])

This function takes one or two ''lists'' as input and returns a map. If only one list is specified, then the function will evaluate this list, count how many similar elements are found within the list, and return a map with keys being these elements, and values being a number representing how many of them the list contains. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf', 'elf', 'elf', 'human', 'human'])
</syntaxhighlight>

will return:

['elf' -> 3, 'dwarf' -> 1, 'human' -> 2]

{{DevFeature1.13|5}} However, if all the elements are key-value pairs such as those created by ''pair'' or ''tolist'', then this function will invert the effect of ''tolist'' and return the original map which would have produced the input list as output when passed to ''tolist''. If only some elements are key-value pairs, those elements will be directly converted into key-value pairs in the resulting map, while other values will be treated as described above.

If two lists are specified, then the elements of the first one will be used as a keys, and the elements of the second one as a values, when creating an output map. Note that these input lists must be of the same length. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf' ], [10, 20])
</syntaxhighlight>

will result in:

['elf' -> 10, 'dwarf' -> 20]

==== values ====

* values(''map'')

Extracts the values assigned to keys from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
values(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

[50, 60]

=== List-processing Functions ===

This section covers functions that operate on maps or lists by applying one or more formulas in succession to each element. Most return another map or list, <code>reduce</code> instead combines all the elements into a single result.

==== choose ====

* choose(''input'', [''self_name'',] ''formula'')

This function evaluates ''formula'' for each item in the ''input'' (which can be a list or a map). It will return the first item to which ''formula'' gave the highest value. For example:

<syntaxhighlight lang='wfl'>
choose(my_units, level)
</syntaxhighlight>

gives back the unit with the highest level.

The implicit input when evaluating a mapping/filtering function's ''formula'' component will be that specific item under evaluation (in this example one of "my_units"), and it can be explicitly referenced as <code>self</code> when necessary. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

When evaluating a map, we can reference each key by <code>key</code> and each value by <code>value</code>. In this case, the <code>self</code> variable is this key-value pair. For example:

<syntaxhighlight lang='wfl'>
choose(['elf' -> 10, 'dwarf' -> 20 ], value)
</syntaxhighlight>

will return a key-value pair

{key->'dwarf', value->20}

The curly braces are used in output to indicate that this is an object, not a map. It is not valid WFL syntax.

==== filter ====

* filter(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map). It will evaluate to a list or map which only contains items that the ''formula'' was true for. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

<syntaxhighlight lang='wfl'>
filter(my_units, hitpoints < max_hitpoints)
</syntaxhighlight>

will return all of your units which have less than maximum hitpoints. For instance this could be used if looking for candidates for healing.

==== find ====

* find(''input'', [''self_name'',] ''formula'')

This function will run <formula> on each item in the <input> (which can be a list or a map) and will return the first item for which <formula> was true. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. For example:

<syntaxhighlight lang='wfl'>
find(units, type = 'Elvish Archer' )
</syntaxhighlight>

will return the first unit of type 'Elvish Archer'.

==== map ====

* map(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map), and evaluate to a new list or map or a map, which contains the same number of items as in ''input'', with the formulas run on each item. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. When run on a map, the resulting map has the same keys as the input map, but with the values updated to the results of the ''formula''. For example:

<syntaxhighlight lang='wfl'>
map([10,20], self*self)
</syntaxhighlight>

and

<syntaxhighlight lang='wfl'>
map([10,20], 'value', value*value)
</syntaxhighlight>

will both result in [100, 400]. The formula:

<syntaxhighlight lang='wfl'>
map(my_units, hitpoints)
</syntaxhighlight>

will give a list back with the number of hitpoints each unit has. This is more useful in conjunction with other functions.

<syntaxhighlight lang='wfl'>
map(['elf' -> 10, 'dwarf' -> 20 ], value*2)
</syntaxhighlight>

The above will produce ['elf' -> 20, 'dwarf' -> 40]. Note that in case of a map data type, the <code>map</code> function can only modify the value.

<syntaxhighlight lang='wfl'>
map(tomap([3,5,8,8]), value+key*100)
</syntaxhighlight>

The above will produce <code>[3 -> 301, 5 -> 502, 8 -> 801]</code>. This can be used to take a list and make a map containing pairs <code>[element_from_that_list -> f(element_from_that_list,number_of_repetitions_of_that_element_in_that_list)]</code> where <code>f</code> is an arbitrary function.

==== reduce ====

* reduce(''list'', [''identity'', ] ''formula'')

This function will run the ''formula'' on the first and second members of the ''list'', then on the result and the third member and so on until the list is depleted. The final result is then returned. The two variables used in the ''formula'' are always 'a' and 'b'.

For example, <syntaxhighlight lang='wfl' inline>reduce([1,2,3,4], a+b)</syntaxhighlight> returns <code>10</code> and <syntaxhighlight lang='wfl' inline>reduce([9,4,8,2], 10*a+b)</syntaxhighlight> returns <code>9482</code>.

{{DevFeature1.13|5}} The new ''identity'' argument specifies the starting value (which is null or 0 by default). If ''list'' is empty, then ''identity'' is returned. Otherwise, the list will be considered as if ''identity'' were an extra first element. For example, to calculate the product of a list of numbers, you might do something like this:
<syntaxhighlight lang='wfl'>
reduce(your_list, 1, a * b)
</syntaxhighlight>

This will return 1 if the list is empty, as expected - the product of no numbers is 1. If the list is not empty, adding 1 to the list will have no effect, since it is the multiplicative identity.

==== take_while ====

{{DevFeature1.13|5}}

* take_while(''list'', ''formula'')

Evaluates the ''formula'' for each element of the ''list'' until it finds one for which it evaluates to false, then returns a list of all elements up to but not including that element. For example:

<syntaxhighlight lang='wfl'>
take_while([1,5,3,6,3,7,9,5,6,4,12,2,53,2,1], self < 10)
</syntaxhighlight>

returns the list <code>[1,5,3,6,3,7,9,5,6,4]</code>.

==== zip ====

{{DevFeature1.13|5}}

* zip(''list1'', ... , ''listN'')
* zip(''list of lists'')

Takes a list of lists and generates a new list of lists such that list ''n'' contains element ''n'' of each of the original lists, in order. If the lists are not all of the same length, it treats them as if they were padded on the end with null values so that they are all the length of the longest list.

<syntaxhighlight lang='wfl'>
zip([1,2,3],[4,5,6])
zip([1,4],[2,5],[3,6])
</syntaxhighlight>

return <code>[[1,4],[2,5],[3,6]]</code> and <code>[[1,2,3],[4,5,6]]</code>, respectively.

=== Location Functions ===

Functions for working with locations on a hex map.

==== adjacent_locs ====

{{DevFeature1.13|9}}

* adjacent_locs(''center'')

Returns a list of all locations adjacent to the specified location. When called from a formula with access to the game state, it automatically excludes locations that don't exist on the map. Otherwise, it operates as if on an infinite map. This means you should generally not expect the returned list to contain exactly 6 elements.

==== are_adjacent ====

{{DevFeature1.13|9}}

* are_adjacent(''loc1'', ''loc2'')

Check if two locations are adjacent. Returns 1 (true) or 0 (false).

==== direction_from ====

{{DevFeature1.13|9}}

* direction_from(''start'', ''direction'', [''distance''])

Returns the hex reached by travelling in the specified direction from a starting hex for a certain distance (default 1 hex).

==== distance_between ====

{{DevFeature1.13|5}}

* distance_between(''start'', ''end'')

Returns the distance between the locations ''start'' and ''end'', which must be location objects such as those created by <code>loc()</code>.

'''Note:''' This function was already available in FormulaAI prior to 1.13.5; however, from 1.13.5 onward it is available to all formulas.

==== loc ====

* loc(''x'', ''y'')

Creates and returns a location object with the specified coordinates. If assigned to a variable ''pos'' (eg with a <code>where</code> clause), the individual coordinates can be accessed as <code>pos.x</code> and <code>pos.y</code>.

==== locations_in_radius ====

{{DevFeature1.13|9}}

* locations_in_radius(''center'', ''radius'')

Returns a list of all locations within a given radius of the specified center hex.
Only locations on the map will be returned.

==== relative_dir ====

{{DevFeature1.13|9}}

* relative_dir(''loc1'', ''loc2'')

Returns the direction you need to travel to progress from one location to another. The returned location is one of the six possible directions on the Wesnoth hex map, or an empty string if both locations are the same.

==== rotate_loc_around ====

{{DevFeature1.13|9}} but returns wrong result until {{DevFeature1.19|2}}

* rotate_loc_around(''center'', ''loc'', ''angle'')

Rotates a location around a given center to produce a new location. The angle is an integer between -6 and 6, which can be understood as a multiple of 60 degrees.

=== Miscellaneous Functions ===

Some functions really don't fit into any category. They are all listed here.

==== null ====

* null([''arguments''])

Evaluates each of its arguments (if any) in order, then returns null. Since formulas generally do not have side-effects, there is little point in specifying any arguments unless you are writing AI code (where several functions do have side-effects).

==== pair ====

{{DevFeature1.13|5}}

* pair(''key'', ''value'')

Creates a key-value pair object, the same as those created by the ''tolist'' function.

==== reverse ====

{{DevFeature1.13|5}}

* reverse(''string or list'')

Returns the input string or list backwards.

==== type ====

{{DevFeature1.13|5}}

* type(''anything'')

Returns the type of its input as a string. Possible results are:

* <code>'integer'</code>
* <code>'decimal'</code>
* <code>'string'</code>
* <code>'list'</code>
* <code>'map'</code>
* <code>'null'</code>
* <code>'object'</code>

==== get_palette ====

{{DevFeature1.19|4}}

* get_palette(''name'')

Returns a list of colours that make up the named palette. Palettes are defined by a '''[color_palette]''' tag, usually in the [[GameConfigWML#Color_Palettes|game config]]. The palettes defined in core Wesnoth are '''magenta''', '''flag_green''', and '''ellipse_red'''. In addition to defined palettes, several hard-coded palettes are available by name. They are '''red_green_scale''', '''red_green_scale_text''', '''blue_white_scale''', and '''blue_white_scale_text'''. These are also defined in the game config, but not with a '''[color_palette]''' tag.

=== Debugging Functions ===

There are also a few functions that can be useful for debugging formulas, for example by displaying intermediate results to the screen. Note that this breaks the general rule that functions do not have side-effects.

==== debug ====

* debug([''formula''])

Starts a GUI formula AI debugger when evaluating a formula. It takes a formula, evaluates it and returns the result unchanged. '''Note:''' this does not appear to work in 1.13.3.

{{DevFeature1.13|5}} The formula allows you to step through the formula one operation at a time, viewing the current stack and execution trace. As of 1.13.5, you need to enable [[CommandMode|debug mode]] to use the debugger; otherwise, it will simply be skipped.

==== debug_print ====

'''you need to enable formula log (--log-info='scripting/formula') to see the result of this call'''

* debug_print([''explanation'' ,] ''formula'' )

This function can be used for debugging a formula. It takes a ''formula'', writes its result to the console, and returns it unchanged. For example:

<syntaxhighlight lang='wfl'>
debug_print([1, 2, 3])
</syntaxhighlight>

will result in printing to the console

[1, 2, 3]

and returning the same.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_print'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_print('My array: ', [1, 2, 3])
</syntaxhighlight>

will write in the console:

My array: [1, 2, 3]

and return

[1, 2, 3]

==== debug_profile ====

* debug_profile(''formula'' [, ''explanation''])

Evaluates the formula 1000 times and prints (as with debug_print) a number indicating the average time required to evaluate the formula. Mainly intended for internal testing, but could occasionally be useful for people working with complicated formulas. The optional ''explanation'' argument is used in the same way as in debug_print.

==== debug_float ====

* debug_float(''location'', [''explanation'',] ''formula'' )

This function can be used for debugging a formula. It takes a formula, floats a label containing the result on the hex specified (in the same way damage is displayed) and returns it unchanged. Note that the ''location'' here is an object type; it can be created with the <code>[[#loc|loc()]]</code> function. For example:

<syntaxhighlight lang='wfl'>
debug_float(me.loc, me.id)
</syntaxhighlight>

will make a label containing the id of the unit ''me'' float over the unit.

Return value is also the unit id.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_float'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_float( me.loc, 'id: ', me.id )
</syntaxhighlight>

will float the following label

id: unit_id

and return the unit id.

==== dir ====

* dir(''object'')

This function return a list of all attributes in ''object''. For example:

<syntaxhighlight lang='wfl'>
dir(my_leader)
</syntaxhighlight>

will result in the following output:

[ 'x', 'y', 'loc', 'id', 'type', 'name', 'leader', 'undead', 'traits', 'attacks', 'abilities', 'hitpoints',
'max_hitpoints', 'experience', 'max_experience', 'level', 'total_movement', 'movement_left', 'attacks_left',
'side', 'states', 'cost', 'usage', 'vars']

This command is useful in the formula command line, to get information about the attributes of different types of data.

=== Game State Functions ===

These are functions that access the game state. Therefore, they are not available in all formulas, as described above.

==== base_tod_bonus ====

* base_tod_bonus([''loc'', [''turn'']])

Evaluates the base time-of-day bonus, excluding the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== chance_to_hit ====

* chance_to_hit(''unit'', ''location or terrain'')

Calculates the base chance for the unit to be hit if it moved to the given location or terrain. This is essentially the inverse of its defense. It is returned as an integer between 0 and 100.

==== defense_on ====

* defense_on(''unit'', ''location or terrain'')

Calculates the defense that the unit would have if it moved to the given location or terrain. It is returned as an integer between 0 and 100.

==== enemy_of ====

* enemy_of(''self'', ''other'')

Determines whether two units are enemies. Returns 1 (true) or 0 (false).

==== get_unit_type ====

* get_unit_type(''id'')

Returns an object describing the specified unit type, or null if no such unit type exists. A unit type object has many of the same keys as a unit, excluding those that are expected to change over time such as <tt>hitpoints</tt> or <tt>name</tt>.

==== jamming_cost ====

* jamming_cost(''unit or unit type'', ''location or terrain'')

Calculates the jamming cost for the unit to block vision on the given location terrain.

==== movement_cost ====

* movement_cost(''unit or unit type'', ''location or terrain'')

Calculates the movement cost for the unit to enter the given location or terrain.

==== resistance_on ====

* resistance_on(''unit'', ''location'', ''type'', [''attacker''])

Calculates the unit's resistance to the given damage type when standing on the specified location. If specified, the ''attacker'' parameter should be 1 to indicate that the unit is the attacker, or 0 to indicate that it is the defender, as this status can affect resistances. By default, it is assumed to be the defender.

This is returned not as the raw resistance set in WML, but the actual resistance that the player sees, so it ranges between -100 and 100.

==== tod_bonus ====

* tod_bonus([''loc'', [''turn'']])

Evaluates the final time-of-day bonus, accounting for the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== unit_at ====

* unit_at(''location'')

Returns the unit on the given location, or null if there is no unit there.

==== vision_cost ====

* vision_cost(''unit or unit type'', ''location or terrain'')

Calculates the vision cost for the unit to see through the given location or terrain.

DirectActionsWML

2025-01-13T19:57:56Z

Laela: /* [modify_unit] */ type and experience

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

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

The following tags are actions:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their current value. 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).

Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''. Setting value, including empty string, of ''type'' acts as shortcut of ''experience="$this_unit.max_experience"''.

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

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

=== [petrify] ===

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

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

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

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

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

Removes an object from matching units.

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

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

Note that [remove_object] works the following way:

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

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

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

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the trait to be removed. See [[UnitsWML#.5Btrait.5D|[trait]]].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{DevFeature1.15|0}}
In a '''capture'''/'''moveto''' [event], interrupt the attack.

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

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

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount. When harming multiple units, the special variable '''$this_unit''' can be used to access the current unit being harmed. This obviously does not work inside the filters though, as they give '''$this_unit''' a different meaning.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': (default yes) If there is a harmer, experience will be attributed similar to regular combat. Can take list of values. When any value is provided, all unspecified experience types default to not giving experience. Supported values: {{DevFeature1.17|25}} until that version only experience=yes and experience=no are supported
** no - none of involved units get any experience (this value only works if it is the only value in list)
** kill - the harming unit receives experience based on level of harmed unit in attack which kills harmed unit
** attack - the harming unit receives experience based on level of harmed unit in attack which does not kill harmed unit, or in attack which kills harmed unit while kill experience is disabled
** defend - the unit being harmed receives experience based on level of harming unit in attack which does not kill harmed unit
** fight - short form of experience=attack,defend
** yes - short form of experience=kill,attack,defend
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

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

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

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

=== [remove_time_area] ===

{{DevFeature1.13|2}}

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

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

=== [replace_map] ===

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement. ('''NB''': due to https://github.com/wesnoth/wesnoth/issues/5757 this attribute is ignored in versions 1.16.*. The fix was delivered in 1.17.* but wasn't backported due to backward-compatibility requirements)

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

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

=== [do_command] ===

{{DevFeature1.13|0}}

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

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

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

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

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

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

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

=== [set_achievement] ===

{{DevFeature1.17|13}}

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

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

=== [set_sub_achievement] ===

{{DevFeature1.17|17}}

Sets the specified sub-achievement as completed.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

=== [progress_achievement] ===

{{DevFeature1.17|13}}

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

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

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

== See Also ==

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

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

EventWML

2025-01-06T17:37:45Z

Laela: /* id */ when event has no id, but is in one [unit_type], there is no duplication, but when same event is provided by ability to multiple types, id is useful

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the term "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
<syntaxhighlight lang='wml'>
name=<value>
</syntaxhighlight>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

<syntaxhighlight lang='wml'>
name=attacker misses,defender misses
</syntaxhighlight>

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

All predefined event types are listed below, along with a description of when this value will cause the event to be triggered, in the [[#Predefined_Events_Without_Filters|Predefined Events Without Filters]] and [[#Predefined_Events_With_Filters|Predefined Events With Filters]] sections. Any value ''not'' listed there is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

Spaces in event names can be interchanged with ''underscores'' (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

==== Variables in the name ====

If the name contains variables, they will be substituted each time the event is triggered. For example, '''name=turn $disaster_turn''' will only trigger if the turn number is currently equal to whatever number is stored in the variable '''$disaster_turn'''; updating the variable will adjust the turn that the event triggers on. However, if the variable contents contains a comma, it won't be parsed after substitution. Since an event name can't contain a comma, this means the event will never trigger.

{{DevFeature1.17|6}}

Commas resulting from variable substitution are now parsed. If you write '''name=$important_event''' and the variable '''$important_event''' contains the text "capture,die", the event will trigger on either a death or a village capture.

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives. Also, custom events come very handy in [[Wml_optimisation]].

Example:
<syntaxhighlight lang='wml'>
# The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

# This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# And now a fire_event tag is used to trigger the previously defined event. To use
# "speaker=unit" in the fired event, it's also necessary to specify the [primary_unit].
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]
</syntaxhighlight>

You can have more code after the '''[fire_event]''', which will run after the fired event has happened.
Example:
<syntaxhighlight lang='wml'>
# This is a standard recall event that triggers whenever a unit is recalled by side 1
[event]
name=recall
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# Fire the custom event, exactly as the in recruit event
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# After that event has happened, the remaining code in this event is run
[message]
speaker=second_unit
message=_ "Glad to have you back"
[/message]
# As a result, every time side 1 recalls a unit, the recalled unit says
# "Reporting for duty!", and the leader replies "Glad to have you back"
[/event]
</syntaxhighlight>

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is usually desired to avoid duplicates in case same [event] is used in multiple [unit_type] or ability/weapon special.

==== remove ====
: Removes an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if yes, does the same as a [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] with the same id= value, and the other attributes of this event tag are ignored.

{{DevFeature1.13|0}} May be a comma separated list.

{{DevFeature1.15|7}} Prints a deprecation warning recommending to use [remove_event] instead.

==== priority ====
: {{DevFeature1.17|20}} If several '[event]' tags have the same name, then any with a high priority value will be triggered before events with a lower priority value. Negative numbers are also supported, to run after events without a priority (as the attribute defaults to zero). For events with equal priority, the order is determined by the order in which the events were added.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special_id''': filter on the attack's weapon special id.
:* '''special_type''': filter on the attack's weapon special type.
:* {{DevFeature1.17|15}} '''special_id_active''': filter on the attack's weapon special id active(encoded in [specials] or [abilities] tags).
:* {{DevFeature1.17|15}} '''special_type_active''': filter on the attack's weapon special type active(encoded in [specials] or [abilities] tags).

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== [insert_tag] ====
: An '''[insert_tag]''' that expands to any of the above filter tags will result in the filter being loaded from the variable each time the game checks if the event should fire. This can result in the event's filter varying from turn to turn.

==== filter_formula ====
:{{DevFeature1.17|6}}
: Similar to [filter_condition], but the condition is expressed in [[Wesnoth Formula Language]]. The formula has access to the following keys:
:*Event information:
:**'''event''' - the event name
:**'''event_id''' - the event's unique ID
:**'''event_data''' - additional information specific to the event, such as owner_side or damage_inflicted, or anything passed in '''[fire_event][data]'''.
:**'''loc''', '''unit''' - primary event location and unit
:**'''second_loc''', '''second_unit''' - secondary event location and unit
:**'''weapon''', '''second_weapon''' - primary and secondary weapon
:*Gamestate information:
:**'''turn_number'''
:**'''time_of_day''' - the time of day ID
:**'''side_number''' - currently active side
:**'''sides''' - a list of all sides
:**'''units''' - a list of all units on the map
:**'''map''' - the entire game map as a two-dimensional array

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution_2|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]]. Actions can also be dynamically inserted via '''[insert_tag]'''.

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* unit hits
* unit misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
* {{DevFeature1.13|10}} victory
* {{DevFeature1.13|10}} defeat
* {{DevFeature1.13|0}} scenario_end
The following are not synced:
* select
* preload
* victory {{DevFeature1.13|10}} local_victory
* defeat {{DevFeature1.13|10}} local_defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}
</syntaxhighlight>

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef
</syntaxhighlight>

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

<syntaxhighlight lang='wml'>
[event]
id=doubler_event
remove=yes
[/event]
</syntaxhighlight>

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== Predefined Events Without Filters ==

These events do not take filter parameters (except [filter_condition] which works for all events).

=== preload ===

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' If a game is started, saved, and then reloaded, the preload event will fire two times while playing. However, it will only fire once when viewing the replay. If the preload event alters the gamestate the second time it fired while playing (when loading the saved game) then it can result in Out Of Sync errors.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

=== prestart ===

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== start ===

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== new turn ===

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

=== turn end ===

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

=== turn ''X'' end ===

Triggers at the end of turn ''X''.

=== side turn ===

Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

=== ai turn ===

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event can break replays if it is used improperly. The ai turn event does not fire during replays. The intention is only to guide the AI to make choices (movements, attacks) which are then saved to the replay.''

=== turn refresh ===

Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status. WML variable '''side_number''' holds the number of this side.

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

=== turn ''X'' ===

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

=== side ''X'' turn ''Y'' ===

This event triggers at the start of turn ''Y'' of side X

=== side ''X'' turn ===

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn ''X'' ===

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side X turn Y refresh ===

This event triggers at the turn refresh for side X on turn Y

=== side ''X'' turn refresh ===

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== turn ''X'' refresh ===

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn end ===

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

=== time over ===

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

=== enemies defeated ===

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

=== local_victory ===

In Wesnoth 1.12 and earlier, the event described here is '''victory''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_victory'''.

This event will be fired at the end of a scenario, if the player's side won. If it fires as a result of an '''[endlevel]''' tag, the event is processed before the line after the '''[endlevel]]''' tag. The event is not synchronized, as in networked mp it is possible to have different results for different players.

=== local_defeat ===

In Wesnoth 1.12 are earlier, the event described here is '''defeat''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_defeat'''.

Functions identically to '''local_victory''', except that the player's side lost.

=== victory ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''victory''' event is equivalent to 1.14's '''local_victory'''.

This event will be fired at the end of a scenario, if the game will proceed to the next scenario. In multiplayer, this means that it will fire on all players' clients, even for players who received a '''local_defeat''', as long as the game continues to the next scenario. This event is synchronized.

It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":next_level" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign.

=== defeat ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''defeat''' event is equivalent to 1.14's '''local_defeat'''.

This event will be fired at the end of a scenario, if the game resulted in a game-over other than victoriously reaching the end of a campaign (including single-scenario campaigns). Synchronization (including bug #4667) is the same as '''victory'''.

=== scenario_end ===

{{DevFeature1.13|10}} This event fires immediately after '''victory''' or '''defeat'''; it is synchronized, but is also affected by bug #4667.

Note: in 1.13.0 - 1.13.9 this event was added as a synchronized alternative to the events that are, since 1.13.10, called local_victory or local_defeat.

== Predefined Events With Filters ==

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables '''unit''' and '''second_unit''' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, unit_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

=== moveto ===

Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' $x2 and $y2 refer to the hex the unit came from.

=== sighted ===

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away. You may want to use [filter_second] in order to restrict a sighted event in a single player scenario to only being triggered by the player and not by other non-allied sides.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

=== enter_hex ===

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). In Wesnoth 1.12, the movement will be interrupted, stopping the unit where it is; this behavior can be avoided by using the {{tag|DirectActionsWML|allow_undo}} tag or `NO_INTERRUPT_NO_UNDO` macro. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

'''Note:''' At the time of writing (7ca5a0df, just before 1.13.11), if the hex is occupied then $unit contains the occupying unit, not the moving unit.

'''Note:''' At the time of writing (1.16.2), if the hex is occupied then $unit does contain the moving unit.

=== exit_hex ===

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

=== pre attack {{DevFeature1.17|7}}===

Similar to '''attack''', but is triggered before calculating the number of attacks and the movement of the unit. Can be used for modifications, which affect these values.

=== attack ===

Triggers when the primary unit attacks the secondary unit. Variables $weapon and $second_weapon contain weapons used for this attack by primary and secondary units respectively for all attack-related events (attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath).

=== attack end ===

Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

=== attacker hits ===

Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

=== attacker misses ===

Same as ''attacker hits'', but is triggered when the attacker misses.

=== defender hits ===

Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

=== defender misses ===

Same as ''defender hits'', but is triggered when the defender misses.

=== unit hits {{DevFeature1.19|2}} ===

Triggers when the the primary unit (either attacker or defender) hits the secondary unit (the other). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the primary unit.

Compared to ''defender hits'', primary and secondary units are swapped.

=== unit misses {{DevFeature1.19|2}} ===

Same as ''unit hits'', but is triggered when the unit misses.

=== petrified ===
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''petrifies'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

=== last breath ===

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

=== die ===

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want the primary unit to make a final [message], use name=last_breath, see above.

=== capture ===

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

=== recruit ===

Triggers when the primary unit is recruited (by the secondary unit). (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

=== prerecruit ===

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

=== recall ===

Triggers after the primary unit is recalled (by the secondary unit).

=== prerecall ===

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

=== advance ===

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

=== pre advance ===

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

Care needs to be taken when tags that may trigger advancement themselves are used in this event. For example '''[transform_unit]''', '''[unstore_unit]''', '''[modify_unit]''' etc.

=== post advance ===

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

=== select ===

Triggers when the primary unit is selected. Prior to version 1.11, this also triggered when a move was interrupted, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

=== menu item ''X'' ===

Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== unit placed {{DevFeature1.13|3}}===

Triggers when the primary unit is placed on the map, regardless of method. This includes but might not be limited to:
* Leaders and units placed in side definitions (fired once for every unit right before prestart events)
* Recruited and recalled units
* Units placed on the map with the [unit] tag ('''not''' units created directly onto a recall list or variable)
* Units placed by the wesnoth.put_unit() Lua function
* Units placed by :to_map in Lua (which is a shortcut for the above)
* Units created via debug mode
* Units created by plague
* Every use of [unstore_unit], when ''fire_event'' is set to ''yes'' (default is ''no'')
* Units moved on map with [move_unit] before {{DevFeature1.15|8}}
* Units matching the filter of [petrify], [unpetrify] or [harm_unit] before {{DevFeature1.15|8}}
* Units who receive a bonus from the feeding ability every time except the first, before {{DevFeature1.15|8}}
This event is solely intended for special cases where no other event types suffice, for example if you must immediately apply a modification to every unit that ever appears. The event does '''not''' keep track of which units it has previously fired for, but can fire an unlimited number of times for the same unit as long the unit is "placed" several times and the event filter doesn't prevent it.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

<syntaxhighlight lang='wml'>
[event]
name=last breath
[message]
speaker=second_unit
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker=unit
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]
</syntaxhighlight>

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]
</syntaxhighlight>

An equivalent way of doing this would be to create a single moveto event with a '''[filter_condition]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[filter_condition]''' statements. Using '''[if]''' tags is also an option especially if your event has '''first_time_only=yes'''.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]
</syntaxhighlight>

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.

<syntaxhighlight lang='wml'>
[event] # parent
name=turn 2
# delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event] # child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event] # great-grandchild
name=turn 5
{DEBUG_MSG $turn_number} # output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]
</syntaxhighlight>

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

UnitTypeWML

2025-01-05T15:36:17Z

Laela: /* Unit Type */ image_icon in recruit #9702

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences. WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub. {{DevFeature1.17|26}} canrecruit=yes is now supported with "misc/ellipse-hero", since "misc/ellipse-hero-leader" has been added in [https://github.com/wesnoth/wesnoth/pull/8375 8375].
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the recruit dialog, attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:
** ''scout'': Fast, mobile unit meant for exploration and village grabbing.
** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.
** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.
** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.
** ''healer'': Specialty 'heals' or 'cures'.
:Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities|WML Abilities]]. {{DevFeature1.19|4}} Abilities support [event].

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

LuaAPI/wesnoth/sides

2024-10-24T13:22:16Z

Laela: /* wesnoth.sides.set_id */

{{DevFeature1.15|3}}

The sides module is only available in the game. It is not available to plugins or map generators.

All functions taking a side on this page (except '''get''') will accept either the integer index of the side or the [[LuaAPI/types/side|side proxy userdata]] (as returned by '''get''' or '''find''').

== Functions ==

=== wesnoth.sides.is_enemy ===

* {{LuaGameOnly}} '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
* {{LuaGameOnly}} ''side1'':'''is_enemy'''(''side2'') → ''boolean''

Returns true if side 1 is an enemy of side 2, false otherwise.

<syntaxhighlight lang=lua>
local enemy_flag = wesnoth.sides.is_enemy(1, 3)
</syntaxhighlight>

=== wesnoth.sides.matches ===

* {{LuaGameOnly}} '''wesnoth.sides.match_side'''(''side'', ''filter'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''matches'''(''filter'') → ''boolean''

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

<syntaxhighlight lang=lua>
wesnoth.message(tostring(wesnoth.sides[1]:matches{ wml.tag.has_unit { type = "Troll" } }))
</syntaxhighlight>

=== wesnoth.sides.set_id ===

* {{LuaGameOnly}} '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
* {{LuaGameOnly}} ''side'':'''set_id('''''flag'', ''color'')

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes. Both attributes can also be changed through the [[LuaAPI/types/side|side proxy]] attributes, but changing both at the same time is slightly more efficient.

=== wesnoth.sides.place_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.place_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''place_fog'''(''locations'', [''permanent''])

Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, but not a list of such. The ''permanent'' argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.

=== wesnoth.sides.remove_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''remove_fog'''(''locations'', [''permanent''])

Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, though not a list of such. The ''permanent'' argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.

<syntaxhighlight lang=lua>
wesnoth.sides.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.sides.remove_fog(wesnoth.sides[1], { {5, 5} }) -- removes fog for first side on 5,5
wesnoth.sides[1]:remove_fog(wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5
</syntaxhighlight>

=== wesnoth.sides.is_fogged ===

* {{LuaGameOnly}} '''wesnoth.sides.is_fogged'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_fogged'''(''side'') → ''boolean''

Check if a specific location is under fog for the given side.

=== wesnoth.sides.place_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.place_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''place_shroud'''(''locations'')

Places shroud on the specified hexes for the chosen side. This merges the new shroud with any existing shroud on the map. The locations must be passed as an array of pairs, but if you want to merge in a shroud data string, you can parse it first with [[../map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]].

=== wesnoth.sides.override_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.override_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''override_shroud'''(''locations'')

Clears shroud on the specified hexes for the chosen side. This replaces any existing shroud data on the map – after calling `override_shroud`, the locations passed will be the ''only'' unshrouded locations.

=== wesnoth.sides.remove_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''remove_shroud'''(''locations'')

Unshrouds the specified hexes for the chosen side.

=== wesnoth.sides.is_shrouded ===

* {{LuaGameOnly}} '''wesnoth.sides.is_shrouded'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_shrouded'''(''location'') → ''boolean''

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

=== wesnoth.sides.switch_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.switch_ai'''(''side'', ''file'')
* {{LuaGameOnly}} ''side'':'''switch_ai'''(''file'')

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

=== wesnoth.sides.append_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.append_ai'''(''side'', ''params'')
* {{LuaGameOnly}} ''side'':'''append_ai'''(''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.sides.add_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''add_ai_component'''(''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.sides.change_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''change_ai_component'''(''path'', ''component'')

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

=== wesnoth.sides.delete_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
* {{LuaGameOnly}} ''side'':'''delete_ai_component'''(''path'')

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

=== wesnoth.sides.get ===

* {{LuaGameOnly}} '''wesnoth.sides.get'''(''id'') → ''[[LuaAPI/types/side|side proxy]]''
* {{LuaGameOnly}} '''wesnoth.sides'''[''id''] → ''[[LuaAPI/types/side|side proxy]]''
* {{LuaGameOnly}} #'''wesnoth.sides''' → ''number of sides''

Returns the specified [[LuaAPI/types/side|side]], which must be a valid integer side ID.

=== wesnoth.sides.find ===

* {{LuaGameOnly}} '''wesnoth.sides.find'''(''filter'') → ''array of [[LuaAPI/types/side|sides]]''

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].

<syntaxhighlight lang=lua>
--set gold to 0 for all sides with a leader
local sides = wesnoth.sides.find{ wml.tag.has_unit { canrecruit = true } }
for i,v in ipairs(sides) do
v.gold = 0
end
</syntaxhighlight>

=== wesnoth.sides.iter ===

{{DevFeature1.17|?}}

* {{LuaGameOnly}} '''wesnoth.sides.iter'''(''filter?'') → ''iterator'' ⇒ ''[[LuaAPI/types/side|side]]''

Iterate over all sides, or sides that match a filter.

=== wesnoth.sides.create ===

* {{LuaGameOnly}} '''wesnoth.sides.create'''() → ''new side number''

Adds a new blank side to the end of the scenario sides list and returns its number.

=== wesnoth.sides.debug_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.debug_ai'''(''side'') → ''ai context table''
* {{LuaGameOnly}} ''side'':'''debug_ai'''() → ''ai context table''

Returns the AI context table for the given side. This function only exists in debug mode, and only if Wesnoth is launched with the <tt>--debug-lua</tt> command-line argument. This allows you to inspect all the AI internals for that side, including the AI component tree and the AI module (which is instanced per side). You can also execute individual components by calling their execution or evaluation functions.

The returned table contains the following keys:

* '''ai''': The [[LuaAPI/ai|ai]] module bound to this side. Each side has a separate instance of the AI module.
* '''components''': The AI components tree. Each component in this tree potentially has the following subkeys:
** '''engine''', '''id''', '''name''': The basic info about the component - its name and ID and the engine it runs on.
** '''stage''', '''candidate_action''': An array of subcomponents of the specified type.
** '''exec''': For stages or candidate actions, a function which, when called, executes it immediately (and synchronously). Prefer calling this with the :lua command rather than from the Lua console.
* '''engine''': The complete contents of the Lua [engine] tag.
* '''params''': The contents of the [args] tag from the Lua [engine] tag.
* '''data''': A WML table containing persistent data used by the AI. This data is serialized as part of the Lua [engine] tag.
* '''update_self''': The function defined in the Lua [engine] tag. Called as <syntaxhighlight lang=lua inline>update_self(params, data)</syntaxhighlight>.

The above list covers only the most useful keys and is not exhaustive.

Some examples:
<syntaxhighlight lang='lua'>
wesnoth.debug_ai(2).ai -- returns the AI module bound to side 2
wesnoth.debug_ai(2).stage[another_stage].exec() -- executes the "another_stage" stage for side 2
wesnoth.debug_ai(2).ai.aspects.aggression -- returns the current value of the aggression aspect of the AI on side 2
</syntaxhighlight>

'''Note:''' Do not rely on the precise structure of the AI context table. It is documented here as an aid to debugging, but it is ''not'' public API and may change without warning or deprecation.

[[Category:Lua Reference]]

LuaAPI/wesnoth/sides

2024-10-24T13:21:35Z

Laela:

{{DevFeature1.15|3}}

The sides module is only available in the game. It is not available to plugins or map generators.

All functions taking a side on this page (except '''get''') will accept either the integer index of the side or the [[LuaAPI/types/side|side proxy userdata]] (as returned by '''get''' or '''find''').

== Functions ==

=== wesnoth.sides.is_enemy ===

* {{LuaGameOnly}} '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
* {{LuaGameOnly}} ''side1'':'''is_enemy'''(''side2'') → ''boolean''

Returns true if side 1 is an enemy of side 2, false otherwise.

<syntaxhighlight lang=lua>
local enemy_flag = wesnoth.sides.is_enemy(1, 3)
</syntaxhighlight>

=== wesnoth.sides.matches ===

* {{LuaGameOnly}} '''wesnoth.sides.match_side'''(''side'', ''filter'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''matches'''(''filter'') → ''boolean''

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

<syntaxhighlight lang=lua>
wesnoth.message(tostring(wesnoth.sides[1]:matches{ wml.tag.has_unit { type = "Troll" } }))
</syntaxhighlight>

=== wesnoth.sides.set_id ===

* {{LuaGameOnly}} '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
* {{LuaGameOnly}} ''side'':'''set_id('''''flag'', ''color'')

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes. Both attributes can also be changed through the side proxy attributes, but changing both at the same time is slightly more efficient.

=== wesnoth.sides.place_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.place_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''place_fog'''(''locations'', [''permanent''])

Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, but not a list of such. The ''permanent'' argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.

=== wesnoth.sides.remove_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''remove_fog'''(''locations'', [''permanent''])

Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, though not a list of such. The ''permanent'' argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.

<syntaxhighlight lang=lua>
wesnoth.sides.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.sides.remove_fog(wesnoth.sides[1], { {5, 5} }) -- removes fog for first side on 5,5
wesnoth.sides[1]:remove_fog(wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5
</syntaxhighlight>

=== wesnoth.sides.is_fogged ===

* {{LuaGameOnly}} '''wesnoth.sides.is_fogged'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_fogged'''(''side'') → ''boolean''

Check if a specific location is under fog for the given side.

=== wesnoth.sides.place_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.place_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''place_shroud'''(''locations'')

Places shroud on the specified hexes for the chosen side. This merges the new shroud with any existing shroud on the map. The locations must be passed as an array of pairs, but if you want to merge in a shroud data string, you can parse it first with [[../map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]].

=== wesnoth.sides.override_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.override_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''override_shroud'''(''locations'')

Clears shroud on the specified hexes for the chosen side. This replaces any existing shroud data on the map – after calling `override_shroud`, the locations passed will be the ''only'' unshrouded locations.

=== wesnoth.sides.remove_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''remove_shroud'''(''locations'')

Unshrouds the specified hexes for the chosen side.

=== wesnoth.sides.is_shrouded ===

* {{LuaGameOnly}} '''wesnoth.sides.is_shrouded'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_shrouded'''(''location'') → ''boolean''

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

=== wesnoth.sides.switch_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.switch_ai'''(''side'', ''file'')
* {{LuaGameOnly}} ''side'':'''switch_ai'''(''file'')

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

=== wesnoth.sides.append_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.append_ai'''(''side'', ''params'')
* {{LuaGameOnly}} ''side'':'''append_ai'''(''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.sides.add_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''add_ai_component'''(''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.sides.change_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''change_ai_component'''(''path'', ''component'')

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

=== wesnoth.sides.delete_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
* {{LuaGameOnly}} ''side'':'''delete_ai_component'''(''path'')

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

=== wesnoth.sides.get ===

* {{LuaGameOnly}} '''wesnoth.sides.get'''(''id'') → ''[[LuaAPI/types/side|side proxy]]''
* {{LuaGameOnly}} '''wesnoth.sides'''[''id''] → ''[[LuaAPI/types/side|side proxy]]''
* {{LuaGameOnly}} #'''wesnoth.sides''' → ''number of sides''

Returns the specified [[LuaAPI/types/side|side]], which must be a valid integer side ID.

=== wesnoth.sides.find ===

* {{LuaGameOnly}} '''wesnoth.sides.find'''(''filter'') → ''array of [[LuaAPI/types/side|sides]]''

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].

<syntaxhighlight lang=lua>
--set gold to 0 for all sides with a leader
local sides = wesnoth.sides.find{ wml.tag.has_unit { canrecruit = true } }
for i,v in ipairs(sides) do
v.gold = 0
end
</syntaxhighlight>

=== wesnoth.sides.iter ===

{{DevFeature1.17|?}}

* {{LuaGameOnly}} '''wesnoth.sides.iter'''(''filter?'') → ''iterator'' ⇒ ''[[LuaAPI/types/side|side]]''

Iterate over all sides, or sides that match a filter.

=== wesnoth.sides.create ===

* {{LuaGameOnly}} '''wesnoth.sides.create'''() → ''new side number''

Adds a new blank side to the end of the scenario sides list and returns its number.

=== wesnoth.sides.debug_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.debug_ai'''(''side'') → ''ai context table''
* {{LuaGameOnly}} ''side'':'''debug_ai'''() → ''ai context table''

Returns the AI context table for the given side. This function only exists in debug mode, and only if Wesnoth is launched with the <tt>--debug-lua</tt> command-line argument. This allows you to inspect all the AI internals for that side, including the AI component tree and the AI module (which is instanced per side). You can also execute individual components by calling their execution or evaluation functions.

The returned table contains the following keys:

* '''ai''': The [[LuaAPI/ai|ai]] module bound to this side. Each side has a separate instance of the AI module.
* '''components''': The AI components tree. Each component in this tree potentially has the following subkeys:
** '''engine''', '''id''', '''name''': The basic info about the component - its name and ID and the engine it runs on.
** '''stage''', '''candidate_action''': An array of subcomponents of the specified type.
** '''exec''': For stages or candidate actions, a function which, when called, executes it immediately (and synchronously). Prefer calling this with the :lua command rather than from the Lua console.
* '''engine''': The complete contents of the Lua [engine] tag.
* '''params''': The contents of the [args] tag from the Lua [engine] tag.
* '''data''': A WML table containing persistent data used by the AI. This data is serialized as part of the Lua [engine] tag.
* '''update_self''': The function defined in the Lua [engine] tag. Called as <syntaxhighlight lang=lua inline>update_self(params, data)</syntaxhighlight>.

The above list covers only the most useful keys and is not exhaustive.

Some examples:
<syntaxhighlight lang='lua'>
wesnoth.debug_ai(2).ai -- returns the AI module bound to side 2
wesnoth.debug_ai(2).stage[another_stage].exec() -- executes the "another_stage" stage for side 2
wesnoth.debug_ai(2).ai.aspects.aggression -- returns the current value of the aggression aspect of the AI on side 2
</syntaxhighlight>

'''Note:''' Do not rely on the precise structure of the AI context table. It is documented here as an aid to debugging, but it is ''not'' public API and may change without warning or deprecation.

[[Category:Lua Reference]]

LuaAPI/wesnoth/sides

2024-10-24T13:21:01Z

Laela: /* wesnoth.sides.get */

{{DevFeature1.15|3}}

The sides module is only available in the game. It is not available to plugins or map generators.

All functions taking a side on this page (except '''get''') will accept either the integer index of the side or the side proxy userdata (as returned by '''get''' or '''find''').

== Functions ==

=== wesnoth.sides.is_enemy ===

* {{LuaGameOnly}} '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
* {{LuaGameOnly}} ''side1'':'''is_enemy'''(''side2'') → ''boolean''

Returns true if side 1 is an enemy of side 2, false otherwise.

<syntaxhighlight lang=lua>
local enemy_flag = wesnoth.sides.is_enemy(1, 3)
</syntaxhighlight>

=== wesnoth.sides.matches ===

* {{LuaGameOnly}} '''wesnoth.sides.match_side'''(''side'', ''filter'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''matches'''(''filter'') → ''boolean''

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

<syntaxhighlight lang=lua>
wesnoth.message(tostring(wesnoth.sides[1]:matches{ wml.tag.has_unit { type = "Troll" } }))
</syntaxhighlight>

=== wesnoth.sides.set_id ===

* {{LuaGameOnly}} '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
* {{LuaGameOnly}} ''side'':'''set_id('''''flag'', ''color'')

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes. Both attributes can also be changed through the side proxy attributes, but changing both at the same time is slightly more efficient.

=== wesnoth.sides.place_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.place_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''place_fog'''(''locations'', [''permanent''])

Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, but not a list of such. The ''permanent'' argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.

=== wesnoth.sides.remove_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''remove_fog'''(''locations'', [''permanent''])

Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, though not a list of such. The ''permanent'' argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.

<syntaxhighlight lang=lua>
wesnoth.sides.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.sides.remove_fog(wesnoth.sides[1], { {5, 5} }) -- removes fog for first side on 5,5
wesnoth.sides[1]:remove_fog(wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5
</syntaxhighlight>

=== wesnoth.sides.is_fogged ===

* {{LuaGameOnly}} '''wesnoth.sides.is_fogged'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_fogged'''(''side'') → ''boolean''

Check if a specific location is under fog for the given side.

=== wesnoth.sides.place_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.place_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''place_shroud'''(''locations'')

Places shroud on the specified hexes for the chosen side. This merges the new shroud with any existing shroud on the map. The locations must be passed as an array of pairs, but if you want to merge in a shroud data string, you can parse it first with [[../map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]].

=== wesnoth.sides.override_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.override_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''override_shroud'''(''locations'')

Clears shroud on the specified hexes for the chosen side. This replaces any existing shroud data on the map – after calling `override_shroud`, the locations passed will be the ''only'' unshrouded locations.

=== wesnoth.sides.remove_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''remove_shroud'''(''locations'')

Unshrouds the specified hexes for the chosen side.

=== wesnoth.sides.is_shrouded ===

* {{LuaGameOnly}} '''wesnoth.sides.is_shrouded'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_shrouded'''(''location'') → ''boolean''

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

=== wesnoth.sides.switch_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.switch_ai'''(''side'', ''file'')
* {{LuaGameOnly}} ''side'':'''switch_ai'''(''file'')

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

=== wesnoth.sides.append_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.append_ai'''(''side'', ''params'')
* {{LuaGameOnly}} ''side'':'''append_ai'''(''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.sides.add_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''add_ai_component'''(''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.sides.change_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''change_ai_component'''(''path'', ''component'')

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

=== wesnoth.sides.delete_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
* {{LuaGameOnly}} ''side'':'''delete_ai_component'''(''path'')

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

=== wesnoth.sides.get ===

* {{LuaGameOnly}} '''wesnoth.sides.get'''(''id'') → ''[[LuaAPI/types/side|side proxy]]''
* {{LuaGameOnly}} '''wesnoth.sides'''[''id''] → ''[[LuaAPI/types/side|side proxy]]''
* {{LuaGameOnly}} #'''wesnoth.sides''' → ''number of sides''

Returns the specified [[LuaAPI/types/side|side]], which must be a valid integer side ID.

=== wesnoth.sides.find ===

* {{LuaGameOnly}} '''wesnoth.sides.find'''(''filter'') → ''array of [[LuaAPI/types/side|sides]]''

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].

<syntaxhighlight lang=lua>
--set gold to 0 for all sides with a leader
local sides = wesnoth.sides.find{ wml.tag.has_unit { canrecruit = true } }
for i,v in ipairs(sides) do
v.gold = 0
end
</syntaxhighlight>

=== wesnoth.sides.iter ===

{{DevFeature1.17|?}}

* {{LuaGameOnly}} '''wesnoth.sides.iter'''(''filter?'') → ''iterator'' ⇒ ''[[LuaAPI/types/side|side]]''

Iterate over all sides, or sides that match a filter.

=== wesnoth.sides.create ===

* {{LuaGameOnly}} '''wesnoth.sides.create'''() → ''new side number''

Adds a new blank side to the end of the scenario sides list and returns its number.

=== wesnoth.sides.debug_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.debug_ai'''(''side'') → ''ai context table''
* {{LuaGameOnly}} ''side'':'''debug_ai'''() → ''ai context table''

Returns the AI context table for the given side. This function only exists in debug mode, and only if Wesnoth is launched with the <tt>--debug-lua</tt> command-line argument. This allows you to inspect all the AI internals for that side, including the AI component tree and the AI module (which is instanced per side). You can also execute individual components by calling their execution or evaluation functions.

The returned table contains the following keys:

* '''ai''': The [[LuaAPI/ai|ai]] module bound to this side. Each side has a separate instance of the AI module.
* '''components''': The AI components tree. Each component in this tree potentially has the following subkeys:
** '''engine''', '''id''', '''name''': The basic info about the component - its name and ID and the engine it runs on.
** '''stage''', '''candidate_action''': An array of subcomponents of the specified type.
** '''exec''': For stages or candidate actions, a function which, when called, executes it immediately (and synchronously). Prefer calling this with the :lua command rather than from the Lua console.
* '''engine''': The complete contents of the Lua [engine] tag.
* '''params''': The contents of the [args] tag from the Lua [engine] tag.
* '''data''': A WML table containing persistent data used by the AI. This data is serialized as part of the Lua [engine] tag.
* '''update_self''': The function defined in the Lua [engine] tag. Called as <syntaxhighlight lang=lua inline>update_self(params, data)</syntaxhighlight>.

The above list covers only the most useful keys and is not exhaustive.

Some examples:
<syntaxhighlight lang='lua'>
wesnoth.debug_ai(2).ai -- returns the AI module bound to side 2
wesnoth.debug_ai(2).stage[another_stage].exec() -- executes the "another_stage" stage for side 2
wesnoth.debug_ai(2).ai.aspects.aggression -- returns the current value of the aggression aspect of the AI on side 2
</syntaxhighlight>

'''Note:''' Do not rely on the precise structure of the AI context table. It is documented here as an aid to debugging, but it is ''not'' public API and may change without warning or deprecation.

[[Category:Lua Reference]]

LuaAPI/wesnoth/sides

2024-10-24T13:20:01Z

Laela:

{{DevFeature1.15|3}}

The sides module is only available in the game. It is not available to plugins or map generators.

All functions taking a side on this page (except '''get''') will accept either the integer index of the side or the side proxy userdata (as returned by '''get''' or '''find''').

== Functions ==

=== wesnoth.sides.is_enemy ===

* {{LuaGameOnly}} '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
* {{LuaGameOnly}} ''side1'':'''is_enemy'''(''side2'') → ''boolean''

Returns true if side 1 is an enemy of side 2, false otherwise.

<syntaxhighlight lang=lua>
local enemy_flag = wesnoth.sides.is_enemy(1, 3)
</syntaxhighlight>

=== wesnoth.sides.matches ===

* {{LuaGameOnly}} '''wesnoth.sides.match_side'''(''side'', ''filter'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''matches'''(''filter'') → ''boolean''

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

<syntaxhighlight lang=lua>
wesnoth.message(tostring(wesnoth.sides[1]:matches{ wml.tag.has_unit { type = "Troll" } }))
</syntaxhighlight>

=== wesnoth.sides.set_id ===

* {{LuaGameOnly}} '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
* {{LuaGameOnly}} ''side'':'''set_id('''''flag'', ''color'')

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes. Both attributes can also be changed through the side proxy attributes, but changing both at the same time is slightly more efficient.

=== wesnoth.sides.place_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.place_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''place_fog'''(''locations'', [''permanent''])

Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, but not a list of such. The ''permanent'' argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.

=== wesnoth.sides.remove_fog ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_fog'''([''sides''], ''locations'', [''permanent''])
* {{LuaGameOnly}} ''side'':'''remove_fog'''(''locations'', [''permanent''])

Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, though not a list of such. The ''permanent'' argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.

<syntaxhighlight lang=lua>
wesnoth.sides.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.sides.remove_fog(wesnoth.sides[1], { {5, 5} }) -- removes fog for first side on 5,5
wesnoth.sides[1]:remove_fog(wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5
</syntaxhighlight>

=== wesnoth.sides.is_fogged ===

* {{LuaGameOnly}} '''wesnoth.sides.is_fogged'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_fogged'''(''side'') → ''boolean''

Check if a specific location is under fog for the given side.

=== wesnoth.sides.place_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.place_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''place_shroud'''(''locations'')

Places shroud on the specified hexes for the chosen side. This merges the new shroud with any existing shroud on the map. The locations must be passed as an array of pairs, but if you want to merge in a shroud data string, you can parse it first with [[../map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]].

=== wesnoth.sides.override_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.override_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''override_shroud'''(''locations'')

Clears shroud on the specified hexes for the chosen side. This replaces any existing shroud data on the map – after calling `override_shroud`, the locations passed will be the ''only'' unshrouded locations.

=== wesnoth.sides.remove_shroud ===

* {{LuaGameOnly}} '''wesnoth.sides.remove_shroud'''(''side'', ''locations'')
* {{LuaGameOnly}} ''side'':'''remove_shroud'''(''locations'')

Unshrouds the specified hexes for the chosen side.

=== wesnoth.sides.is_shrouded ===

* {{LuaGameOnly}} '''wesnoth.sides.is_shrouded'''(''side'', ''location'') → ''boolean''
* {{LuaGameOnly}} ''side'':'''is_shrouded'''(''location'') → ''boolean''

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

=== wesnoth.sides.switch_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.switch_ai'''(''side'', ''file'')
* {{LuaGameOnly}} ''side'':'''switch_ai'''(''file'')

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

=== wesnoth.sides.append_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.append_ai'''(''side'', ''params'')
* {{LuaGameOnly}} ''side'':'''append_ai'''(''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.sides.add_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''add_ai_component'''(''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.sides.change_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
* {{LuaGameOnly}} ''side'':'''change_ai_component'''(''path'', ''component'')

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

=== wesnoth.sides.delete_ai_component ===

* {{LuaGameOnly}} '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
* {{LuaGameOnly}} ''side'':'''delete_ai_component'''(''path'')

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

=== wesnoth.sides.get ===

* {{LuaGameOnly}} '''wesnoth.sides.get'''(''id'') → ''side proxy''
* {{LuaGameOnly}} '''wesnoth.sides'''[''id''] → ''side proxy''
* {{LuaGameOnly}} #'''wesnoth.sides''' → ''number of sides''

Returns the specified [[LuaAPI/types/side|side]], which must be a valid integer side ID.

=== wesnoth.sides.find ===

* {{LuaGameOnly}} '''wesnoth.sides.find'''(''filter'') → ''array of [[LuaAPI/types/side|sides]]''

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].

<syntaxhighlight lang=lua>
--set gold to 0 for all sides with a leader
local sides = wesnoth.sides.find{ wml.tag.has_unit { canrecruit = true } }
for i,v in ipairs(sides) do
v.gold = 0
end
</syntaxhighlight>

=== wesnoth.sides.iter ===

{{DevFeature1.17|?}}

* {{LuaGameOnly}} '''wesnoth.sides.iter'''(''filter?'') → ''iterator'' ⇒ ''[[LuaAPI/types/side|side]]''

Iterate over all sides, or sides that match a filter.

=== wesnoth.sides.create ===

* {{LuaGameOnly}} '''wesnoth.sides.create'''() → ''new side number''

Adds a new blank side to the end of the scenario sides list and returns its number.

=== wesnoth.sides.debug_ai ===

* {{LuaGameOnly}} '''wesnoth.sides.debug_ai'''(''side'') → ''ai context table''
* {{LuaGameOnly}} ''side'':'''debug_ai'''() → ''ai context table''

Returns the AI context table for the given side. This function only exists in debug mode, and only if Wesnoth is launched with the <tt>--debug-lua</tt> command-line argument. This allows you to inspect all the AI internals for that side, including the AI component tree and the AI module (which is instanced per side). You can also execute individual components by calling their execution or evaluation functions.

The returned table contains the following keys:

* '''ai''': The [[LuaAPI/ai|ai]] module bound to this side. Each side has a separate instance of the AI module.
* '''components''': The AI components tree. Each component in this tree potentially has the following subkeys:
** '''engine''', '''id''', '''name''': The basic info about the component - its name and ID and the engine it runs on.
** '''stage''', '''candidate_action''': An array of subcomponents of the specified type.
** '''exec''': For stages or candidate actions, a function which, when called, executes it immediately (and synchronously). Prefer calling this with the :lua command rather than from the Lua console.
* '''engine''': The complete contents of the Lua [engine] tag.
* '''params''': The contents of the [args] tag from the Lua [engine] tag.
* '''data''': A WML table containing persistent data used by the AI. This data is serialized as part of the Lua [engine] tag.
* '''update_self''': The function defined in the Lua [engine] tag. Called as <syntaxhighlight lang=lua inline>update_self(params, data)</syntaxhighlight>.

The above list covers only the most useful keys and is not exhaustive.

Some examples:
<syntaxhighlight lang='lua'>
wesnoth.debug_ai(2).ai -- returns the AI module bound to side 2
wesnoth.debug_ai(2).stage[another_stage].exec() -- executes the "another_stage" stage for side 2
wesnoth.debug_ai(2).ai.aspects.aggression -- returns the current value of the aggression aspect of the AI on side 2
</syntaxhighlight>

'''Note:''' Do not rely on the precise structure of the AI context table. It is documented here as an aid to debugging, but it is ''not'' public API and may change without warning or deprecation.

[[Category:Lua Reference]]

UnitTypeWML

2024-10-21T20:58:07Z

Laela: /* Other tags */ 9236

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.
::WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]. {{DevFeature1.19|4}} Abilities support [event].

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

AbilitiesWML

2024-10-21T20:50:28Z

Laela: /* Common keys and tags for every weapon special */ 9236

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} Shortcut of [unit_type][event].

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. '''Replaces''' '''[filter_self]''' of normal weapon specials.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} Shortcut of [unit_type][event].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special {{DevFeature1.17|23}} ===

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

AbilitiesWML

2024-10-21T20:50:05Z

Laela: /* Common keys and tags for every ability */ 9236

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} Shortcut of [unit_type][event].

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. '''Replaces''' '''[filter_self]''' of normal weapon specials.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special {{DevFeature1.17|23}} ===

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

UnitTypeWML

2024-09-23T15:53:14Z

Laela: /* Attacks */ alignment

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.
::WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

FilterWML

2024-09-04T19:15:59Z

Laela: /* Filtering Weapons */

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane' or customised type. {{DevFeature1.17|23}} [damage_type] can change the type of damage inflicted, and this change can be detected in the filter except when it is applied from a [damage_type] which affects the filtered attack, in this case only the type before any modification by a any [damage_type] will be detectable.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location. Does not work in 1.16. {{DevFeature1.17|17}} Works again.
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''number''': {{DevFeature1.13|5}} filter on number of strikes
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''attacks_used''': {{DevFeature1.17|13}} filter on attack's attack cost
* '''min_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''max_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]. The context object for the formula is a '''weapon object''', which supports the following keys: '''name''', '''description''', '''type''', '''icon''', '''range''', '''damage''', '''number''', '''attack_weight''', '''defense_weight''', '''accuracy''', '''parry''', '''movement_used''', '''specials'''. The '''specials''' key is a list of all the special IDs the unit possesses. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable. Keys supported after specific version: {{DevFeature1.17|13}} '''attacks_used'''. {{DevFeature1.19|4}} '''min_range''', '''max_range'''.

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Filtering on WML data ==

Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. Anything between '''<>''' needs to be replaced by the actual data to be filtered for. The following conventions are possible:

* '''<key>=<value>''': Means that the key '''key''' must be present with the specified '''value'''.
* '''glob_on_<key>=<glob>''': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In a glob, the '''*''' character matches any sequence of characters, while the '''?''' character matches any single character. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_<key>=*''' in a '''[not]''' tag.
* '''[<some_tag>]''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.

== Tutorial ==
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]

== See Also ==

* [[AnimationWML#Animation_Filtering|Animation filtering]]
* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]
* [[FilterWML/Examples - How to use Filter]]

[[Category: WML Reference]]

FilterWML

2024-09-04T19:13:49Z

Laela: /* Filtering Weapons */

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane' or customised type. {{DevFeature1.17|23}} [damage_type] can change the type of damage inflicted, and this change can be detected in the filter except when it is applied from a [damage_type] which affects the filtered attack, in this case only the type before any modification by a any [damage_type] will be detectable.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location. Does not work in 1.16. {{DevFeature1.17|17}} Works again.
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''number''': {{DevFeature1.13|5}} filter on number of strikes
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''attacks_used''': {{DevFeature1.17|13}} filter on attack's attack cost
* '''min_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''max_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]. The context object for the formula is a '''weapon object''', which supports the following keys: '''name''', '''description''', '''type''', '''icon''', '''range''', '''damage''', '''number''', '''attack_weight''', '''defense_weight''', '''accuracy''', '''parry''', '''movement_used''', '''min_range''', '''max_range''', '''specials'''. The '''specials''' key is a list of all the special IDs the unit possesses. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable. {{DevFeature1.17|13}} The '''attacks_used''' key is also supported.

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Filtering on WML data ==

Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. Anything between '''<>''' needs to be replaced by the actual data to be filtered for. The following conventions are possible:

* '''<key>=<value>''': Means that the key '''key''' must be present with the specified '''value'''.
* '''glob_on_<key>=<glob>''': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In a glob, the '''*''' character matches any sequence of characters, while the '''?''' character matches any single character. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_<key>=*''' in a '''[not]''' tag.
* '''[<some_tag>]''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.

== Tutorial ==
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]

== See Also ==

* [[AnimationWML#Animation_Filtering|Animation filtering]]
* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]
* [[FilterWML/Examples - How to use Filter]]

[[Category: WML Reference]]

FilterWML

2024-09-04T19:13:21Z

Laela: /* Filtering Weapons */

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane' or customised type. {{DevFeature1.17|23}} [damage_type] can change the type of damage inflicted, and this change can be detected in the filter except when it is applied from a [damage_type] which affects the filtered attack, in this case only the type before any modification by a any [damage_type] will be detectable.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location. Does not work in 1.16. {{DevFeature1.17|17}} Works again.
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''number''': {{DevFeature1.13|5}} filter on number of strikes
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''attacks_used''': {{DevFeature1.17|13}} filter on attack's attack cost
* '''min_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''max_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]. The context object for the formula is a '''weapon object''', which supports the following keys: '''name''', '''description''', '''type''', '''icon''', '''range''', '''damage''', '''number''', '''attack_weight''', '''defense_weight''', '''accuracy''', '''parry''', '''movement_used''', '''specials'''. The '''specials''' key is a list of all the special IDs the unit possesses. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable. {{DevFeature1.17|13}} The '''attacks_used''' key is also supported.

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Filtering on WML data ==

Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. Anything between '''<>''' needs to be replaced by the actual data to be filtered for. The following conventions are possible:

* '''<key>=<value>''': Means that the key '''key''' must be present with the specified '''value'''.
* '''glob_on_<key>=<glob>''': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In a glob, the '''*''' character matches any sequence of characters, while the '''?''' character matches any single character. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_<key>=*''' in a '''[not]''' tag.
* '''[<some_tag>]''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.

== Tutorial ==
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]

== See Also ==

* [[AnimationWML#Animation_Filtering|Animation filtering]]
* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]
* [[FilterWML/Examples - How to use Filter]]

[[Category: WML Reference]]

LuaAPI/types

2024-09-04T19:11:31Z

Laela:

== Race ==

This represents a possible unit race. It has the following attributes:

* ''race''.'''description''' → ''translatable string''

The description of the race, for showing to players.

* ''race''.'''name''' → ''translatable string''
* ''race''.'''plural_name''' → ''translatable string''

The name of the race, for showing to players.

* ''race''.'''num_traits''' → ''number''

The number of random traits given to units of this race.

* ''race''.'''ignore_global_traits''' → ''boolean''

Whether this race can receive the global traits.

* ''race''.'''undead_variation''' → ''string''

The variation to transform this race to if killed by a plague attack.

* ''race''.'''traits''' → ''trait list''

The traits available to this race. Includes global traits if available. You can access specific traits by their ID, and the full trait definition is included.

* ''race''.'''male_name_gen''' → ''name generator''
* ''race''.'''female_name_gen''' → ''name generator''

The name generators for this race. These are callable userdatas that return a random name each time.

* ''race''.'''__cfg''' → ''config''

The entire race definition as raw WML.

== Unit Type ==

This represents a ''type'' of unit in the game, rather than a specific instance of a unit. It has the following attributes:

* ''unit_type''.'''name''' → ''translatable string''

The name of the unit type, for displaying to the player.

* ''unit_type''.'''id''' → ''string''

The unit's ID.

* ''unit_type''.'''race''' → ''string''

The ID of the unit's race. To get the actual race object, use this to look it up in '''wesnoth.races'''.

* ''unit_type''.'''alignment''' → ''alignment''

The unit's alignment.

* ''unit_type''.'''image''' → ''image string''
* ''unit_type''.'''icon''' → ''image string''
* ''unit_type''.'''profile''' → ''image string''
* ''unit_type''.'''small_profile''' → ''image string''

Various images used to represent the unit.

* ''unit_type''.'''max_hitpoints''' → ''number''
* ''unit_type''.'''max_moves''' → ''number''
* ''unit_type''.'''max_experience''' → ''number''
* ''unit_type''.'''cost''' → ''number''
* ''unit_type''.'''level''' → ''number''
* ''unit_type''.'''recall_cost''' → ''number''

Various stats of the unit type.

* ''unit_type''.'''advances_to''' → ''list of strings''

A list of unit type IDs that this unit can advance to.

* ''unit_type''.'''advances_from''' → ''list of strings''

A list of unit type IDs that can advance to this unit.

* ''unit_type''.'''traits''' → ''table''

A table of the traits that this unit type can get. The key is the trait ID and the value is the trait's full definition as a config.

* ''unit_type''.'''abilities''' → ''list of strings''

A list of abilities that this unit type possesses. This is only the abilities' IDs, not their full definition.

* ''unit_type''.'''attacks''' → ''attack list''

A list of weapons that this unit type possesses. This list can be indexed as an array, but you can also look up an attack by its ID (name field). Each attack is a [[#weapon|weapon]] userdata.

* ''unit_type''.'''variations''' → ''variation list''

Returns a list of unit type userdata representing possible variations of this unit, including gender variations. You can look up specific variations by their ID. Male and female variations have the ID '''male''' or '''female'''.

* ''unit_type''.'''__cfg''' → ''config''

Returns the full unit type definition as raw WML. This can be used if you need something that's not directly supported.

== Weapon ==

This represents a single attack on a unit or unit type; it can also exist as an orphaned attack not attached to either a unit or unit type. It has the following attributes:

* ''weapon''.'''read_only''' → ''boolean''

Indicates whether you can write to the attributes of this attack. It will be true when getting an attack from a unit type userdata.

* ''weapon''.'''description''' → ''translatable string''

The attack's name, for displaying to the player.

* ''weapon''.'''name''' → ''string''

The attack's ID.

* ''weapon''.'''type''' → ''string''

The attack's damage type.

* ''weapon''.'''icon''' → ''image string''

The attack's icon.

* ''weapon''.'''damage''' → ''number''
* ''weapon''.'''range''' → ''string''
* ''weapon''.'''number''' → ''number''
* ''weapon''.'''movement_used''' → ''number''
* {{DevFeature1.17|13}} ''weapon''.'''attacks_used''' → ''number''

Basic stats of the attack.

* ''weapon''.'''attack_weight''' → ''number''
* ''weapon''.'''defense_weight''' → ''number''

The attack's weighting values.

* ''weapon''.'''accuracy''' → ''number''
* ''weapon''.'''parry''' → ''number''

The defense modifications of the attack.

* {{DevFeature1.19|4}} ''weapon''.'''min_range''' → ''number''
* {{DevFeature1.19|4}} ''weapon''.'''max_range''' → ''number''

The attack's distance requirement between attacker and defender.

* ''weapon''.'''specials''' → ''list of configs''

The special abilities of this attack.

* ''weapon'':'''matches'''(''filter'') → ''boolean''

Tests if this attack matches the given [[StandardWeaponFilter]].

* ''weapon''.'''__cfg''' → ''config''

The entire attack as raw WML

== See Also ==

* [[LuaAPI/wesnoth#wesnoth.textdomain|translatable strings]] - a string that will be translated by the engine.
* [[LuaAPI/wml#wml.tovconfig|vconfig]] - a WML object that automatically substitutes variables on the fly.
* [[LuaAPI/types/unit|unit]] - represents a reference to Wesnoth unit on the map, on the recall list, or private to Lua.
* [[LuaAPI/types/side|side]] - represents a single side (player) in the game.
* [[LuaAPI/types/widget|widget]] - represents a GUI2 widget.
* [[LuaAPI/types/map|map]] - represents the game map.
* [[LuaAPI/types/hex|hex]] - represents a single hex on the map.

[[Category:Lua Reference]]

LuaAPI/types

2024-09-04T19:09:16Z

Laela: /* Weapon */

== Race ==

This represents a possible unit race. It has the following attributes:

* ''race''.'''description''' → ''translatable string''

The description of the race, for showing to players.

* ''race''.'''name''' → ''translatable string''
* ''race''.'''plural_name''' → ''translatable string''

The name of the race, for showing to players.

* ''race''.'''num_traits''' → ''number''

The number of random traits given to units of this race.

* ''race''.'''ignore_global_traits''' → ''boolean''

Whether this race can receive the global traits.

* ''race''.'''undead_variation''' → ''string''

The variation to transform this race to if killed by a plague attack.

* ''race''.'''traits''' → ''trait list''

The traits available to this race. Includes global traits if available. You can access specific traits by their ID, and the full trait definition is included.

* ''race''.'''male_name_gen''' → ''name generator''
* ''race''.'''female_name_gen''' → ''name generator''

The name generators for this race. These are callable userdatas that return a random name each time.

* ''race''.'''__cfg''' → ''config''

The entire race definition as raw WML.

== Unit Type ==

This represents a ''type'' of unit in the game, rather than a specific instance of a unit. It has the following attributes:

* ''unit_type''.'''name''' → ''translatable string''

The name of the unit type, for displaying to the player.

* ''unit_type''.'''id''' → ''string''

The unit's ID.

* ''unit_type''.'''race''' → ''string''

The ID of the unit's race. To get the actual race object, use this to look it up in '''wesnoth.races'''.

* ''unit_type''.'''alignment''' → ''alignment''

The unit's alignment.

* ''unit_type''.'''image''' → ''image string''
* ''unit_type''.'''icon''' → ''image string''
* ''unit_type''.'''profile''' → ''image string''
* ''unit_type''.'''small_profile''' → ''image string''

Various images used to represent the unit.

* ''unit_type''.'''max_hitpoints''' → ''number''
* ''unit_type''.'''max_moves''' → ''number''
* ''unit_type''.'''max_experience''' → ''number''
* ''unit_type''.'''cost''' → ''number''
* ''unit_type''.'''level''' → ''number''
* ''unit_type''.'''recall_cost''' → ''number''

Various stats of the unit type.

* ''unit_type''.'''advances_to''' → ''list of strings''

A list of unit type IDs that this unit can advance to.

* ''unit_type''.'''advances_from''' → ''list of strings''

A list of unit type IDs that can advance to this unit.

* ''unit_type''.'''traits''' → ''table''

A table of the traits that this unit type can get. The key is the trait ID and the value is the trait's full definition as a config.

* ''unit_type''.'''abilities''' → ''list of strings''

A list of abilities that this unit type possesses. This is only the abilities' IDs, not their full definition.

* ''unit_type''.'''attacks''' → ''attack list''

A list of weapons that this unit type possesses. This list can be indexed as an array, but you can also look up an attack by its ID (name field). Each attack is a [[#weapon|weapon]] userdata.

* ''unit_type''.'''variations''' → ''variation list''

Returns a list of unit type userdata representing possible variations of this unit, including gender variations. You can look up specific variations by their ID. Male and female variations have the ID '''male''' or '''female'''.

* ''unit_type''.'''__cfg''' → ''config''

Returns the full unit type definition as raw WML. This can be used if you need something that's not directly supported.

== Weapon ==

This represents a single attack on a unit or unit type; it can also exist as an orphaned attack not attached to either a unit or unit type. It has the following attributes:

* ''weapon''.'''read_only''' → ''boolean''

Indicates whether you can write to the attributes of this attack. It will be true when getting an attack from a unit type userdata.

* ''weapon''.'''description''' → ''translatable string''

The attack's name, for displaying to the player.

* ''weapon''.'''name''' → ''string''

The attack's ID.

* ''weapon''.'''type''' → ''string''

The attack's damage type.

* ''weapon''.'''icon''' → ''image string''

The attack's icon.

* ''weapon''.'''damage''' → ''number''
* ''weapon''.'''range''' → ''string''
* ''weapon''.'''number''' → ''number''
* ''weapon''.'''movement_used''' → ''number''
* {{DevFeature1.17|13}} ''weapon''.'''attacks_used''' → ''number''

Basic stats of the attack.

* ''weapon''.'''attack_weight''' → ''number''
* ''weapon''.'''defense_weight''' → ''number''

The attack's weighting values.

* ''weapon''.'''accuracy''' → ''number''
* ''weapon''.'''parry''' → ''number''

The defense modifications of the attack.

* ''weapon''.'''min_range''' → ''number''
* ''weapon''.'''max_range''' → ''number''

The attack's distance requirement between attacker and defender.

* ''weapon''.'''specials''' → ''list of configs''

The special abilities of this attack.

* ''weapon'':'''matches'''(''filter'') → ''boolean''

Tests if this attack matches the given [[StandardWeaponFilter]].

* ''weapon''.'''__cfg''' → ''config''

The entire attack as raw WML

== See Also ==

* [[LuaAPI/wesnoth#wesnoth.textdomain|translatable strings]] - a string that will be translated by the engine.
* [[LuaAPI/wml#wml.tovconfig|vconfig]] - a WML object that automatically substitutes variables on the fly.
* [[LuaAPI/types/unit|unit]] - represents a reference to Wesnoth unit on the map, on the recall list, or private to Lua.
* [[LuaAPI/types/side|side]] - represents a single side (player) in the game.
* [[LuaAPI/types/widget|widget]] - represents a GUI2 widget.
* [[LuaAPI/types/map|map]] - represents the game map.
* [[LuaAPI/types/hex|hex]] - represents a single hex on the map.

[[Category:Lua Reference]]

EffectWML

2024-09-04T19:06:47Z

Laela: /* [effect] */ min_range, max_range

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaAPI/wesnoth#wesnoth.effects]]. Some examples can be seen in [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/World_Conquest/lua/game_mechanics/effects.lua World Conquest].

[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* {{anchor|apply_to-new_attack|'''new_attack'''}}: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* {{anchor|apply_to-remove_attacks|'''remove_attacks'''}}: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* {{anchor|apply_to-attack|'''attack'''}}: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** {{anchor|set_specials|'''[set_specials]'''}}: change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''increase_attacks_used''': {{DevFeature1.17|13}} increases the attack points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''set_attacks_used''' {{DevFeature1.17|13}} like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
** '''set_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''set_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
* {{anchor|apply_to-max_attacks|'''max_attacks'''}}: {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* {{anchor|apply_to-hitpoints|'''hitpoints'''}}: modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* {{anchor|apply_to-movement|'''movement'''}}: modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* {{anchor|apply_to-vision|'''vision'''}}: {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* {{anchor|apply_to-jamming|'''jamming'''}}: {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* {{anchor|apply_to-experience|'''experience'''}}: affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* {{anchor|apply_to-max_experience|'''max_experience'''}}: affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* {{anchor|apply_to-loyal|'''loyal'''}}: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* {{anchor|apply_to-fearless|'''fearless'''}}: Add/Remove fearless attribute.
** '''set''': new value for fearless (boolean). Defaults to '''yes'''.
* {{anchor|apply_to-healthy|'''healthy'''}}: Add/Remove healthy attribute.
** '''set''': new value for healthy (boolean). Defaults to '''yes'''.
* {{anchor|apply_to_movement_costs|'''movement_costs'''}}: speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[movement_costs]''': a subtag that describes the new movement costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-vision_costs|'''vision_costs'''}}: vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[vision_costs]''': a subtag that describes the new vision costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-jamming_costs|'''jamming_costs'''}}: jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-defense|'''defense'''}}: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to '''no'''.
** '''[defense]''': a subtag that describes the new defense just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-resistance|'''resistance'''}}: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to '''no'''.
** '''[resistance]''': a subtag that describes the new resistance just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-variation|'''variation'''}}: switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement].
** '''name''': the id of the variation to invoke.
* {{anchor|apply_to-type|'''type'''}}: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* {{anchor|apply_to-status|'''status'''}}: modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* {{anchor|apply_to-zoc|'''zoc'''}}: toggle the zone of control.
** '''value''': new value for zoc (boolean).
* {{anchor|apply_to-profile|'''profile'''}}: customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* {{anchor|apply_to-new_ability|'''new_ability'''}}: Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': A subtag that contains the ability definitions like type of abilities, id, or other attributes like affect_self or [affect_adjacent] but not generic filter.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

== Examples ==
=== Effect: apply_to = new_animation ===
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.

[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y = 1,5
[/filter]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]

If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable = stored_unit
[/store_unit]
[set_variables]
name = stored_unit.modifications.object
[value]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable = stored_unit
[/unstore_unit]
[/event]

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

ThemeWML

2024-08-10T22:30:21Z

Laela: /* The toplevel [theme] tag */ ref

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

Themes are used both for the wesnoth game and the wesnoth editor.
Themes allow flexible configuration of how everything is laid out on-screen.

The following keys are recognized in '''[theme]''':
* '''id''': The internal id of the theme.
* '''name''': Translatable theme name displayed in Preferences.
* '''hidden''': Boolean value (defaults to '''no'''), determines whether the theme will be displayed in Preferences or not. This can be used to prevent players from choosing themes that are not intended for use in regular gameplay.
* '''description''': A short description of the theme to display in Preferences.

The only tag in '''[theme]''' is '''[[ThemeSystem|[resolution]]]''', but each theme can have multiple [resolution] tags.
The [resolution] tags are scanned until the first one which is of the same or lower resolution than is currently being used is found, and this is used as our theme.
This allows us to define themes to work differently on different resolutions,
and will allow us to support both high and low resolutions elegantly.

The following keys and tags are recognized for [resolution]:

* '''width''', '''height''': dimensions in pixels

All subtags of [resolution] use the following keys:
* '''rect'''=''a,b,c,d'': defines the rectangle to display on, where a,b are top-left XY co-ordinates and c,d are bottom-right XY co-ordinates. So, for example rec="0,10,20,30" would create a rectangle that has top left corner at the very left side of the screen, 10 pixels below the very top and is 20 pixels wide and tall. Each of a,b,c,d may be specified as:
** number : absolute positions
** ''='' : same value as the same field in reference rect (alignment with reference)
** +number or -number : for a and b, add this value to reference's c and d respectively (spacing from reference); for c and d, add this value to self's a and b (specify by width and height)
** =+number or =-number : add this value to same field in reference rect (eg. consider reference as a container box)
* '''ref''': id of subtag of [resolution] which is used in case of relative rect component (by default rect of (0,0,0,0))
* '''xanchor''', '''yanchor''': control the behavior of how this rectangle changes as the resolution changes.
** '''left''': its distance from the left side of the screen always remain the same, while changes in the resolution will change its size by the same amount (top for the y axis).
** '''right''': its size always remain the same, as well as its distance to the right side of the screen (bottom for the y axis).
** '''fixed''': its co-ordinates in that axis remain constant
** '''proportional''': its co-ordinates multiplied by the ratio of the resolution being used to the canonical resolution.

== [main_map] ==

defines where the main game display (i.e. all the hexagons and units) is displayed.

== [main_map_border] ==
Defines the border of the main map area. It has the following keys.

* '''border_size''': the size of the border, the value should be between 0.0 and 0.5. The images which are used by default are sized for 0.5. If the border gets smaller the images still need the same size. They're simply cut off at the right spot.
* '''background_image''': the filename of the image to use as background.
* '''tile_image''': the filename of the image to use for the _off^_usr tile. The image in the minimal can't be controlled only the image in the main map. This image must be in the terrain directory and a png image. When specifying the image the 'terrain/' prefix and '.png' suffix _must_ be ommitted.

== [mini_map] ==

Determines where the mini map is displayed

== [panel] ==

Displays an image as a panel on-screen.
* '''image''': the image used for the panel

== [label] ==

Displays a text label on screen.
* '''prefix''': a string that will be printed before the text in all languages
* '''text''': a text string id to be displayed
* '''postfix''': a string that will be printed after the text in all languages
* '''icon''': an image that will be displayed instead of the text if it is available
* '''font_size''': the size of font to use for the label

== [menu] ==

* '''title''': the id of the string to write on the button
* '''title_literal''': a string that will be displayed "as is" in all language after the title
* '''image''': the image to use if available
* '''is_context_menu''': if set to true this menu will not be placed, but displayed on a right click
* '''items''': comma separated list of actions to put in the menu. if there is only one action, it will be executed immediately and no menu will be displayed
** '''cycle''': move to next movable unit
** '''endunitturn''': consume this unit's move and cycle to the next one
** '''leader''': center on the leader
** '''undo''': undo last action
** '''redo''': redo undone action
** '''zoomin''': zoom the map in
** '''zoomout''': zoom the map out
** '''zoomdefault''': return to default zoom
** '''fullscreen''': switch fulscreen mode
** '''accelerated''': switch turbo mode
** '''resistance''': show resistance table of current unit
** '''terraintable''': show terrain table of current unit
** '''describeunit''': show unit description
** '''renameunit''': change unit name
** '''save''': save the game
** '''recruit''': recruit a unit
** '''repeatrecruit''': repeat last recruitement
** '''recall''': recall a unit from previous scenario
** '''endturn''': end current turn
** '''togglegrid''': toggle grid display
** '''statustable''': show status table
** '''mute''': mute all sounds
** '''speak''': send message to other players
** '''createunit''': debug create a unit on the map
** '''preferences''': open preference dialog
** '''objectives''': show objective window
** '''unitlist''': list units
** '''statistics''': show game statistics
** '''quit''': quit the game
** '''labelterrain''': label current location
** '''clearlabels''': clear all labels on map
** '''showenemymoves''': show grids reachable by the enemy
** '''bestenemymoves''': show grids reachable by the enemy with no zone of control
** '''editnewmap''': editor only start a new map
** '''editloadmap''': editor only loads an existing map
** '''editsavemap''': editor only saves the current map
** '''editsaveas''': editor only saves the current map, let you choose a filename
** '''editsetstartpos''': editor only set a starting position for a team
** '''editfloodfill''': editor only flood the map with a terrain
** '''toggleshroud''': toggle the "moving removes shroud" behaviour
** '''updateshroud''': removes all possible shroud
** '''AUTOSAVES''': expands to a list of all Auto-Save games prior to this one

== [status] ==

This tag describes the Status Table.
This tag contains many other tags, which determine where other game statistics, such as the current turn, and a description of selected units go.
For instance, the [time_of_day] tag will determine where the time of day image goes.
Each subtag of [status] can contain the following attributes

** '''font_size''': the size of font to use for the status
** '''rect''': the rectangle as for the main_map attribute
** '''xanchor''': the x-wise anchoring as for the main_map attribute
** '''yanchor''': the y-wise anchoring as for the main_map attribute
** '''prefix''': the string to display before the actual status, this is the string id for internationalisation
** '''prefix_literal''': a string to put after the prefix, but before the label for all languages.
** '''postfix_literal''': a string to put after the status
** '''postfix''': the string to display after the postfix_literal, this is the string id for internationalisation

the following tags are recognized for [status]:
* '''[unit_description]''': the user description of the current unit. Note: this tag is now obsolete
* '''[unit_name]''': the user description of the current unit
* '''[unit_type]''': the type of the current unit
* '''[unit_race]''': the race of the current unit
* '''[unit_level]''': the level of the current unit
* '''[unit_side]''': the side of the current unit (flag)
* '''[unit_traits]''': the traits of the current unit
* '''[unit_status]''': the status of the current unit
* '''[unit_alignment]''': the alignment of the current unit
* '''[unit_abilities]''': the abilities of the current unit
* '''[unit_hp]''': the HP of the current unit
* '''[unit_xp]''': the XP of the current unit
* '''[unit_moves]''': the moves remaining for the current unit
* '''[unit_weapons]''': the attacks of the current unit
* '''[unit_image]''': the icon for the current unit
* '''[unit_profile]''': the portait for the current unit
* '''[unit_advancement_options]''': the advancement(s) of the current unit appear in the tooltip of this element
* '''[time_of_day]''': the time of day on the current location
* '''[turn]''': the turn number and turn remaining
* '''[gold]''': the gold remaining
* '''[villages]''': the number of villages owned
* '''[num_units]''': the number of units owned
* '''[upkeep]''': the money needed to keep your units every turn
* '''[expenses]''': the money lost each turn when you don't have enough income
* '''[income]''': the income per turn (can be positive)
* '''[terrain]''': the text description of the current terrain
* '''[position]''': the current terrain's position
* '''[side_playing]''': the current playing side (flag)
* '''[observers]''': the current observers

== See Also ==

* [[ThemeSystem]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Wesnoth AI Framework

2024-08-08T19:15:56Z

Laela: /* AI Configuration */ seems [ai] works in [modification]

== Wesnoth AI Framework: A Composite AI ==

The Wesnoth AI framework is that of a composite AI. In other words, rather than the AI being one huge monolithic block, it is composed of a variety of different components which can be combined in a modular fashion (almost) at will.

In its default configuration, Wesnoth provides a predefined combination of these components in the [[RCA AI]]. This configuration can be modified in a multitude of different ways. Due to the modular setup, it is not only possible to add new AI behavior to before or after the default AI moves, or replace the default AI entirely, but also to insert new behavior routines in between existing components. This can be done either in addition to or as substitutions for existing components.

This page describes the AI components and their configuration in a general sense. Check out [[RCA AI]] for a description of how these are assembled into the default AI and [[Wesnoth AI]] for a collection of links to pages explaining how to customize and modify the existing AI or write a completely new AI.

== Types of AI Components ==

The Wesnoth AI framework consists of the following types of components:

==== Stages====

These are the fundamental building blocks of the AI. The AI is set up as a series of stages which are executed in the order in which they are put into the AI configuration. In other words, all actions of the first stage are executed first, then all actions of the second stage, etc.

While there are six different types of stages, only one of them, called the ''main_loop'' stage, is used in the default AI. In fact, this stage is sufficient for the vast majority of custom AI applications as well. We therefore only describe the ''main_loop'' stage and its sub-components in detail.

==== The Candidate Actions of the ''main_loop'' Stage ====

The ''main_loop'' stage consists of a number of candidate actions (CAs), each of which contains an evaluation and an execution function. For each AI move, the evaluation functions of all CAs are called, with each of them returning a score. The execution function of the CA with the highest score is then called, which results in an AI move (or in some cases, several moves) to be done. Then all CAs are evaluated again (including the one that was just executed) and the highest scoring CA is executed, until no CA returns a valid (non-zero) score any more.

Combining candidate actions designed for specific tasks such as attacks or village grabbing, it is possible to create entire AIs in a modular fashion. The CAs can be put together in whatever order and combination best suits the needs of a scenario. They do not need to be sorted in order of their evaluation scores and can even return variable scores which adapt to the situation on the map.

For a summary of the candidate actions of the default AI, click [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|here]].

==== Aspects and Goals====

Aspects are configurable input parameters used to customize a candidate action's behavior. They are implemented as the the return values of functions that are called by the CAs of the RCA AI. They can also be called and taken into account by custom CAs, but that is not necessarily always the case. For example, some of the [[Micro AIs]] respect some of the RCA AI aspects (such as ''avoid''), but not all do.

The return values of the aspect functions can be defined and/or customized using both [[AiWML|WML]] or [[LuaAI#Dynamic_Lua_Aspects|Lua]].

Goals are used similarly to aspects in that they also affect the behavior of the default AI. They can be used to customize the directions into which the default AI moves its units. However, both their [[AiWML#AI_Targets_and_Goals|syntax]] and their internal implementation (see below) are different from those of the aspects.

Check out the [[RCA AI]] page for details on which aspects and goals exist and how they are used by the default AI.

==== Engines====

Engines assemble the configurations provided for the individual components of the AI into usable code and execute this code. In recent Wesnoth versions, you do not need to worry about the engines any more, they are always defined and active by default. It is sufficient to know that the components can be written in three different languages, C++, Lua and Formula AI (FAI). Information on how to do this is provided in the links of the [[Wesnoth AI]] page.

It is worth noting that some stages are only set up for specific engines (see below), while the candidate actions, aspects and goals of the ''main_loop'' stage can be written in any of the three languages and can be combined arbitrarily.

== AI Configuration ==

The Wesnoth AIs are assembled from configurations provided in several different places:
* The default AI parameters in a variety of configuration files in the 'data/ai/' directory
* Optional [ai] or [modify_ai] tags in era configurations
* Optional [ai] or [modify_ai] tags in modification configurations
* Optional [ai] or [modify_ai] tags in multiplayer faction configurations
* Optional [ai] or [modify_ai] tags in scenario configurations
* Optional [ai] tags in individual unit definitions (ie in the [unit] tag) - note that this option may be removed or drastically changed in the future

When the game is created, all these config snippets are merged into a single configuration stored in form of an [ai] tag. Then, aspects with the same ids are merged. During the game, whenever a [modify_ai] tag is acted upon (for example in an event), it is added into the existing AI configuration in the same way.

In the following, we describe the syntax of the [ai] tag. We first show the top-level keys and tags that can be used. Details on the use of the tags for the individual components follow after that, together with examples and links to more information for each component.

== The [ai] Tag — Top-level Elements ==

AI configurations are set up and stored using the [ai] tag. It has the following top-level elements, which are described in more detail in the remaining sections of this page.

*'''description'''="": (translatable string) This is the text displayed in the MP setup menu when choosing an AI for a computer player. It is only relevant for reusable AI configurations, for example in [[EraWML]].
*'''id'''="": (string) The id of the [ai] config snippet. This was originally meant to make it possible to remove [ai] configurations selectively during a game. However, due to the merging process described above, this information is lost. The id is therefore meaningless in the current implementation of the AI. {{DevFeature1.13|5}} This id can now be referenced by ''ai_algorithm'' in order to set the base AI algorithm to build on. It is only relevant for reusable AI configurations, for example in [[EraWML]].
*'''ai_algorithm''': (string) This used to instruct Wesnoth to load a different AI engine instead of the composite AI. {{DevFeature1.13|5}} It now specifies a default AI configuration to load; any AI available at the multiplayer select screen can be chosen, or AIs defined in other addons. It must reference the id attribute of another [ai] tag. It defaults to ai_default_rca; other possible values include experimental_ai and idle_ai. Specifying the ID of an AI defined in ''data/ai/ais/'' or ''/data/ai/dev/'' is roughly equivalent to macro-including that file in your side configuration just above the opening [ai] tag, except that the AI configuration will be loaded on the fly (similar to using [modify_side]switch_ai) rather than included in the preprocessed WML. Additional aspects, stages, and so on can still be added to the [ai] tag as normal.
*'''mp_rank''': (integer) {{DevFeature1.15|0}} A value that determines in which order available AIs are displayed in the multiplayer selection menu. AIs are listed in ascending order of mp_rank (smallest values first). The mainline default (RCA) AI and Experimental AI have values of 1000 and 1010, respectively, meaning that custom AIs with mp_rank less than 1000 will be listed before any of the default AIs. AIs that do not contain an mp_rank line are shown at the end of the list. It is only relevant for reusable AI configurations, for example in [[EraWML]].
*'''version'''="": (string) This key is currently still needed to distinguish whether aspects are defined using ''standard'' or ''composite'' syntax in the [ai] tag. If it is omitted, standard syntax is used. If set to '10703' or '10710', the engine uses composite syntax. However, '''we are in the process of removing this distinction'''. When that is done, both types of syntax can be used without needing the ''version'' key, even mixed together inside the same [ai] tag. We will also deprecate this key when that happens. {{DevFeature1.13|5}} The version key is no longer recognized and will be mistaken as an attempt to set a non-existent "version" aspect. The key should not normally be required even prior to 1.13.5, however.
*'''[stage]''': Configuration of the stage(s) used in the AI. Several [stage] tags can be used, even several stages of the same type. They are executed in the order in which they are put into the [ai] tag.
*'''[aspect]''': Configuration of the aspects to be used by the AI. These are in composite aspect format.
** Most aspects can also be provided using the simpler syntax explained at [[AiWML]].
*'''[goal]''': Configuration of the goals to be used by the AI.
*'''[engine]''': This tag used to be needed for the Lua AI engine. It is not required any more, the Lua engine is created automatically now, just as the two other engines. If you need information on how this works, check out the [[Lua_AI_Legacy_Methods_Howto|Lua AI legacy documentation]]. Note that this tag is still used internally, so it will almost certainly not be removed in the future.
*'''[modify_ai]''': The [modify_ai] tag can specify modifications to be applied to the AI immediately. This is the preferred way to add a candidate action to the RCA AI, but can also be used for any other type of modification that [[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]] supports.
*'''[micro_ai]''': Add a [micro_ai] at initialization time. See [[Micro AIs]] for details. This is equivalent to adding the micro AI at prestart. The side and action keys are not supported here.
*'''formula'''="": (string) Formula AI code to be executed by the AI. We recommend not using this any more, and it is not guaranteed to continue working. See the [[Formula_AI_Howto|Formula AI legacy documentation]] for more information. {{DevFeature1.13|5}} As of version 1.13.5 this key is ''definitely not'' recognized at this level. It has likely not been recognized for some time prior to this, as well.
*'''time_of_day''', '''turns''', '''engine''': {{DevFeature1.13|5}} Specifies default values for aspects given as attributes or simple tags. (Simple tags are tags that do not contain either a value= attribute or a [value] subtag, with the exception that [attacks] is never a simple tag.) This is available prior to 1.13.5, but more limited; the engine attribute is probably more limited, and there might be problems mixing this syntax with fully-specified composite aspects in the same [ai] tag. (That can easily be worked around in a side configuration by splitting the [ai] tag in two.)
*'''Other tags and attributes''': {{DevFeature1.13|5}} Any other tag or attribute found is assumed to be a simplified aspect. More details about this syntax is given in the section on aspects later on this page. Some of this syntax is available prior to 1.13.5, but it has been generalized in 1.13.5 to automatically work for any compatible aspect. See [[AIWML]] for a list of these tags and attributes.

If no '''ai_algorithm''' is specified, normally the game will automatically load in the default AI, as if you had specified '''ai_algorithm=ai_default_rca'''. However, if there is a '''[stage]''' tag, then this behaviour is disabled and the AI will be built from a blank slate. This special behaviour only comes into play if '''ai_algorithm''' is omitted entirely.

== The [ai] Tag — Stages ==

The [ai] tag can contain one or several stages defined in [stage] tags. If the AI configuration contains several stages, they are executed in the order in which they are put into the [ai] tag.

While there are six different types of stages available, all AI functionality possible in Wesnoth can be achieved using only a single one, the candidate action evaluation loop stage. In the default setup, this stage has ''id'' 'main_loop' and we generally simply refer to it as the ''main_loop'' stage.

Other stages exist mostly for legacy reasons from the times in the AI development when the ''main_loop'' stage did not exist yet. They are currently still functional and kept for backward compatibility reasons, but they are not maintained any more and might be removed in a future Wesnoth release cycle. We therefore recommend that all custom AI development is done using the ''main_loop'' stage only.

All stages support the '''id''' and '''engine''' tags. The latter defaults to cpp, and can be omitted in this case; the former is a unique identifier which is required if you want to later remove or modify the stage with [modify_ai]. If '''engine'''=cpp, an additional '''name''' tag is required, which tells the game which C++ AI algorithm to use. Currently the only valid values are 'ai_default_rca::candidate_action_evaluation_loop' and 'empty'. The 'empty' stage does nothing at all and should generally not be required.

=== ''main_loop'' Stage Configuration ===

For the ''main_loop'' stage, the [ai] tag contains the following elements:

*'''name''': This must be set to 'ai_default_rca::candidate_action_evaluation_loop', so that the AI knows that this is the ''main_loop'' stage.
*'''id''': (string) This is the identifier of the AI. It is usually set to 'main_loop', but can take on any value. It only matters if you are planning to remove or modify the stage during a scenario. Note that adding or removing a candidate action counts as a modification.
*'''engine'''=cpp: (string) This must be set to 'cpp', which is also the default value. It can therefore be omitted.
*'''[candidate_action]''': Candidate action configuration tags. See [[#The_.5Bai.5D_Tag_.E2.80.94_Candidate_Actions|below]] for details.
*'''[args]''': {{DevFeature1.13|5}} Lua engine only; specifies arguments to pass to the stage's execution function. This works similarly to the [args] in candidate actions.

'''Notes:'''
* As an example, the configuration of the ''main_loop'' stage of the default AI is shown [[RCA_AI#RCA_AI_Stage_Configuration|here]].
* Candidate actions can use any of the three available engines. Just because the stage uses the ''cpp'' engine does not mean that the CAs need to do so as well. See [[#The_.5Bcandidate_action.5D_Tag|below]] for an example.
* While that should rarely ever be necessary, it is possible to include several ''main_loop'' stage definitions in the same [ai] tag.
** This is done by putting several [stage] tags into the same [ai] tag
** The AI engine then evaluates the CAs of the first stage in the usual way, until no CA returns a valid score any more.
** After the first stage is finished, it moves on to the second stage and repeats the process, until all stages have finished. This ends the AI turn.
** Obviously, this only makes sense if the sets of CAs of the different stages are not identical (although individual CAs might appear in several stages).

=== Recruitment Stage ===

There is a specialized configurable recruitment stage. However, this stage uses the recruitment functions of the old ''Default AI'' (the one used before the RCA AI existed). Anything that can be done with this stage, and more, can now also be done with the ''recruitment'' candidate action using the [[AI_Recruitment#Aspect_recruitment_instructions|''recruitment_instruction'' aspect]]. It should therefore never be necessary to use this stage and we do not describe it here.

{{DevFeature1.13|5}} This stage has now been removed. Any use of this stage within the old ''recruitment'' aspect should still continue to work, as the syntax of this stage is compatible with the ''recruitment_instructions'' aspect and ''recruitment'' is now considered a synonym of that newer aspect. Straight uses of this stage, however, will no longer function.

=== Legacy Stages ===

Four other stages are also available. They do, however, not provide any functionality that is not also possible with the ''main_loop'' stage, only different ways of achieving the same functionality. We therefore only list them here for completeness, with brief examples and links to legacy documentation.

Note that both this documentation and the stages themselves might be removed at some point.

==== Lua stage ====

Executes Lua code by calling a function created inside a Lua engine. Whatever element is returned by the code in the Lua [engine] tag is accessible here as an upvalue.
So, for example, <syntaxhighlight lang='lua' inline>(...):execute()</syntaxhighlight> calls <syntaxhighlight lang='lua' inline>whatever_is_returned_by_lua_engine:execute()</syntaxhighlight>.
<syntaxhighlight lang='wml'>
[stage]
engine="lua"
code= "(...):execute()"
[/stage]
</syntaxhighlight>

See the [[Lua_AI_Legacy_Methods_Howto#Using_the_Lua_Stage|Lua AI legacy documentation]].

==== Formula AI Side Formulas Stage ====

This stage executes a given Formula AI side formula. Example:
<syntaxhighlight lang='wml'>
[stage]
engine=fai
name=side_formulas
move="write_your_formula_here"
[/stage]
</syntaxhighlight>

See the [[Formula_AI_Howto#Setting_up_the_Formula_AI_side_formulas_Stage|Formula AI legacy documentation]].

==== Formula AI Unit Formulas Stage ====

This stage takes no parameters and executes all Formula AI formulas which are attached to units. Example:
<syntaxhighlight lang='wml'>
[stage]
engine=fai
name=unit_formulas
[/stage]
</syntaxhighlight>

See the [[Formula_AI_Howto#Setting_up_the_Formula_AI_unit_formulas_Stage|Formula AI legacy documentation]].

==== Fallback stage ====

Fall back to another AI. Example:
<syntaxhighlight lang='wml'>
[stage]
id=fallback
name=testing_ai_default::fallback
[ai]
ai_algorithm=default_ai
[/ai]
[/stage]
</syntaxhighlight>
This example shows how to set up a stage to fall back to the old ''Default AI''. This was useful when it was not clear yet how well the RCA AI would work and whether it would suddenly stop in the middle of the CA evaluation loop. There is really no reason to use a fallback stage any more these days, especially since it is also possible to simply add another stage to the AI configuration (without that having to be a fallback stage).

{{DevFeature1.13|5}} This stage has now been removed since the RCA AI is now the only algorithm and thus there's nothing else to fallback to.

== The [ai] Tag — Candidate Actions ==

The ''main_loop'' stage (and only this stage) can contain an assortment of candidate actions. They are evaluated and executed in the manner explained [[Wesnoth_AI_Framework#The_Candidate_Actions_of_the_main_loop_Stage|above]]. This section explains how to configure the [candidate_action] tag that goes into the [stage] tag of the ''main_loop'' stage.

All three engines can, in principle, be used to [[Creating_Custom_AIs#Setting_Up_a_Custom_AI|write custom CAs]]. However, only the use of Lua CAs is recommended for this purpose. Using the ''cpp'' engine has the obvious problem of requiring changes to the Wesnoth source code. Formula AI CAs are discouraged for the same reasons why we do not recommend using Formula AI stages any more.

=== The [candidate_action] Tag ===

The [candidate_action] tag can contain the following keys:

*'''engine''': This key is required for Wesnoth to know which engine the CA should be processed with. Possible values are 'cpp', 'lua' and 'fai'.
*'''id''': The id of the CA is, in principle, optional. However, it is needed if you want to remove or change the CA after its initial definition.
*'''name''': The CAs of the default AI are identified by their name, making this a required key for the ''cpp'' engine. Check [[RCA_AI#Available_Candidate_Actions|here]] for the names of the available default CAs. The key is optional for other engines.
*'''max_score''': The maximum score the CA evaluation function might return. This parameter is optional, but it is useful to reduce the AI move evaluation time. During each iteration through the evaluation loop, the ''main_loop'' stage only evaluates CAs with ''max_score'' larger than that of the highest-scoring CA found so far during this iteration. For that same reason, it also makes sense to order CAs by decreasing ''max_score'' in the [stage] tag, even though that is not technically necessary.
*'''score''': (''cpp'' engine only) The score returned by the CA. Note that this means that ''cpp'' engine CAs always have fixed scores.
*'''[filter_own]''': {{DevFeature1.15|3}} The AI units participating in this candidate action can be restricted to only the units defined in this tag. See the [[AiWML#Filtering_which_Units_Participate_in_which_Actions|AiWML page]] for more information and an example. The content of this tag is [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions|available to both the evaluation and execution function as a WML table]]. This tag is optional. If it is omitted, all AI units are used. (''cpp'' and ''lua'' CAs only; ''fai'' CAs have a different mechanism.)

In addition, [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions|Lua CAs]] also contain the following keys:
*'''location''': File name, including path, of the AI code for the CA.
*'''eval_parms''', '''exec_parms''': (deprecated) The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a [[LuaWML#Encoding_WML_objects_into_Lua_tables|Lua table]], without the outer curly brackets. They are [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions|passed to these functions]] as the second argument, ''cfg''.
*'''sticky''', '''unit_x''', '''unit_y''': Specifies that this is a [[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions|behavioral candidate action]] that is automatically removed once the unit on the given location dies.
*'''[args]''': {{DevFeature1.13|5}} This replaces eval_parms and exec_parms, which are now deprecated and will be removed in a later version. The content of this tag is available to both the evaluation and execution function as a WML table. Details at the link above.

'''Notes:'''

* The syntax for Lua CAs has evolved a fair bit, and some of the older syntaxes are still supported. They are deprecated, however, and may be removed in a future version.
** If you need information on the old syntax, check out the [[Lua_AI_Legacy_Methods_Howto|Lua AI legacy documentation]].
* The current syntax was originally called ''external Lua CAs''. However, as this has now become the standard, we drop the ''external'' and simply call them ''Lua CAs''.
* Formula AI CAs contain some additional keys. As we do not recommend using the ''fai'' engine any more, we do not describe this syntax here and refer to the [[Formula_AI_Howto|Formula AI legacy documentation]] instead.

Here are examples of [candidate_action] tag uses:

'''Combat CA''' of the default AI:
<syntaxhighlight lang='wml'>
[candidate_action]
id=combat
engine=cpp
name=ai_default_rca::combat_phase
max_score=100000
score=100000
[/candidate_action]
</syntaxhighlight>

'''Lua AI CA''':
<syntaxhighlight lang='wml'>
[candidate_action]
engine=lua
name=return_guardian_bob
id=return_guardian_bob
max_score=100010
location="~add-ons/my_addon/lua/return_guardian.lua"
[args]
id=Bob
return_x=10
return_y=15
[/args]
[/candidate_action]
</syntaxhighlight>

=== Available Candidate Actions ===

* '''''cpp''''' '''engine''': The available CAs of the default AI are given [[RCA_AI#Available_Candidate_Actions|here]].
* '''''lua''''' '''engine''': The [[Micro AIs]] are written using Lua CAs, which can be used either as they are or as templates for [[Creating_Custom_AIs#Setting_Up_a_Custom_AI|creating your own CAs]]. They can be found [https://github.com/wesnoth/wesnoth/tree/master/data/ai/micro_ais/cas here].
* '''''fai''''' '''engine''': As we said above, we do not recommend using the ''fai'' engine any more for creating custom CAs. However, if you want to do so, a few simple Formula AI CA examples can be found in the [[Formula_AI_Howto|Formula AI legacy documentation]].

== The [ai] Tag — Aspects ==

The values of aspects are used by the candidate actions of the default AI as parameters influencing the AI behavior. Thus, for the most part, they only apply to the CAs of the default AI. It is, however, possible to write Lua CAs which query certain aspects and take them into account. For example, some of the [[Micro AIs]] respect some of the default aspects.

A huge number of aspects are available for the default AI. They are therefore given [[AiWML|their own page]]. Only the syntax and internal structure of the aspect configuration is shown here.

There are two types of syntax for defining aspects. In the following, we slowly walk you through these using increasingly complex examples, with the full definition of all the possible key and tags listed at the end of this section.

The vast majority of aspects can be defined using a straight-forward syntax of simply defining their values using keys or tags. These are sometimes referred to as ''simple'' aspects, though the simplicity is in the syntax rather than a feature of the aspect. (In actual fact, this syntax defines facets of a ''composite'' aspect.) Examples are
<syntaxhighlight lang='wml'>
[ai]
time_of_day=dawn
aggression=0.765
[/ai]
</syntaxhighlight>
or
<syntaxhighlight lang='wml'>
[ai]
[avoid]
terrain=W*
[/avoid]
[ai]
</syntaxhighlight>
For simple aspect syntax, several additional keys are available in addition to the aspect names themselves, '''time_of_day''' (as shown in the example above), '''turns''' and {{DevFeature1.13|5}} '''engine'''. These are also explained at [[AiWML]], but these keys basically affect all aspects defined in this simple syntax. {{DevFeature1.13|5}} Currently, every aspect except the attacks aspect can be defined in this way. Prior to 1.13.5, there were also a few other aspects that could not be defined in this way.

{{DevFeature1.13|5}} Occasionally, a more complex structure is required. Any aspect name can be used as a tag which contains the contents of a [facet] tag. Thus, the above two examples could also be implemented like this:
<syntaxhighlight lang='wml'>
[ai]
[aggression]
time_of_day=dawn
value=0.765
[/aggression]
[avoid]
[value]
terrain=W*
[/value]
[/avoid]
[/ai]
</syntaxhighlight>
This syntax has the advantage of allowing you to set the facet ID as well as the invalidate keys, if desired. They are not affected by toplevel ''turns'', ''time_of_day'', and ''engine'' keys. However, they expand in a very similar way to the simpler syntax - that is, they define a facet of a composite aspect. In the case of aspects that require a tag in both syntaxes (such as ''avoid''), it's the presence of [value] that disambiguates them.

The third way of defining an aspect is to use the full syntax, which is sometimes called ''complex aspects'', though this is merely a feature of the syntax and not something inherent to any given aspect. All simple aspects expand to equivalent complex aspects, after all. A complex aspect uses the following keys:
*'''engine'''=cpp: The engine to use for this tag. This can usually be omitted.
*'''id''': A unique identifier for the aspect. This is mainly used for [modify_ai].
*'''name''': Only required for the ''cpp'' engine. Possible values are ''standard_aspect'', ''composite_aspect'', ''lua_aspect'', and ''ai_default_rca::aspect_attacks''. Most of these values are only valid with the cpp engine, while ''lua_aspect'' is only valid with the Lua engine. A sensible default is normally chosen, allowing this to be omitted. {{DevFeature1.13|5}} Prior to 1.13.5, some of these values would not work in certain contexts, but in 1.13.5, any valid value may be used here in any aspect context.
*'''invalidate_on_*''' keys: These four keys are primarily for advanced usage. They are described in more detail below.

A complex aspect contains additional keys and tags based on the value of its name attribute. Standard aspects contain either a '''value''' attribute or a '''[value]''' tag which specifies the attribute's value. The attack aspect contains the '''[filter_own]''' and '''[filter_enemy]''' tags, as described [[AiWML#Filtering_Combat_with_the_attacks_Aspect|here]]. Lua aspects contain additional keys as defined [[LuaAI#Dynamic_Lua_Aspects|here]]. And composite aspects contain the following additional tags:
*'''[facet]''': A sub-aspect which will be taken as the value of the aspect, unless its '''turns''' and '''time_of_day''' keys do not match. {{DevFeature1.13|5}} Formerly this had to be a standard aspect, but as of 1.13.5 it can be any type of aspect, such as a composite aspect or a Lua aspect.
*'''[default]''': A sub-aspect which will specifies the default value of the aspect, which is used if there are no facets or if all facets are inactive. {{DevFeature1.13|5}} Formerly this had to be a standard aspect, but as of 1.13.5 it can be any type of aspect, such as a composite aspect or a Lua aspect. '''Note: Overriding the default aspect is generally not recommended. It's just as easy to simply add an unconditional facet instead.'''

At the toplevel within the [ai] tag, complex aspects are defined by an [aspect] tag containing the various keys and tags that define the aspect. Typically, these toplevel aspects are composite aspects, meaning that they contain facets to specify the actual value of the aspect (though they can easily be changed to Lua aspects {{DevFeature1.13|5}} or standard aspects). The '''id''' attribute in an [aspect] tag ''must'' be a valid aspect name, otherwise it will give an error and be ignored.

Let's try to explain this using the aggression example from above. If we wanted to define that using the complex aspect syntax, it would look like this:
<syntaxhighlight lang='wml'>
[ai]
[aspect]
id=aggression
[facet]
id=custom_aggression # Can be used to remove this facet later
time_of_day=dawn
value=0.765
[/facet]
[/aspect]
[/ai]
</syntaxhighlight>

The most important part is that the composite aspect structure uses so-called ''facets'', which contain the value of the aspect. If the aspect is a single scalar value, such as in this example, that value is assigned using the '''value''' key. If it is a tag, such as [avoid], the content of the tag is added inside a '''[value]''' tag. For example:
<syntaxhighlight lang='wml'>
[facet]
engine=cpp
id=custom_avoid
name=standard_aspect
[value]
terrain=W*
[/value]
[/facet]
</syntaxhighlight>

That’s it for the most practical purposes, although there a few more parameters in the full aspect configuration:
<syntaxhighlight lang='wml'>
[aspect]
engine=cpp
id=aggression
invalidate_on_gamestate_change=no
invalidate_on_minor_gamestate_change=no
invalidate_on_tod_change=yes
invalidate_on_turn_start=yes
name=composite_aspect
[facet]
engine=cpp
id=
invalidate_on_gamestate_change=no
invalidate_on_minor_gamestate_change=no
invalidate_on_tod_change=yes
invalidate_on_turn_start=yes
name=standard_aspect
time_of_day=dawn
turns=
value=0.765
[/facet]
[default]
engine=cpp
id=custom_aggression
invalidate_on_gamestate_change=no
invalidate_on_minor_gamestate_change=no
invalidate_on_tod_change=yes
invalidate_on_turn_start=yes
name=standard_aspect
time_of_day=dawn
turns=
value=0.4
[/default]
[/aspect]
</syntaxhighlight>

Thus, the full list of keys and tags inside the [aspect] tag is as follows:
* '''engine'''=cpp: The engine processing the aspect. Most often this is 'cpp', which is also the default and can therefore be omitted, but it is also possible to define dynamic Lua aspects. These have the syntax [[Wesnoth_AI_Framework#Dynamic_Lua_Aspects|shown below]]. (Note: engine=fai is not supported for aspects.)
* '''id''': This must be set to the aspect name (yes, name) shown at [[AiWML]].
* '''name'''=composite_aspect: As described above.
* '''invalidate_on_turn_start'''="yes": (boolean) If "yes", the value of this aspect is invalidated at the start of each AI turn.
* '''invalidate_on_tod_change'''="yes": (boolean) If "yes", the value of this aspect is invalidated when the absolute time of day bonus changes anywhere on the map. This implies invalidate_on_turn_start. {{DevFeature1.13|5}} Before 1.13.5, this was not implemented.
* '''invalidate_on_gamestate_change'''="no": (boolean) If "yes", the value of this aspect is invalidated on each game state change (on turn start, move, attack, recruit, etc.). This implies invalidate_on_turn_start.
* '''invalidate_on_minor_gamestate_change'''="no": (boolean) If "yes", the value of this aspect is invalidated on each minor game state change (on set unit variable, etc). This implies invalidate_on_gamestate_change. (Currently this is not implemented.)
* '''code''': (Lua engine only) If the aspect is defined dynamically in Lua, this key contains the Lua code to be executed. See [[Wesnoth_AI_Framework#Dynamic_Lua_Aspects|below]].
* '''[facet]''' or '''[default]''': These tags define the aspect values. '''[default]''' contains the default value assigned to the aspect at the start of the game. It cannot be modified or deleted. '''[facet]''' tags contain the custom values for the aspect and override the value from [default]. If there are several [facet] tags, the most recent one active at the current time of day and turn number is applied. The tags contain the following keys:
** '''engine''': Same as above, overrides the key with same name in the [aspect] tag
** '''id''': This has a different meaning from the [aspect] tag ''id'' key. It can be freely chosen and is only needed if you plan to [[Modifying_AI_Components#Modifying_Standard_Aspects|modify or remove]] the aspect at a later time. If not, the ''id'' can be omitted. Not used in the [default] tag.
** The different '''invalidation keys''': They have the same meaning as those under the [aspect] tag, but apply only to this facet.
** '''name''': Possible values include 'standard_aspect' and 'composite_aspect', as described above. The engine chooses the correct value automatically, so you never have to worry about this unless you're doing something unusual.
** '''time_of_day''' and '''turns''': Define when the aspect is active. See [[AiWML#Defining_Aspects_and_Goals_of_the_RCA_AI|here]] for details. Not valid in '''[default]'''.
** '''value''' or '''[value]''': This, finally, is the actual value the facet returns. See the examples above for syntax.

All of this is admittedly a bit complex. This is done because there are a couple aspects which require all these keys and customization functionality. In the vast majority of cases, you do not have to worry about this and can simply use the ''standard'' aspect syntax of the first two examples.

'''Note:''' If unsure, the easiest way to see the full configuration for any given aspect (or any other AI component, in fact) is either in savefiles, or in-game by typing <code>:inspect</code> in debug mode and choosing 'ai config full' for a team.

==== Some more on the invalidation keys ====

A few of the aspects return a significant amount of information, as opposed to only a single value (such as ''aggression'') or an array of locations (such as ''avoid''). For example, the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|''attacks'' aspect]] returns a list of possible attacks of the filtered attacker/target unit pairs, together with ratings for many different aspects of these attacks. This list, originally established at the beginning of the AI turn, is not valid any more after the first attack has been performed and needs to be reset. The AI does this by "invalidating" the aspect, after which the aspect information is calculated anew the next time the aspect is queried by a candidate action.

If you check out the default values of the invalidation keys, you see that, in the default configuration, information stored about aspects is reevaluated only at the beginning of each AI turn and when the time of day changes. It is not reevaluated by default after the game state changes (such as after an attack) during the AI turn. This works for most aspects, but not for the ''attacks'' aspect (and it might not be sufficient for all custom aspects either). This is the reason why <code>invalidate_on_gamestate_change=yes</code> needs to be set explicitly for the ''attacks'' aspect as [[AiWML#Filtering_Combat_with_the_attacks_Aspect|shown here]].

As a final comment, you can see at that link that the ''attacks'' aspect is also an exception in that its configuration and definition do not contain a value key or [value] tag, but '''[filter_own]''' and '''[filter_enemy]''' tags. If you look at the configuration in the inspector, you will also see that it has ''name=ai_default_rca::aspect_attacks'' instead of ''standard_aspect''. In other words, the attacks aspect is never a standard aspect (though it can be a composite or {{DevFeature1.13|5}} Lua aspect).

==== Dynamic Lua Aspects ====

It is also possible to [[LuaAI#Dynamic_Lua_Aspects|define aspects dynamically in Lua]]. In that case, no [default] and [facet] tags are added to the configuration. They are replaced by the '''code''' key used to define the aspect. For the second example given at the link above, the configuration looks like this:
<syntaxhighlight lang='wml'>
[aspect]
code=<<
local value = wesnoth.current.turn / 10.
return value
>>
engine=lua
id=aggression
invalidate_on_gamestate_change=no
invalidate_on_minor_gamestate_change=no
invalidate_on_tod_change=yes
invalidate_on_turn_start=yes
name=lua_aspect
[/aspect]
</syntaxhighlight>

It's also possible to put all of that ''in'' a [facet] tag, rather than in an [aspect] tag – this would allow the Lua aspect to take effect only at certain times of day, for example.

== The [ai] Tag — Goals ==

Goals are essentially a special type of aspect, in that they are used to customize the behavior of the default (RCA) AI. However as [[RCA_AI#RCA_AI_Aspect_and_Goal_Configuration|described here]], the default goals are not stored in configuration files. Similarly, custom goals are stored in a different format in the AI configuration than the aspects. Fortunately, this format is the same as that used for [[AiWML#Examples_of_.5Bgoal.5D_Tag_Usage|defining custom goals]]. See the examples given there for syntax.

== The [ai] Tag — Engines ==

As stated above, it is not necessary to define engines any more these days. Just for reference, we list the possible attributes of the [engine] tag here nevertheless.

* '''id''': (string) Optional id of the engine.
* '''engine'''=cpp: (string) The type of engine used to parse this [engine] config snippet. This will always be cpp, since the lua and fai engines are not equipped for parsing [engine] tags.
* '''name'''=cpp: (string) Name of the [engine]. Must be a valid engine name (cpp, lua, or fai).
* '''code''': If <code>name=lua</code> only. The Lua code to add to the engine. See the [[Lua_AI_Legacy_Methods_Howto#Lua_AI_Setup|old method for setting up custom Lua CAs]] for details. It should generally <code>return ...</code> or similar - if it doesn't, other components using the Lua engine may not be able to function correctly.

== See also ==
* [[Wesnoth AI]]
* [[AiWML]]

[[Category:AI]]

DirectActionsWML

2024-07-28T18:06:01Z

Laela: /* [cancel_action] */

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

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

The following tags are actions:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''.

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

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

=== [petrify] ===

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

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

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

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

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

Removes an object from matching units.

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

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

Note that [remove_object] works the following way:

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

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

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

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the trait to be removed. See [[UnitsWML#.5Btrait.5D|[trait]]].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{DevFeature1.15|0}}
In a '''capture'''/'''moveto''' [event], interrupt the attack.

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

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

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount. When harming multiple units, the special variable '''$this_unit''' can be used to access the current unit being harmed. This obviously does not work inside the filters though, as they give '''$this_unit''' a different meaning.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': (default yes) If there is a harmer, experience will be attributed similar to regular combat. Can take list of values. When any value is provided, all unspecified experience types default to not giving experience. Supported values: {{DevFeature1.17|25}} until that version only experience=yes and experience=no are supported
** no - none of involved units get any experience (this value only works if it is the only value in list)
** kill - the harming unit receives experience based on level of harmed unit in attack which kills harmed unit
** attack - the harming unit receives experience based on level of harmed unit in attack which does not kill harmed unit, or in attack which kills harmed unit while kill experience is disabled
** defend - the unit being harmed receives experience based on level of harming unit in attack which does not kill harmed unit
** fight - short form of experience=attack,defend
** yes - short form of experience=kill,attack,defend
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

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

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

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

=== [remove_time_area] ===

{{DevFeature1.13|2}}

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

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

=== [replace_map] ===

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement. ('''NB''': due to https://github.com/wesnoth/wesnoth/issues/5757 this attribute is ignored in versions 1.16.*. The fix was delivered in 1.17.* but wasn't backported due to backward-compatibility requirements)

=== [tunnel] ===

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

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

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

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

=== [do_command] ===

{{DevFeature1.13|0}}

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

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

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

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

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

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

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

=== [set_achievement] ===

{{DevFeature1.17|13}}

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

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

=== [set_sub_achievement] ===

{{DevFeature1.17|17}}

Sets the specified sub-achievement as completed.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

=== [progress_achievement] ===

{{DevFeature1.17|13}}

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

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

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

== See Also ==

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

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

UnitTypeWML

2024-07-21T23:10:36Z

Laela: /* Attacks */ attack_weight

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.
::WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

InterfaceActionsWML

2024-07-10T13:40:47Z

Laela: /* [message] */

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

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

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

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

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

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). [message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

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

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

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

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

<nowiki>You are victorious!</nowiki>

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

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

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

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

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

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

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

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

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

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item. All menus will be sorted lexicographically by the id string. The ordering is underscores, digits, and finally letters.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item, defaults to "buttons/WML-custom.png"
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

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

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

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

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

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

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

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

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

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

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

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

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

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

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

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

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

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

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

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

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

=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

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

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

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music] ===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax

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

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

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

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

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

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit
* '''object_id''': object id to use, defaults to the '''image''' key with an "overlay_" prefix; this allows using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']]
* '''duration''': object duration

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

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

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

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

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

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

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

The meanings of the deprecation levels are as follows:

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

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

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

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

=== [test_condition] ===

{{DevFeature1.13|2}}

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

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

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

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

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

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

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

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

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

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

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

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

InterfaceActionsWML

2024-07-09T20:32:52Z

Laela: /* [message] */

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

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

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

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

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

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). [message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

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

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

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

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

<nowiki>You are victorious!</nowiki>

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

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

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

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

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

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

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

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

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

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item. All menus will be sorted lexicographically by the id string. The ordering is underscores, digits, and finally letters.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item, defaults to "buttons/WML-custom.png"
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

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

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

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

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

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

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

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

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

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

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

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

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

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

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

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

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

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

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

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

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

=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

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

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

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music] ===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax

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

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

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

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

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

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit
* '''object_id''': object id to use, defaults to the '''image''' key with an "overlay_" prefix; this allows using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']]
* '''duration''': object duration

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

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

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

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

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

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

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

The meanings of the deprecation levels are as follows:

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

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

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

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

=== [test_condition] ===

{{DevFeature1.13|2}}

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

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

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

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

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

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

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

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

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

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

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

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

Wesnoth Formula Language

2024-07-08T12:41:33Z

Laela: /* rotate_loc_around */

<div class="tright"> __TOC__ </div>

The Wesnoth Formula Language is a functional language used to evaluate expressions within the game engine. The most common use of WFL is in the [[VariablesWML#Variable_Substitution|<code>$(formula)</code> substitution]] syntax, which allows the use of formulas wherever variables are parsed, but it can also be used in [[FilterWML|filters]], [[GUIToolkit|GUI2 dialogs]], [[AbilitiesWML|unit abilities]] and even [[FormulaAI|AI]].

All formulas should be enclosed in quotes, as in this example: <code>key = "(formula-expression)"</code>. This avoids issues concerning the interpretation of the plus sign, which has a special meaning in WML. Some locations (for example unit abilities) require you to enclose the formula in parentheses, taking the value as a simple number otherwise, but others (such as filters) do not require the parentheses.

Generally, you do not use a <code>$</code> to introduce a formula. The <code>$</code> introduces a variable substitution, which is a separate concept from formulas (but allows using a formula if you wish) and works in many, but not all, places where simple text is used. See [[VariablesWML#Variable Substitution|VariablesWML]] for more information about this.

== Data Types and Operators ==

=== Numbers ===

The most common use of WFL is for simple calculations involving numbers. For this, the standard arithmetic operators (<code>+ - * / %</code>) work as you would expect, performing addition, subtraction, multiplication, division, and remainder. The only caveat to watch out for is that <code>/</code> rounds down when used on integers. For example, <syntaxhighlight lang='wfl' inline>5 / 2</syntaxhighlight> will evaluate to <code>2</code>. To avoid this, make sure at least one of the numbers includes a decimal point - <syntaxhighlight lang='wfl' inline>5.0 / 2</syntaxhighlight> will evaluate to <code>2.5</code>. Note that WFL supports only three decimal places of precision; beyond that it will still be rounded down. (So <syntaxhighlight lang='wfl' inline>1.0 / 16</syntaxhighlight> will evaluate to <code>0.062</code> instead of <code>0.0625</code>.) The <code>^</code> operator performs exponentiation (raising to a power) - for example, <syntaxhighlight lang='wfl' inline>2 ^ 3</syntaxhighlight> evaluates to <code>8</code>

'''Note:''' The modulus operator only works if both operands are integers. {{DevFeature1.13|5}} This is no longer the case as of 1.13.5.

You can also use the standard comparison operators (<code>= != < <= > >=</code>) on numbers. This is often useful in unit filters - for example, a formula of <syntaxhighlight lang='wfl' inline>hitpoints < max_hitpoints / 2</syntaxhighlight> will match only if the unit is at less than half health. Comparison operators return 1 for true and 0 for false; there is no boolean type.

One final numeric operator exists - the dice roll. The syntax <syntaxhighlight lang='wfl' inline>3d12</syntaxhighlight> will roll three 12-sided dice and return the sum of the results. Note however that this is not multiplayer-safe, so using it can and will produce OOS errors. {{DevFeature1.13|5}} The dice operator is now synced and should be safe for use in multiplayer contexts.

'''Note:''' {{DevFeature1.13|5}} Some numeric operations will return null instead of a number. This usually involves the exponentiation operator - for example, <syntaxhighlight lang='wfl' inline>(-2) ^ 0.5</syntaxhighlight> attempts to take the square root of -2, which doesn't exist, so it returns null to indicate this. Dividing by zero also returns null, as well as certain [[#Numeric Functions|math functions]] in appropriate circumstances.

=== Strings ===

WFL also supports strings, which must be enclosed in single quotes (<syntaxhighlight lang='wfl' inline>'like this'</syntaxhighlight>). The comparison operators (<code>= != < <= > >=</code>) also work on strings, performing lexicographical comparison (ie, alphabetical order). The comparison is case sensitive.

{{DevFeature1.13|5}}

Strings can be concatenated with the concatenation operator <code>..</code>. They also support interpolations enclosed in square brackets, the contents of which can be any valid formula. For example:

<syntaxhighlight lang='wfl'>
'Some text: [a + b]' where a = 12, b = 10
</syntaxhighlight>

results in the string <code>Some text: 22</code>. (The <code>where</code> operator is explained [[#Variables|below]].)

If you need to include a literal square bracket in a string, write <code>[(]</code> or <code>[)]</code>. For a literal single quote, you can write <code>[']</code>. For example:

<syntaxhighlight lang='wfl'>
'[(]It[']s bracketed![)]'
</syntaxhighlight>

results in the string <code>[It's bracketed!]</code>.

You can index the characters or words of a string with the following syntax:

<syntaxhighlight lang='wfl'>
'Hello World'.char[4]
'Hello World'.word[1]
</syntaxhighlight>

These return <code>o</code> and <code>World</code>, respectively. A third option is also available, <code>item</code>, which splits the string on commas but allows parentheses to prevent a portion of the string from being split up. For example:

<syntaxhighlight lang='wfl'>
'First Item,Second Item,Third Item'.item[1]
'a,b,(c,d,e),f,g'.item[2]
</syntaxhighlight>

These return <code>Second Item</code> and <code>(c,d,e)</code>, respectively.

=== Lists ===

A list is a sequence of values represented as square brackets, [], surrounding a comma-separated list. For instance:

<syntaxhighlight lang='wfl'>
[ 1, 5, 'abc' ]
</syntaxhighlight>

The comparison operators work on lists, performing lexicographical comparison. A specific list index can be obtained with the indexing operator, like this: <syntaxhighlight lang='wfl' inline>my_list[index]</syntaxhighlight>. The first element of a list is numbered 0.

There are four ''vector operators'' (<code>.+ .- .* ./</code>) that perform entrywise operations on lists. For example, <syntaxhighlight lang='wfl' inline>[1,2,3] .+ [12,2,8]</syntaxhighlight> produces <code>[13,4,11]</code>. Both lists must be of the same length to use these operators, and of course, they must contain only numbers.

{{DevFeature1.13|5}}

A negative list index now counts from the end of the list - <code>-1</code> refers to the last element. You can check if an element exists in a list using the <code>in</code> operator. Lists can also be joined with the concatenation operator <code>..</code>, and sliced using the range operator <code>~</code>. In fact, the range operator produces a list of consecutive numbers, and in fact any list of numbers can be used to index a list - the result is to take the elements at the requested indices, in order. Some examples:

<syntaxhighlight lang='wfl'>
[1, 7, 'abc', 2.5, 'foobar', 127][1~3]
(10~20)[[0,-1]]
[1, 7, 'abc', 2.5, 'foobar', 127][[2,4]]
</syntaxhighlight>

These result in the following lists:

[7, 'abc', 2.5]
[10,20]
['abc', 'foobar']

=== Maps ===

A map is a sequence of key-value pairs. For example:

<syntaxhighlight lang='wfl'>
[12 -> 'Hello', [1,2] -> 9, 'abc' -> 1.5]
</syntaxhighlight>

The comparison operators work on maps. A specific element of a map can be obtained with the indexing operation. In the above example, the following conditions are all true (assuming the map is in a variable called <code>self</code>):

* <syntaxhighlight lang='wfl' inline>self[12] = 'Hello'</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self[[1,2]] = 9</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self['abc'] = 1.5</syntaxhighlight>

{{DevFeature1.13|5}}

You can now use the <code>in</code> operator to test if a key exists in the map. You can also access string keys using the dot operator <code>.</code> as long as they are valid identifiers. (Valid identifiers contain letters and underscores only; no digits are permitted.)

Note that the selection indexing that lists use is ''not'' valid for maps - a list can be used as a key, after all.

=== Objects ===

An object is a container containing additional variables (see [[#Variables|below]] for further explanation of variables) which are not in the global scope. The ''dot operator'' can be used to evaluate a formula in the object's scope. For example, suppose ''u'' is a unit object referring to your leader, who is an Elvish Ranger who has taken 12 damage (thus has 30 hit points). Then <syntaxhighlight lang='wfl' inline>u.hitpoints</syntaxhighlight> will evaluate to the number 30. For a more advanced example, <syntaxhighlight lang='wfl' inline>u . (hitpoints < max_hitpoints - 10)</syntaxhighlight> will evaluate to true if the unit has taken more than 10 damage, which in this example, it has. (This could also be written <syntaxhighlight lang='wfl' inline>u.hitpoints < u.max_hitpoints - 10</syntaxhighlight> if you prefer; this enters the scope twice, instead of once, but the result is identical.)

Objects generally cannot be created directly by the code - they are created for you by the game when formulas are called in certain contexts. However, there are two types of object that ''can'' be created by your code. The first is the location object, which has variables ''x'' and ''y''; it can be created by the [[#loc|<code>loc()</code>]] function. The second is the map pair object, which is returned (or used internally) by several of the built-in functions and has variables ''key'' and ''value''.

=== Other Types and Operators ===

There is one other basic type in WFL - the null type, which is used to mean "no value". It will be returned if you attempt to perform an invalid operation, such as dividing a string. It is also returned by the built-in <code>null()</code> function, which allows you to test if a value is null by writing <syntaxhighlight lang='wfl' inline>value = null()</syntaxhighlight>.

The logical operators <code>and</code> and <code>or</code> can be used to connect conditional expressions, and the unary operator <code>not</code> negates them. Note that <code>or</code> is inclusive - <syntaxhighlight lang='wfl' inline>A or B</syntaxhighlight> is false only if both ''A'' and ''B'' are false. These operators consider <code>0</code> or null to be false, while all other values count as true. The [[#if|<code>if()</code>]] function also follows the same rules to determine whether a value is true or false.

'''Note:''' Programmers familiar with other languages may occasionally be surprised by the fact that <code>and</code> and <code>or</code> do not short-circuit (which would mean that they will never evaluate their second argument if they can know their result solely from the first argument). This should not be a problem in general formula usage, since functions do not have side-effects, but it could make a difference when using the debug functions.

=== Operator Precedence ===

The precedence of various operators is, more or less, what you'd expect - you can write something like <syntaxhighlight lang='wfl' inline>a + b * 2 <= 5 and n - m / 4 > 7</syntaxhighlight> and the engine will do what you expect - first multiplication and division, then addition and subtraction, then comparison, and finally logical conjunction. The only thing to watch out for is when chaining exponentiation - all operators are left associative, so <syntaxhighlight lang='wfl' inline>a ^ b ^ c</syntaxhighlight> will be evaluated as <syntaxhighlight lang='wfl' inline>(a ^ b) ^ c</syntaxhighlight> instead of <syntaxhighlight lang='wfl' inline>a ^ (b ^ c)</syntaxhighlight> like you would expect. {{DevFeature1.13|5}} This has been fixed - exponentiation is now right-associative.

The full precedence list is as follows, from lowest to highest; operators on the same line have equal precedence.

# <code>not</code>
# <code>where</code> clauses
# <code>or</code>
# <code>and</code>
# Comparison operators <code>= != < <= > >= in</code>
# Range-generating operator <code>~</code>
# Additive operators <code>+ - ..</code>
# Multiplicative operators <code>* /</code>
# Modulus <code>%</code>
# Exponentiation <code>^</code>
# Dice operator <code>d</code>
# Dot operator <code>.</code>

== Variables ==

Formulas may have a variety of variables, depending on the context in which they are evaluated. A string substitution formula like <code>$(3 + 5)</code> has no variables, but a [[StandardUnitFilter|unit filter]] formula has variables such as <code>hitpoints</code> and <code>max_hitpoints</code> which contain various properties of the unit being tested (the same unit which is also referred to in variable substitution as <code>$this_unit</code>). The special variable <code>self</code> typically refers to the "global context" - in the case of a unit filter formula, the unit itself. This means for example that <code>self.hitpoints</code> and <code>hitpoints</code> are equivalent when used in a unit filter formula. In a string substitution formula (the <code>$(formula)</code> syntax), <code>self</code> is null. Because of this, you should prefer not to use the substitution syntax in places where formulas are specifically supported.

A formula may declare additional variables using a <code>where</code> clause. This assigns a meaning to any unknown variables in the preceding formula. The general syntax is:

<formula> where <variable> = <value> [, <variable> = value ...]

This functions similarly to an operator, so if desired, you could have multiple where clauses in a single formula. Note that all variables in WFL are read-only - they are variables because they may have different values depending on the context in which the formula is evaluated, but for a given context, they are constant. A variable that has not been assigned a value is considered to have a value of null. Variables are lazily-evaluated - if a where clause declares a variable that is never used, the expression assigned to it will never be evaluated. (This only really matters if it contains a call to a debug function.)

Variable names can contain letters and underscores only. In particular, they cannot contain digits. Also, names are case-sensitive, so ''y'' and ''Y'' refer to two different variables. The following names are reserved and cannot be used for the name of a variable or function:

* <tt>d</tt> - dice operator
* <tt>or</tt> - logical operator
* <tt>in</tt> - containment operator
* <tt>def</tt> - defines a function
* <tt>and</tt> - logical operator
* <tt>not</tt> - logical operator
* <tt>fai</tt> - deprecated synonym of <tt>wfl</tt>
* <tt>wfl</tt> - declares filename
* <tt>where</tt> - declares variables
* <tt>faiend</tt> - deprecated synonym of <tt>wflend</tt>
* <tt>wflend</tt> - closes file scope
* <tt>functions</tt> - lists all defined functions

=== Documentation of some common objects ===

* [[StandardUnitFilter#Wesnoth_Formula_Language|unit objects]]
* [[FilterWML#Filtering_Weapons|weapon objects]]
* [[StandardLocationFilter#Wesnoth_Formula_Language|terrain objects]]
* [[StandardSideFilter#Wesnoth_Formula_Language|side objects]]
* [[ImagePathFunctions#CHAN:_General function|pixel objects]]
* [[ConditionalActionsWML#.5Bvariable.5D|WML objects]]
* [[EventWML#filter_formula|game state objects]]

== Comments ==

Sometimes with particularly complicated formulas, it may be useful to document what's going on inline. Of course, you can use WML comments to do this, but in some cases it may be useful to put some comments in the middle of the formula. This is easily done - simply enclose them in <code>#</code> characters, like this:

<syntaxhighlight lang='wfl'>
#This is a Wesnoth Formula Language comment.#
</syntaxhighlight>

Note the final <code>#</code> - unlike WML, WFL requires this to indicate where the comment ends.

== Functions ==

There are several predefined functions in the Wesnoth Formula Language, and if these are not enough, it is possible to define your own functions. The special variable <syntaxhighlight lang='wfl' inline>functions</syntaxhighlight> always evaluates to a list of all known function names. This is mainly useful only as a debugging tool, though.

To define a function, you use the <code>def</code> keyword. For example:

<syntaxhighlight lang='wfl'>
def sgn(x) if(x < 0, -1, x > 0, 1, 0);
</syntaxhighlight>

This defines a function called <code>sgn</code> which returns the sign of the input number. The semicolon marks the end of the function. It's optional if there's nothing else following the function, but in practice this will very rarely be the case.

Function names have the same limitation as variable names – they can contain only letters numbers, and underscores, and cannot contain digits.

You can select one of the function's arguments to be the "default" argument. If an object is passed to the default argument, then any attributes of that object are directly accessible in the global scope. For example:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u*) hitpoints < max_hitpoints / 2;
</syntaxhighlight>

This function takes a unit and returns 1 if it is at less than half hitpoints. The <code>*</code> indicates the default argument, without which it would instead have to be defined like this:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u) u.hitpoints < u.max_hitpoints / 2;
</syntaxhighlight>

It's important to remember that the function body has access to no variables other than its parameters. For example, the following function would not work (in an AI context) even though the my_leader variable is defined:

<syntaxhighlight lang='wfl'>
def endangers_leader(u) distance_between(u.loc, my_leader.loc) < u.moves;
</syntaxhighlight>

This is because the body of the function can't see the my_leader variable. To make this work, you would need to pass in my_leader as an additional parameter.

'''Note: Prior to 1.14, function definitions only work in AI code and GUI2 code.'''

== Files ==

{{DevFeature1.13|5}}

On occasion, you may find yourself working with formulas complex enough to split them out into a separate file. The formula engine normally assumes that it is executing inline code and reports errors accordingly, but you can tell it to enter a file scope using the special <code>wfl</code> keyword. The convention is to frame your code, so that any file looks like this:

<syntaxhighlight lang='wfl'>
wfl 'filename.wfl'

# Put whatever code you need here, possibly including function definitions. #

wflend
</syntaxhighlight>

The matching <code>wflend</code> is required.

'''Note:''' This functionality was available prior to 1.13.5 using keywords <code>fai</code> and <code>faiend</code>. These keywords are now deprecated, but still work.

== Core Functions ==

Many of the core functions exhibit two features that (as of 1.13.4) cannot be used in user-defined functions. The first is the ability to accept a varying number of arguments - some core functions accept any number of arguments, while others have a few optional arguments. The second is that arguments are lazily-evaluated, and in some cases some arguments will not be evaluated at all, while others may be evaluated multiple times with different variable values. The description of each function will explain how and when its arguments are evaluated.

Most of the core functions can be used from any formula. However, there are some that are only available in formulas that have access to the game state. These functions can be used in [[FilterWML]] formulas and [[AbilitiesWML]] formulas, but not in GUI formulas and substitution formulas (using <tt>$</tt>).

=== Conditional Functions ===

There are two functions which return one of their input values based on some condition - the <code>if</code> function, and the <code>switch</code> function. Both evaluate only as many parameters as is needed to determine which value to return. In particular, parameters that are neither returned nor part of the condition will never be evaluated.

==== if ====

* if(''condition'', ''if true'' [, ''condition 2'', ''if true 2'', ...] [, ''otherwise''])

This function first evaluates the ''condition'', which is a formula. If it evaluates to true, then the function evaluates and returns the ''if true'' parameter; otherwise, it tries the next condition (if any) with the same result. If none of the conditions evaluate to true, then it returns the ''otherwise'' parameter if present, or <code>null()</code> otherwise.

For instance, an AI that recruits Wolf Riders on the first turn, and Orcish Grunts thereafter might look like this:

<syntaxhighlight lang='wfl'>
if(turn = 1, recruit('Wolf Rider'), recruit('Orcish Grunt'))
</syntaxhighlight>

==== switch ====

* switch(''formula'', ''value 1'', ''outcome 1'' [, ... , ''value N'', ''outcome N''] [, ''default outcome''])

The switch function first evaluates the input ''formula'', and then checks if it is equal to any of the specified ''values''. If matching value is found, the ''outcome'' assigned to it is returned; if not, then function returns either ''default outcome'' (if specified) or null.

=== Numeric Functions ===

Several basic math functions are available. These generally work equally on integer and decimal values.

==== abs ====

* abs(''number'')

Returns the absolute value of an input number; for example

<syntaxhighlight lang='wfl'>
abs( -5 )
</syntaxhighlight>

will return 5.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== acos ====

{{DevFeature1.13|5}}

* acos(''number'')

Returns the arccosine of the input number, in degrees.

==== asin ====

{{DevFeature1.13|5}}

* asin(''number'')

Returns the arcsine of the input number, in degrees.

==== atan ====

{{DevFeature1.13|5}}

* atan(''number'')

Returns the arctangent of the input number, in degrees.
==== as_decimal ====

* as_decimal(''number'')

Ensures that the number is a decimal rather than an integer; useful if you're dividing two unknown values and want to ensure that the result is a decimal.

==== cbrt ====

{{DevFeature1.13|5}}

* cbrt(''number'')

Returns the cube root of the input number. This is better than using the exponentiation operator, because it will give the correct result for negative numbers.

==== ceil ====

* ceil(''number'')

Returns the ceiling of the specified number, ie rounding it up to the nearest integer.

==== clamp ====

{{DevFeature1.17|0}}

* clamp(''number'', ''min'', ''max'')

Combines min and max into a single call. If ''number'' is less than ''min'', returns ''min''; if it's greater than ''max'', returns ''max''. Otherwise, returns ''number''.

==== cos ====

* cos(''angle'')

Returns the cosine of the given angle, which is specified in degrees.

==== exp ====

{{DevFeature1.13|5}}

* exp(''number'')

Returns the exponential of the input number, which is the constant ''e'' raised to the specified power.

==== floor ====

* floor(''number'')

Returns the floor of the specified number, ie rounding it down to the nearest integer.

==== frac ====

{{DevFeature1.13|5}}

* frac(''number'')

Returns the fractional part of the specified number.

==== hypot ====

{{DevFeature1.13|5}}

* hypot(''x'', ''y'')

Returns the hypoteneuse length of a triangle with sides ''x'' and ''y''.

==== lerp ====

{{DevFeature1.17|0}}

* lerp(''min'', ''max'', ''fraction'')

Returns a linear interpolation between ''min'' and ''max'' according to the specified ''fraction''.

==== log ====

{{DevFeature1.13|5}}

* log(''number'', [, ''base''])

Returns the logarithm of the input number. If ''base'' is omitted, it returns the natural logarithm; otherwise, the logarithm to the specified base.

==== max ====

* max(''list of numbers'')

Returns the largest number from the list. For example:

<syntaxhighlight lang='wfl'>
max([2, 8, -10, 3])
</syntaxhighlight>

will return <code>8</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== min ====

* min(''list of numbers'')

Returns the smallest number from the list. For example:

<syntaxhighlight lang='wfl'>
min( [ 3, 7, -2, 6] )
</syntaxhighlight>

will return <code>-2</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== pi ====

{{DevFeature1.13|5}}

* pi()

Returns pi.

==== root ====

{{DevFeature1.13|5}}

* root(''number'', ''base'')

Returns the root of the input number, to the specified base. This is better than using the exponentiation operator, because it will give the correct result for negative numbers and odd bases (for example, the fifth root of -32, which is -2).

==== round ====

* round(''number'')

Returns the specified number rounded to the nearest integer.

==== sgn ====

{{DevFeature1.13|5}}

* sgn(''number'')

Returns the sign of the number, ie -1 if it is negative, 1 if it is positive, and 0 if it is zero.

==== sin ====

* sin(''angle'')

Returns the sine of the given angle, which is specified in degrees.

==== sqrt ====

{{DevFeature1.13|5}}

* sqrt(''number'')

Returns the square root of the input number.

==== sum ====

* sum(''list of numbers'')

This function evaluates to the sum of the numbers in the ''list of numbers''. For example:

<syntaxhighlight lang='wfl'>
sum([ 2, 5, 8])
</syntaxhighlight>

returns <code>15</code>, and:

<syntaxhighlight lang='wfl'>
sum(map(my_units, max_hitpoints - hitpoints))
</syntaxhighlight>

finds the total damage your units have taken.

==== tan ====

{{DevFeature1.13|5}}

* tan(''number'')

Returns the tangent of the given angle, which is specified in degrees.

==== trunc ====

{{DevFeature1.13|5}}

* trunc(''number'')

Returns the truncation of the specified number, ie rounding it towards zero. This is different from floor when applied to negative numbers - floor(-7.5) gives -8, but trunc(-7.5) gives -7.

==== wave ====

* wave(''number'')

Given a numeric value V, this returns:

sin(2*pi*V)

=== String Functions ===

There are a few useful functions for manipulating strings.

==== concatenate ====

* concatenate(''value1''[, ''value2'', ...])

Converts each of its arguments to a string, and concatenates the result together into a single string.

==== contains_string ====

* contains_string(''string'', ''search_string'')

Returns 1 if ''search_string'' can be found within ''string'' (as a substring), 0 otherwise. For example:

<syntaxhighlight lang='wfl'>
contains_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>1</code>.

==== length ====

* length(''string'')

Returns the length of the input string.

==== find_string ====

{{DevFeature1.13|5}}

* find_string(''string'', ''search_string'')

Returns the index at which ''search_string'' starts within ''string'' (as a substring), or -1 if it is not found. For example:

<syntaxhighlight lang='wfl'>
find_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>4</code>.

==== replace ====

{{DevFeature1.13|5}}

* replace(''string'', ''offset'', [''size'',] ''replacement'')

Returns a new string obtained by replacing a portion of the input ''string'' with the contents of the ''replacement'' string. The ''offset'' and ''size'' work the same as for <code>substring</code>. Examples:

<syntaxhighlight lang='wfl'>
replace('The quick brown fox jumps over the lazy dog!', 4, 5, 'dumb')
replace('The quick brown fox jumps over the lazy dog!', -9, 4, 'sleeping')
replace('The quick brown fox jumps over the lazy dog!', -9, 'brook!')
replace('The quick brown fox jumps over the lazy dog!', -6, -4, 'yellow')
</syntaxhighlight>

return the following strings:

'The dumb brown fox jumps over the lazy dog!'
'The quick brown fox jumps over the sleeping dog!'
'The quick brown fox jumps over the brook!'
'The quick brown fox jumps over the yellow dog!'

==== substring ====

* substring(''string'', ''offset''[, ''size''])

Extracts a substring from the given input string. The ''offset'' specifies the first character to extract; the first character is <code>0</code>, and negative values count from the end, so the last character is <code>-1</code>. If specified, the ''size'' indicates the total number of characters to extract; it cannot be negative. If omitted, all characters from the ''offset'' to the end of the string are returned. For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', 4, 5)
substring('The quick brown fox jumps over the lazy dog!', -9, 4)
substring('The quick brown fox jumps over the lazy dog!', -9)
</syntaxhighlight>

return <code>'quick'</code>, <code>'lazy'</code>, and <code>'lazy dog!'</code> respectively.

{{DevFeature1.13|5}} The ''size'' can now be negative. This means to count backwards from the given ''offset'' (but always including the given offset, so a ''size'' of -1 gives the same result as 1). For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', -6, -4)
</syntaxhighlight>

returns <code>'lazy'</code>.

=== List and Map Functions ===

This section contains functions that directly manipulate a map or list.

==== head ====

* head(''list'' [, ''count''])

Returns the first item from the ''list''; for example

<syntaxhighlight lang='wfl'>
head([5, 7, 9])
</syntaxhighlight>

returns <code>5</code>, and

<syntaxhighlight lang='wfl'>
head( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Orc'</code>.

{{DevFeature1.13|5}} If a second argument is given, it returns a list containing the first ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>head(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>head(L,1)</syntaxhighlight> - the former returns the first element, while the latter returns a list containing only the first element.

==== index_of ====

* index_of(''value'', ''list'')

This function will return the first index where ''value'' can be found in the input ''list''. It will return -1 if the value is not found in the ''list'.

==== keys ====

* keys(''map'')

Extracts the key values from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
keys(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

['Elvish Fighter', 'Elvish Archer']

==== size ====

* size(''list'')

This function returns the number of elements in the ''list''.

For example, <syntaxhighlight lang='wfl' inline>size([5, 7, 9])</syntaxhighlight> returns <code>3</code> and <syntaxhighlight lang='wfl' inline>size(['Archer', 'Fighter'])</syntaxhighlight> returns <code>2</code>.

==== sort ====

* sort(''list'', ''formula'')

This function evaluates to a result list sorted according to the comparison ''formula'' for each item <code>a</code> and its successor <code>b</code>. For instance, sorting units according to hitpoints would be done by:

<syntaxhighlight lang='wfl'>
sort(my_units, a.hitpoints > b.hitpoints)
</syntaxhighlight>

To sort them in the reverse order, simply use <code><</code> instead of <code>></code>.

==== tail ====

{{DevFeature1.13|5}}

* tail(''list'' [, ''count''])

Returns the last item from the ''list''; for example

<syntaxhighlight lang='wfl'>
tail([5, 7, 9])
</syntaxhighlight>

returns <code>9</code>, and

<syntaxhighlight lang='wfl'>
tail( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Human'</code>.

If a second argument is given, it returns a list containing the last ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>tail(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>tail(L,1)</syntaxhighlight> - the former returns the last element, while the latter returns a list containing only the last element.

==== tolist ====

* tolist(''map'')

This function takes a map and return a list of key-value pair objects. For example:

<syntaxhighlight lang='wfl'>
tolist(['Elf' -> 10, 'Dwarf' -> 20])
</syntaxhighlight>

will return:

[{key->'Elf',value->10}, {key->'Dwarf',value->20}]

==== tomap ====

* tomap(''list A'' [, ''list B''])

This function takes one or two ''lists'' as input and returns a map. If only one list is specified, then the function will evaluate this list, count how many similar elements are found within the list, and return a map with keys being these elements, and values being a number representing how many of them the list contains. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf', 'elf', 'elf', 'human', 'human'])
</syntaxhighlight>

will return:

['elf' -> 3, 'dwarf' -> 1, 'human' -> 2]

{{DevFeature1.13|5}} However, if all the elements are key-value pairs such as those created by ''pair'' or ''tolist'', then this function will invert the effect of ''tolist'' and return the original map which would have produced the input list as output when passed to ''tolist''. If only some elements are key-value pairs, those elements will be directly converted into key-value pairs in the resulting map, while other values will be treated as described above.

If two lists are specified, then the elements of the first one will be used as a keys, and the elements of the second one as a values, when creating an output map. Note that these input lists must be of the same length. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf' ], [10, 20])
</syntaxhighlight>

will result in:

['elf' -> 10, 'dwarf' -> 20]

==== values ====

* values(''map'')

Extracts the values assigned to keys from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
values(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

[50, 60]

=== List-processing Functions ===

This section covers functions that operate on maps or lists by applying one or more formulas in succession to each element. Most return another map or list, <code>reduce</code> instead combines all the elements into a single result.

==== choose ====

* choose(''input'', [''self_name'',] ''formula'')

This function evaluates ''formula'' for each item in the ''input'' (which can be a list or a map). It will return the first item to which ''formula'' gave the highest value. For example:

<syntaxhighlight lang='wfl'>
choose(my_units, level)
</syntaxhighlight>

gives back the unit with the highest level.

The implicit input when evaluating a mapping/filtering function's ''formula'' component will be that specific item under evaluation (in this example one of "my_units"), and it can be explicitly referenced as <code>self</code> when necessary. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

When evaluating a map, we can reference each key by <code>key</code> and each value by <code>value</code>. In this case, the <code>self</code> variable is this key-value pair. For example:

<syntaxhighlight lang='wfl'>
choose(['elf' -> 10, 'dwarf' -> 20 ], value)
</syntaxhighlight>

will return a key-value pair

{key->'dwarf', value->20}

The curly braces are used in output to indicate that this is an object, not a map. It is not valid WFL syntax.

==== filter ====

* filter(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map). It will evaluate to a list or map which only contains items that the ''formula'' was true for. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

<syntaxhighlight lang='wfl'>
filter(my_units, hitpoints < max_hitpoints)
</syntaxhighlight>

will return all of your units which have less than maximum hitpoints. For instance this could be used if looking for candidates for healing.

==== find ====

* find(''input'', [''self_name'',] ''formula'')

This function will run <formula> on each item in the <input> (which can be a list or a map) and will return the first item for which <formula> was true. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. For example:

<syntaxhighlight lang='wfl'>
find(units, type = 'Elvish Archer' )
</syntaxhighlight>

will return the first unit of type 'Elvish Archer'.

==== map ====

* map(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map), and evaluate to a new list or map or a map, which contains the same number of items as in ''input'', with the formulas run on each item. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. When run on a map, the resulting map has the same keys as the input map, but with the values updated to the results of the ''formula''. For example:

<syntaxhighlight lang='wfl'>
map([10,20], self*self)
</syntaxhighlight>

and

<syntaxhighlight lang='wfl'>
map([10,20], 'value', value*value)
</syntaxhighlight>

will both result in [100, 400]. The formula:

<syntaxhighlight lang='wfl'>
map(my_units, hitpoints)
</syntaxhighlight>

will give a list back with the number of hitpoints each unit has. This is more useful in conjunction with other functions.

<syntaxhighlight lang='wfl'>
map(['elf' -> 10, 'dwarf' -> 20 ], value*2)
</syntaxhighlight>

The above will produce ['elf' -> 20, 'dwarf' -> 40]. Note that in case of a map data type, the <code>map</code> function can only modify the value.

<syntaxhighlight lang='wfl'>
map(tomap([3,5,8,8]), value+key*100)
</syntaxhighlight>

The above will produce <code>[3 -> 301, 5 -> 502, 8 -> 801]</code>. This can be used to take a list and make a map containing pairs <code>[element_from_that_list -> f(element_from_that_list,number_of_repetitions_of_that_element_in_that_list)]</code> where <code>f</code> is an arbitrary function.

==== reduce ====

* reduce(''list'', [''identity'', ] ''formula'')

This function will run the ''formula'' on the first and second members of the ''list'', then on the result and the third member and so on until the list is depleted. The final result is then returned. The two variables used in the ''formula'' are always 'a' and 'b'.

For example, <syntaxhighlight lang='wfl' inline>reduce([1,2,3,4], a+b)</syntaxhighlight> returns <code>10</code> and <syntaxhighlight lang='wfl' inline>reduce([9,4,8,2], 10*a+b)</syntaxhighlight> returns <code>9482</code>.

{{DevFeature1.13|5}} The new ''identity'' argument specifies the starting value (which is null or 0 by default). If ''list'' is empty, then ''identity'' is returned. Otherwise, the list will be considered as if ''identity'' were an extra first element. For example, to calculate the product of a list of numbers, you might do something like this:
<syntaxhighlight lang='wfl'>
reduce(your_list, 1, a * b)
</syntaxhighlight>

This will return 1 if the list is empty, as expected - the product of no numbers is 1. If the list is not empty, adding 1 to the list will have no effect, since it is the multiplicative identity.

==== take_while ====

{{DevFeature1.13|5}}

* take_while(''list'', ''formula'')

Evaluates the ''formula'' for each element of the ''list'' until it finds one for which it evaluates to false, then returns a list of all elements up to but not including that element. For example:

<syntaxhighlight lang='wfl'>
take_while([1,5,3,6,3,7,9,5,6,4,12,2,53,2,1], self < 10)
</syntaxhighlight>

returns the list <code>[1,5,3,6,3,7,9,5,6,4]</code>.

==== zip ====

{{DevFeature1.13|5}}

* zip(''list1'', ... , ''listN'')
* zip(''list of lists'')

Takes a list of lists and generates a new list of lists such that list ''n'' contains element ''n'' of each of the original lists, in order. If the lists are not all of the same length, it treats them as if they were padded on the end with null values so that they are all the length of the longest list.

<syntaxhighlight lang='wfl'>
zip([1,2,3],[4,5,6])
zip([1,4],[2,5],[3,6])
</syntaxhighlight>

return <code>[[1,4],[2,5],[3,6]]</code> and <code>[[1,2,3],[4,5,6]]</code>, respectively.

=== Location Functions ===

Functions for working with locations on a hex map.

==== adjacent_locs ====

{{DevFeature1.13|9}}

* adjacent_locs(''center'')

Returns a list of all locations adjacent to the specified location. When called from a formula with access to the game state, it automatically excludes locations that don't exist on the map. Otherwise, it operates as if on an infinite map. This means you should generally not expect the returned list to contain exactly 6 elements.

==== are_adjacent ====

{{DevFeature1.13|9}}

* are_adjacent(''loc1'', ''loc2'')

Check if two locations are adjacent. Returns 1 (true) or 0 (false).

==== direction_from ====

{{DevFeature1.13|9}}

* direction_from(''start'', ''direction'', [''distance''])

Returns the hex reached by travelling in the specified direction from a starting hex for a certain distance (default 1 hex).

==== distance_between ====

{{DevFeature1.13|5}}

* distance_between(''start'', ''end'')

Returns the distance between the locations ''start'' and ''end'', which must be location objects such as those created by <code>loc()</code>.

'''Note:''' This function was already available in FormulaAI prior to 1.13.5; however, from 1.13.5 onward it is available to all formulas.

==== loc ====

* loc(''x'', ''y'')

Creates and returns a location object with the specified coordinates. If assigned to a variable ''pos'' (eg with a <code>where</code> clause), the individual coordinates can be accessed as <code>pos.x</code> and <code>pos.y</code>.

==== locations_in_radius ====

{{DevFeature1.13|9}}

* locations_in_radius(''center'', ''radius'')

Returns a list of all locations within a given radius of the specified center hex.
Only locations on the map will be returned.

==== relative_dir ====

{{DevFeature1.13|9}}

* relative_dir(''loc1'', ''loc2'')

Returns the direction you need to travel to progress from one location to another. The returned location is one of the six possible directions on the Wesnoth hex map, or an empty string if both locations are the same.

==== rotate_loc_around ====

{{DevFeature1.13|9}} but returns wrong result until {{DevFeature1.19|2}}

* rotate_loc_around(''center'', ''loc'', ''angle'')

Rotates a location around a given center to produce a new location. The angle is an integer between -6 and 6, which can be understood as a multiple of 60 degrees.

=== Miscellaneous Functions ===

Some functions really don't fit into any category. They are all listed here.

==== null ====

* null([''arguments''])

Evaluates each of its arguments (if any) in order, then returns null. Since formulas generally do not have side-effects, there is little point in specifying any arguments unless you are writing AI code (where several functions do have side-effects).

==== pair ====

{{DevFeature1.13|5}}

* pair(''key'', ''value'')

Creates a key-value pair object, the same as those created by the ''tolist'' function.

==== reverse ====

{{DevFeature1.13|5}}

* reverse(''string or list'')

Returns the input string or list backwards.

==== type ====

{{DevFeature1.13|5}}

* type(''anything'')

Returns the type of its input as a string. Possible results are:

* <code>'integer'</code>
* <code>'decimal'</code>
* <code>'string'</code>
* <code>'list'</code>
* <code>'map'</code>
* <code>'null'</code>
* <code>'object'</code>

=== Debugging Functions ===

There are also a few functions that can be useful for debugging formulas, for example by displaying intermediate results to the screen. Note that this breaks the general rule that functions do not have side-effects.

==== debug ====

* debug([''formula''])

Starts a GUI formula AI debugger when evaluating a formula. It takes a formula, evaluates it and returns the result unchanged. '''Note:''' this does not appear to work in 1.13.3.

{{DevFeature1.13|5}} The formula allows you to step through the formula one operation at a time, viewing the current stack and execution trace. As of 1.13.5, you need to enable [[CommandMode|debug mode]] to use the debugger; otherwise, it will simply be skipped.

==== debug_print ====

'''you need to enable formula log (--log-info='scripting/formula') to see the result of this call'''

* debug_print([''explanation'' ,] ''formula'' )

This function can be used for debugging a formula. It takes a ''formula'', writes its result to the console, and returns it unchanged. For example:

<syntaxhighlight lang='wfl'>
debug_print([1, 2, 3])
</syntaxhighlight>

will result in printing to the console

[1, 2, 3]

and returning the same.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_print'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_print('My array: ', [1, 2, 3])
</syntaxhighlight>

will write in the console:

My array: [1, 2, 3]

and return

[1, 2, 3]

==== debug_profile ====

* debug_profile(''formula'' [, ''explanation''])

Evaluates the formula 1000 times and prints (as with debug_print) a number indicating the average time required to evaluate the formula. Mainly intended for internal testing, but could occasionally be useful for people working with complicated formulas. The optional ''explanation'' argument is used in the same way as in debug_print.

==== debug_float ====

* debug_float(''location'', [''explanation'',] ''formula'' )

This function can be used for debugging a formula. It takes a formula, floats a label containing the result on the hex specified (in the same way damage is displayed) and returns it unchanged. Note that the ''location'' here is an object type; it can be created with the <code>[[#loc|loc()]]</code> function. For example:

<syntaxhighlight lang='wfl'>
debug_float(me.loc, me.id)
</syntaxhighlight>

will make a label containing the id of the unit ''me'' float over the unit.

Return value is also the unit id.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_float'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_float( me.loc, 'id: ', me.id )
</syntaxhighlight>

will float the following label

id: unit_id

and return the unit id.

==== dir ====

* dir(''object'')

This function return a list of all attributes in ''object''. For example:

<syntaxhighlight lang='wfl'>
dir(my_leader)
</syntaxhighlight>

will result in the following output:

[ 'x', 'y', 'loc', 'id', 'type', 'name', 'leader', 'undead', 'traits', 'attacks', 'abilities', 'hitpoints',
'max_hitpoints', 'experience', 'max_experience', 'level', 'total_movement', 'movement_left', 'attacks_left',
'side', 'states', 'cost', 'usage', 'vars']

This command is useful in the formula command line, to get information about the attributes of different types of data.

=== Game State Functions ===

These are functions that access the game state. Therefore, they are not available in all formulas, as described above.

==== base_tod_bonus ====

* base_tod_bonus([''loc'', [''turn'']])

Evaluates the base time-of-day bonus, excluding the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== chance_to_hit ====

* chance_to_hit(''unit'', ''location or terrain'')

Calculates the base chance for the unit to be hit if it moved to the given location or terrain. This is essentially the inverse of its defense. It is returned as an integer between 0 and 100.

==== defense_on ====

* defense_on(''unit'', ''location or terrain'')

Calculates the defense that the unit would have if it moved to the given location or terrain. It is returned as an integer between 0 and 100.

==== enemy_of ====

* enemy_of(''self'', ''other'')

Determines whether two units are enemies. Returns 1 (true) or 0 (false).

==== get_unit_type ====

* get_unit_type(''id'')

Returns an object describing the specified unit type, or null if no such unit type exists. A unit type object has many of the same keys as a unit, excluding those that are expected to change over time such as <tt>hitpoints</tt> or <tt>name</tt>.

==== jamming_cost ====

* jamming_cost(''unit or unit type'', ''location or terrain'')

Calculates the jamming cost for the unit to block vision on the given location terrain.

==== movement_cost ====

* movement_cost(''unit or unit type'', ''location or terrain'')

Calculates the movement cost for the unit to enter the given location or terrain.

==== resistance_on ====

* resistance_on(''unit'', ''location'', ''type'', [''attacker''])

Calculates the unit's resistance to the given damage type when standing on the specified location. If specified, the ''attacker'' parameter should be 1 to indicate that the unit is the attacker, or 0 to indicate that it is the defender, as this status can affect resistances. By default, it is assumed to be the defender.

This is returned not as the raw resistance set in WML, but the actual resistance that the player sees, so it ranges between -100 and 100.

==== tod_bonus ====

* tod_bonus([''loc'', [''turn'']])

Evaluates the final time-of-day bonus, accounting for the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== unit_at ====

* unit_at(''location'')

Returns the unit on the given location, or null if there is no unit there.

==== vision_cost ====

* vision_cost(''unit or unit type'', ''location or terrain'')

Calculates the vision cost for the unit to see through the given location or terrain.

EventWML

2024-07-07T09:05:36Z

Laela: /* Multiplayer safety */

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the term "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
<syntaxhighlight lang='wml'>
name=<value>
</syntaxhighlight>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

<syntaxhighlight lang='wml'>
name=attacker misses,defender misses
</syntaxhighlight>

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

All predefined event types are listed below, along with a description of when this value will cause the event to be triggered, in the [[#Predefined_Events_Without_Filters|Predefined Events Without Filters]] and [[#Predefined_Events_With_Filters|Predefined Events With Filters]] sections. Any value ''not'' listed there is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

Spaces in event names can be interchanged with ''underscores'' (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

==== Variables in the name ====

If the name contains variables, they will be substituted each time the event is triggered. For example, '''name=turn $disaster_turn''' will only trigger if the turn number is currently equal to whatever number is stored in the variable '''$disaster_turn'''; updating the variable will adjust the turn that the event triggers on. However, if the variable contents contains a comma, it won't be parsed after substitution. Since an event name can't contain a comma, this means the event will never trigger.

{{DevFeature1.17|6}}

Commas resulting from variable substitution are now parsed. If you write '''name=$important_event''' and the variable '''$important_event''' contains the text "capture,die", the event will trigger on either a death or a village capture.

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives. Also, custom events come very handy in [[Wml_optimisation]].

Example:
<syntaxhighlight lang='wml'>
# The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

# This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# And now a fire_event tag is used to trigger the previously defined event. To use
# "speaker=unit" in the fired event, it's also necessary to specify the [primary_unit].
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]
</syntaxhighlight>

You can have more code after the '''[fire_event]''', which will run after the fired event has happened.
Example:
<syntaxhighlight lang='wml'>
# This is a standard recall event that triggers whenever a unit is recalled by side 1
[event]
name=recall
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# Fire the custom event, exactly as the in recruit event
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# After that event has happened, the remaining code in this event is run
[message]
speaker=second_unit
message=_ "Glad to have you back"
[/message]
# As a result, every time side 1 recalls a unit, the recalled unit says
# "Reporting for duty!", and the leader replies "Glad to have you back"
[/event]
</syntaxhighlight>

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is mandatory in case of a [unit_type][event].

==== remove ====
: Removes an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if yes, does the same as a [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] with the same id= value, and the other attributes of this event tag are ignored.

{{DevFeature1.13|0}} May be a comma separated list.

{{DevFeature1.15|7}} Prints a deprecation warning recommending to use [remove_event] instead.

==== priority ====
: {{DevFeature1.17|20}} If several '[event]' tags have the same name, then any with a high priority value will be triggered before events with a lower priority value. Negative numbers are also supported, to run after events without a priority (as the attribute defaults to zero). For events with equal priority, the order is determined by the order in which the events were added.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special_id''': filter on the attack's weapon special id.
:* '''special_type''': filter on the attack's weapon special type.
:* {{DevFeature1.17|15}} '''special_id_active''': filter on the attack's weapon special id active(encoded in [specials] or [abilities] tags).
:* {{DevFeature1.17|15}} '''special_type_active''': filter on the attack's weapon special type active(encoded in [specials] or [abilities] tags).

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== [insert_tag] ====
: An '''[insert_tag]''' that expands to any of the above filter tags will result in the filter being loaded from the variable each time the game checks if the event should fire. This can result in the event's filter varying from turn to turn.

==== filter_formula ====
:{{DevFeature1.17|6}}
: Similar to [filter_condition], but the condition is expressed in [[Wesnoth Formula Language]]. The formula has access to the following keys:
:*Event information:
:**'''event''' - the event name
:**'''event_id''' - the event's unique ID
:**'''event_data''' - additional information specific to the event, such as owner_side or damage_inflicted, or anything passed in '''[fire_event][data]'''.
:**'''loc''', '''unit''' - primary event location and unit
:**'''second_loc''', '''second_unit''' - secondary event location and unit
:**'''weapon''', '''second_weapon''' - primary and secondary weapon
:*Gamestate information:
:**'''turn_number'''
:**'''time_of_day''' - the time of day ID
:**'''side_number''' - currently active side
:**'''sides''' - a list of all sides
:**'''units''' - a list of all units on the map
:**'''map''' - the entire game map as a two-dimensional array

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution_2|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]]. Actions can also be dynamically inserted via '''[insert_tag]'''.

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* unit hits
* unit misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
* {{DevFeature1.13|10}} victory
* {{DevFeature1.13|10}} defeat
* {{DevFeature1.13|0}} scenario_end
The following are not synced:
* select
* preload
* victory {{DevFeature1.13|10}} local_victory
* defeat {{DevFeature1.13|10}} local_defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}
</syntaxhighlight>

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef
</syntaxhighlight>

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

<syntaxhighlight lang='wml'>
[event]
id=doubler_event
remove=yes
[/event]
</syntaxhighlight>

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== Predefined Events Without Filters ==

These events do not take filter parameters (except [filter_condition] which works for all events).

=== preload ===

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' If a game is started, saved, and then reloaded, the preload event will fire two times while playing. However, it will only fire once when viewing the replay. If the preload event alters the gamestate the second time it fired while playing (when loading the saved game) then it can result in Out Of Sync errors.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

=== prestart ===

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== start ===

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== new turn ===

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

=== turn end ===

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

=== turn ''X'' end ===

Triggers at the end of turn ''X''.

=== side turn ===

Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

=== ai turn ===

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event can break replays if it is used improperly. The ai turn event does not fire during replays. The intention is only to guide the AI to make choices (movements, attacks) which are then saved to the replay.''

=== turn refresh ===

Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status. WML variable '''side_number''' holds the number of this side.

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

=== turn ''X'' ===

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

=== side ''X'' turn ''Y'' ===

This event triggers at the start of turn ''Y'' of side X

=== side ''X'' turn ===

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn ''X'' ===

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side X turn Y refresh ===

This event triggers at the turn refresh for side X on turn Y

=== side ''X'' turn refresh ===

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== turn ''X'' refresh ===

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn end ===

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

=== time over ===

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

=== enemies defeated ===

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

=== local_victory ===

In Wesnoth 1.12 and earlier, the event described here is '''victory''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_victory'''.

This event will be fired at the end of a scenario, if the player's side won. If it fires as a result of an '''[endlevel]''' tag, the event is processed before the line after the '''[endlevel]]''' tag. The event is not synchronized, as in networked mp it is possible to have different results for different players.

=== local_defeat ===

In Wesnoth 1.12 are earlier, the event described here is '''defeat''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_defeat'''.

Functions identically to '''local_victory''', except that the player's side lost.

=== victory ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''victory''' event is equivalent to 1.14's '''local_victory'''.

This event will be fired at the end of a scenario, if the game will proceed to the next scenario. In multiplayer, this means that it will fire on all players' clients, even for players who received a '''local_defeat''', as long as the game continues to the next scenario. This event is synchronized.

It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":next_level" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign.

=== defeat ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''defeat''' event is equivalent to 1.14's '''local_defeat'''.

This event will be fired at the end of a scenario, if the game resulted in a game-over other than victoriously reaching the end of a campaign (including single-scenario campaigns). Synchronization (including bug #4667) is the same as '''victory'''.

=== scenario_end ===

{{DevFeature1.13|10}} This event fires immediately after '''victory''' or '''defeat'''; it is synchronized, but is also affected by bug #4667.

Note: in 1.13.0 - 1.13.9 this event was added as a synchronized alternative to the events that are, since 1.13.10, called local_victory or local_defeat.

== Predefined Events With Filters ==

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables '''unit''' and '''second_unit''' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, unit_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

=== moveto ===

Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' $x2 and $y2 refer to the hex the unit came from.

=== sighted ===

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away. You may want to use [filter_second] in order to restrict a sighted event in a single player scenario to only being triggered by the player and not by other non-allied sides.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

=== enter_hex ===

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). In Wesnoth 1.12, the movement will be interrupted, stopping the unit where it is; this behavior can be avoided by using the {{tag|DirectActionsWML|allow_undo}} tag or `NO_INTERRUPT_NO_UNDO` macro. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

'''Note:''' At the time of writing (7ca5a0df, just before 1.13.11), if the hex is occupied then $unit contains the occupying unit, not the moving unit.

'''Note:''' At the time of writing (1.16.2), if the hex is occupied then $unit does contain the moving unit.

=== exit_hex ===

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

=== pre attack {{DevFeature1.17|7}}===

Similar to '''attack''', but is triggered before calculating the number of attacks and the movement of the unit. Can be used for modifications, which affect these values.

=== attack ===

Triggers when the primary unit attacks the secondary unit. Variables $weapon and $second_weapon contain weapons used for this attack by primary and secondary units respectively for all attack-related events (attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath).

=== attack end ===

Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

=== attacker hits ===

Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

=== attacker misses ===

Same as ''attacker hits'', but is triggered when the attacker misses.

=== defender hits ===

Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

=== defender misses ===

Same as ''defender hits'', but is triggered when the defender misses.

=== unit hits {{DevFeature1.19|2}} ===

Triggers when the the primary unit (either attacker or defender) hits the secondary unit (the other). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the primary unit.

Compared to ''defender hits'', primary and secondary units are swapped.

=== unit misses {{DevFeature1.19|2}} ===

Same as ''unit hits'', but is triggered when the unit misses.

=== petrified ===
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''petrifies'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

=== last breath ===

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

=== die ===

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

=== capture ===

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

=== recruit ===

Triggers when the primary unit is recruited (by the secondary unit). (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

=== prerecruit ===

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

=== recall ===

Triggers after the primary unit is recalled (by the secondary unit).

=== prerecall ===

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

=== advance ===

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

=== pre advance ===

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

Care needs to be taken when tags that may trigger advancement themselves are used in this event. For example '''[transform_unit]''', '''[unstore_unit]''', '''[modify_unit]''' etc.

=== post advance ===

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

=== select ===

Triggers when the primary unit is selected. Prior to version 1.11, this also triggered when a move was interrupted, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

=== menu item ''X'' ===

Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== unit placed {{DevFeature1.13|3}}===

Triggers when the primary unit is placed on the map, regardless of method. This includes but might not be limited to:
* Leaders and units placed in side definitions (fired once for every unit right before prestart events)
* Recruited and recalled units
* Units placed on the map with the [unit] tag ('''not''' units created directly onto a recall list or variable)
* Units placed by the wesnoth.put_unit() Lua function
* Units placed by :to_map in Lua (which is a shortcut for the above)
* Units created via debug mode
* Units created by plague
* Every use of [unstore_unit], when ''fire_event'' is set to ''yes'' (default is ''no'')
* Units moved on map with [move_unit] before {{DevFeature1.15|8}}
* Units matching the filter of [petrify], [unpetrify] or [harm_unit] before {{DevFeature1.15|8}}
* Units who receive a bonus from the feeding ability every time except the first, before {{DevFeature1.15|8}}
This event is solely intended for special cases where no other event types suffice, for example if you must immediately apply a modification to every unit that ever appears. The event does '''not''' keep track of which units it has previously fired for, but can fire an unlimited number of times for the same unit as long the unit is "placed" several times and the event filter doesn't prevent it.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

<syntaxhighlight lang='wml'>
[event]
name=last breath
[message]
speaker=second_unit
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker=unit
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]
</syntaxhighlight>

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]
</syntaxhighlight>

An equivalent way of doing this would be to create a single moveto event with a '''[filter_condition]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[filter_condition]''' statements. Using '''[if]''' tags is also an option especially if your event has '''first_time_only=yes'''.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]
</syntaxhighlight>

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.

<syntaxhighlight lang='wml'>
[event] # parent
name=turn 2
# delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event] # child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event] # great-grandchild
name=turn 5
{DEBUG_MSG $turn_number} # output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]
</syntaxhighlight>

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EventWML

2024-06-28T22:20:35Z

Laela: unit hits, unit misses

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the term "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
<syntaxhighlight lang='wml'>
name=<value>
</syntaxhighlight>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

<syntaxhighlight lang='wml'>
name=attacker misses,defender misses
</syntaxhighlight>

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

All predefined event types are listed below, along with a description of when this value will cause the event to be triggered, in the [[#Predefined_Events_Without_Filters|Predefined Events Without Filters]] and [[#Predefined_Events_With_Filters|Predefined Events With Filters]] sections. Any value ''not'' listed there is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

Spaces in event names can be interchanged with ''underscores'' (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

==== Variables in the name ====

If the name contains variables, they will be substituted each time the event is triggered. For example, '''name=turn $disaster_turn''' will only trigger if the turn number is currently equal to whatever number is stored in the variable '''$disaster_turn'''; updating the variable will adjust the turn that the event triggers on. However, if the variable contents contains a comma, it won't be parsed after substitution. Since an event name can't contain a comma, this means the event will never trigger.

{{DevFeature1.17|6}}

Commas resulting from variable substitution are now parsed. If you write '''name=$important_event''' and the variable '''$important_event''' contains the text "capture,die", the event will trigger on either a death or a village capture.

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives. Also, custom events come very handy in [[Wml_optimisation]].

Example:
<syntaxhighlight lang='wml'>
# The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

# This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# And now a fire_event tag is used to trigger the previously defined event. To use
# "speaker=unit" in the fired event, it's also necessary to specify the [primary_unit].
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]
</syntaxhighlight>

You can have more code after the '''[fire_event]''', which will run after the fired event has happened.
Example:
<syntaxhighlight lang='wml'>
# This is a standard recall event that triggers whenever a unit is recalled by side 1
[event]
name=recall
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# Fire the custom event, exactly as the in recruit event
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# After that event has happened, the remaining code in this event is run
[message]
speaker=second_unit
message=_ "Glad to have you back"
[/message]
# As a result, every time side 1 recalls a unit, the recalled unit says
# "Reporting for duty!", and the leader replies "Glad to have you back"
[/event]
</syntaxhighlight>

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is mandatory in case of a [unit_type][event].

==== remove ====
: Removes an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if yes, does the same as a [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] with the same id= value, and the other attributes of this event tag are ignored.

{{DevFeature1.13|0}} May be a comma separated list.

{{DevFeature1.15|7}} Prints a deprecation warning recommending to use [remove_event] instead.

==== priority ====
: {{DevFeature1.17|20}} If several '[event]' tags have the same name, then any with a high priority value will be triggered before events with a lower priority value. Negative numbers are also supported, to run after events without a priority (as the attribute defaults to zero). For events with equal priority, the order is determined by the order in which the events were added.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special_id''': filter on the attack's weapon special id.
:* '''special_type''': filter on the attack's weapon special type.
:* {{DevFeature1.17|15}} '''special_id_active''': filter on the attack's weapon special id active(encoded in [specials] or [abilities] tags).
:* {{DevFeature1.17|15}} '''special_type_active''': filter on the attack's weapon special type active(encoded in [specials] or [abilities] tags).

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== [insert_tag] ====
: An '''[insert_tag]''' that expands to any of the above filter tags will result in the filter being loaded from the variable each time the game checks if the event should fire. This can result in the event's filter varying from turn to turn.

==== filter_formula ====
:{{DevFeature1.17|6}}
: Similar to [filter_condition], but the condition is expressed in [[Wesnoth Formula Language]]. The formula has access to the following keys:
:*Event information:
:**'''event''' - the event name
:**'''event_id''' - the event's unique ID
:**'''event_data''' - additional information specific to the event, such as owner_side or damage_inflicted, or anything passed in '''[fire_event][data]'''.
:**'''loc''', '''unit''' - primary event location and unit
:**'''second_loc''', '''second_unit''' - secondary event location and unit
:**'''weapon''', '''second_weapon''' - primary and secondary weapon
:*Gamestate information:
:**'''turn_number'''
:**'''time_of_day''' - the time of day ID
:**'''side_number''' - currently active side
:**'''sides''' - a list of all sides
:**'''units''' - a list of all units on the map
:**'''map''' - the entire game map as a two-dimensional array

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution_2|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]]. Actions can also be dynamically inserted via '''[insert_tag]'''.

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
* {{DevFeature1.13|10}} victory
* {{DevFeature1.13|10}} defeat
* {{DevFeature1.13|0}} scenario_end
The following are not synced:
* select
* preload
* victory {{DevFeature1.13|10}} local_victory
* defeat {{DevFeature1.13|10}} local_defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}
</syntaxhighlight>

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef
</syntaxhighlight>

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

<syntaxhighlight lang='wml'>
[event]
id=doubler_event
remove=yes
[/event]
</syntaxhighlight>

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== Predefined Events Without Filters ==

These events do not take filter parameters (except [filter_condition] which works for all events).

=== preload ===

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' If a game is started, saved, and then reloaded, the preload event will fire two times while playing. However, it will only fire once when viewing the replay. If the preload event alters the gamestate the second time it fired while playing (when loading the saved game) then it can result in Out Of Sync errors.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

=== prestart ===

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== start ===

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== new turn ===

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

=== turn end ===

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

=== turn ''X'' end ===

Triggers at the end of turn ''X''.

=== side turn ===

Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

=== ai turn ===

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event can break replays if it is used improperly. The ai turn event does not fire during replays. The intention is only to guide the AI to make choices (movements, attacks) which are then saved to the replay.''

=== turn refresh ===

Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status. WML variable '''side_number''' holds the number of this side.

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

=== turn ''X'' ===

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

=== side ''X'' turn ''Y'' ===

This event triggers at the start of turn ''Y'' of side X

=== side ''X'' turn ===

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn ''X'' ===

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side X turn Y refresh ===

This event triggers at the turn refresh for side X on turn Y

=== side ''X'' turn refresh ===

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== turn ''X'' refresh ===

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn end ===

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

=== time over ===

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

=== enemies defeated ===

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

=== local_victory ===

In Wesnoth 1.12 and earlier, the event described here is '''victory''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_victory'''.

This event will be fired at the end of a scenario, if the player's side won. If it fires as a result of an '''[endlevel]''' tag, the event is processed before the line after the '''[endlevel]]''' tag. The event is not synchronized, as in networked mp it is possible to have different results for different players.

=== local_defeat ===

In Wesnoth 1.12 are earlier, the event described here is '''defeat''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_defeat'''.

Functions identically to '''local_victory''', except that the player's side lost.

=== victory ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''victory''' event is equivalent to 1.14's '''local_victory'''.

This event will be fired at the end of a scenario, if the game will proceed to the next scenario. In multiplayer, this means that it will fire on all players' clients, even for players who received a '''local_defeat''', as long as the game continues to the next scenario. This event is synchronized.

It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":next_level" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign.

=== defeat ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''defeat''' event is equivalent to 1.14's '''local_defeat'''.

This event will be fired at the end of a scenario, if the game resulted in a game-over other than victoriously reaching the end of a campaign (including single-scenario campaigns). Synchronization (including bug #4667) is the same as '''victory'''.

=== scenario_end ===

{{DevFeature1.13|10}} This event fires immediately after '''victory''' or '''defeat'''; it is synchronized, but is also affected by bug #4667.

Note: in 1.13.0 - 1.13.9 this event was added as a synchronized alternative to the events that are, since 1.13.10, called local_victory or local_defeat.

== Predefined Events With Filters ==

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables '''unit''' and '''second_unit''' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, unit_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

=== moveto ===

Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' $x2 and $y2 refer to the hex the unit came from.

=== sighted ===

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away. You may want to use [filter_second] in order to restrict a sighted event in a single player scenario to only being triggered by the player and not by other non-allied sides.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

=== enter_hex ===

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). In Wesnoth 1.12, the movement will be interrupted, stopping the unit where it is; this behavior can be avoided by using the {{tag|DirectActionsWML|allow_undo}} tag or `NO_INTERRUPT_NO_UNDO` macro. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

'''Note:''' At the time of writing (7ca5a0df, just before 1.13.11), if the hex is occupied then $unit contains the occupying unit, not the moving unit.

'''Note:''' At the time of writing (1.16.2), if the hex is occupied then $unit does contain the moving unit.

=== exit_hex ===

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

=== pre attack {{DevFeature1.17|7}}===

Similar to '''attack''', but is triggered before calculating the number of attacks and the movement of the unit. Can be used for modifications, which affect these values.

=== attack ===

Triggers when the primary unit attacks the secondary unit. Variables $weapon and $second_weapon contain weapons used for this attack by primary and secondary units respectively for all attack-related events (attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath).

=== attack end ===

Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

=== attacker hits ===

Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

=== attacker misses ===

Same as ''attacker hits'', but is triggered when the attacker misses.

=== defender hits ===

Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

=== defender misses ===

Same as ''defender hits'', but is triggered when the defender misses.

=== unit hits {{DevFeature1.19|2}} ===

Triggers when the the primary unit (either attacker or defender) hits the secondary unit (the other). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the primary unit.

Compared to ''defender hits'', primary and secondary units are swapped.

=== unit misses {{DevFeature1.19|2}} ===

Same as ''unit hits'', but is triggered when the unit misses.

=== petrified ===
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''petrifies'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

=== last breath ===

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

=== die ===

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

=== capture ===

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

=== recruit ===

Triggers when the primary unit is recruited (by the secondary unit). (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

=== prerecruit ===

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

=== recall ===

Triggers after the primary unit is recalled (by the secondary unit).

=== prerecall ===

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

=== advance ===

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

=== pre advance ===

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

Care needs to be taken when tags that may trigger advancement themselves are used in this event. For example '''[transform_unit]''', '''[unstore_unit]''', '''[modify_unit]''' etc.

=== post advance ===

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

=== select ===

Triggers when the primary unit is selected. Prior to version 1.11, this also triggered when a move was interrupted, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

=== menu item ''X'' ===

Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== unit placed {{DevFeature1.13|3}}===

Triggers when the primary unit is placed on the map, regardless of method. This includes but might not be limited to:
* Leaders and units placed in side definitions (fired once for every unit right before prestart events)
* Recruited and recalled units
* Units placed on the map with the [unit] tag ('''not''' units created directly onto a recall list or variable)
* Units placed by the wesnoth.put_unit() Lua function
* Units placed by :to_map in Lua (which is a shortcut for the above)
* Units created via debug mode
* Units created by plague
* Every use of [unstore_unit], when ''fire_event'' is set to ''yes'' (default is ''no'')
* Units moved on map with [move_unit] before {{DevFeature1.15|8}}
* Units matching the filter of [petrify], [unpetrify] or [harm_unit] before {{DevFeature1.15|8}}
* Units who receive a bonus from the feeding ability every time except the first, before {{DevFeature1.15|8}}
This event is solely intended for special cases where no other event types suffice, for example if you must immediately apply a modification to every unit that ever appears. The event does '''not''' keep track of which units it has previously fired for, but can fire an unlimited number of times for the same unit as long the unit is "placed" several times and the event filter doesn't prevent it.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

<syntaxhighlight lang='wml'>
[event]
name=last breath
[message]
speaker=second_unit
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker=unit
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]
</syntaxhighlight>

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]
</syntaxhighlight>

An equivalent way of doing this would be to create a single moveto event with a '''[filter_condition]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[filter_condition]''' statements. Using '''[if]''' tags is also an option especially if your event has '''first_time_only=yes'''.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]
</syntaxhighlight>

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.

<syntaxhighlight lang='wml'>
[event] # parent
name=turn 2
# delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event] # child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event] # great-grandchild
name=turn 5
{DEBUG_MSG $turn_number} # output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]
</syntaxhighlight>

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Template:Lua Functions/Updating

2024-04-26T20:45:49Z

Laela:

Reference how this page was made.

For each relevant LuaAPI page run javascript
<syntaxhighlight lang='js'>
[...document.querySelectorAll('.toclevel-2 .toctext')].map(e => e.innerText).filter(s => s.startsWith('wesnoth') || s.startsWith('wml') || s.startsWith('gui') || s.startsWith('location_set') || s.startsWith('functional') || s.startsWith('stringx') || s.startsWith('mathx') || s.startsWith('filesystem') || s.startsWith('ai') || s.startsWith('utils') || s.startsWith('unit_test')) + " @ " + document.location
</syntaxhighlight>
Put output to separate lines of data.txt and run python
<syntaxhighlight lang='py'>
with open("data.txt") as f:
print("""{| class="reference-sidebar"
|
[[{{SERVER}}{{localurl:Template:Lua Functions|action=edit}} edit]]'''Lua Functions'''""")
sections = {}
for line in f:
line = line.strip().strip("'")
line = line.replace(",wesnoth.audio,wesnoth.achievements,wesnoth.game_events,wesnoth.map,wesnoth.interface,wesnoth.paths,wesnoth.schedule,wesnoth.sides,wesnoth.sync,wesnoth.units","")
methods, url = line.split(" @ ")
url = url.removeprefix("https://wiki.wesnoth.org/")
header = url.removeprefix("LuaAPI/").replace("/",".")

sections[header] = []
for method in sorted(methods.split(",")):
methodWithoutLocation = method.split(".")[-1]
row = "[[{}#{}|{}]] ".format(url, method, method)
sections[header].append(row)

for header in sorted(sections, key=lambda x: '_'+x if x.startswith('wesnoth') else x):
print("|-\n|''{}''".format(header))
for row in sections[header]:
print(row)
print("""|}<includeonly>[[Category:Lua Reference]]</includeonly><noinclude>A box with all the Lua functions, each one linking to the page and section they are described in. It was generated using [[/Updating|this method]]. This box should be included in [[LuaAPI|Lua reference]] page.</noinclude>""")
</syntaxhighlight>

Template:Lua Functions

2024-04-26T20:45:16Z

Laela:

{| class="reference-sidebar"
|
[[{{SERVER}}{{localurl:Template:Lua Functions|action=edit}} edit]]'''Lua Functions'''
|-
|''wesnoth''
[[LuaAPI/wesnoth#wesnoth.as_text|wesnoth.as_text]] 
[[LuaAPI/wesnoth#wesnoth.colors|wesnoth.colors]] 
[[LuaAPI/wesnoth#wesnoth.compile_formula|wesnoth.compile_formula]] 
[[LuaAPI/wesnoth#wesnoth.current|wesnoth.current]] 
[[LuaAPI/wesnoth#wesnoth.current_version|wesnoth.current_version]] 
[[LuaAPI/wesnoth#wesnoth.custom_synced_commands|wesnoth.custom_synced_commands]] 
[[LuaAPI/wesnoth#wesnoth.deprecate_api|wesnoth.deprecate_api]] 
[[LuaAPI/wesnoth#wesnoth.deprecated_message|wesnoth.deprecated_message]] 
[[LuaAPI/wesnoth#wesnoth.dofile|wesnoth.dofile]] 
[[LuaAPI/wesnoth#wesnoth.effects|wesnoth.effects]] 
[[LuaAPI/wesnoth#wesnoth.eval_formula|wesnoth.eval_formula]] 
[[LuaAPI/wesnoth#wesnoth.game_config|wesnoth.game_config]] 
[[LuaAPI/wesnoth#wesnoth.get_language|wesnoth.get_language]] 
[[LuaAPI/wesnoth#wesnoth.log|wesnoth.log]] 
[[LuaAPI/wesnoth#wesnoth.micro_ais|wesnoth.micro_ais]] 
[[LuaAPI/wesnoth#wesnoth.ms_since_init|wesnoth.ms_since_init]] 
[[LuaAPI/wesnoth#wesnoth.name_generator|wesnoth.name_generator]] 
[[LuaAPI/wesnoth#wesnoth.named_tuple|wesnoth.named_tuple]] 
[[LuaAPI/wesnoth#wesnoth.persistent_tags|wesnoth.persistent_tags]] 
[[LuaAPI/wesnoth#wesnoth.print_attributes|wesnoth.print_attributes]] 
[[LuaAPI/wesnoth#wesnoth.races|wesnoth.races]] 
[[LuaAPI/wesnoth#wesnoth.require|wesnoth.require]] 
[[LuaAPI/wesnoth#wesnoth.scenario|wesnoth.scenario]] 
[[LuaAPI/wesnoth#wesnoth.simulate_combat|wesnoth.simulate_combat]] 
[[LuaAPI/wesnoth#wesnoth.terrain_types|wesnoth.terrain_types]] 
[[LuaAPI/wesnoth#wesnoth.textdomain|wesnoth.textdomain]] 
[[LuaAPI/wesnoth#wesnoth.type|wesnoth.type]] 
[[LuaAPI/wesnoth#wesnoth.unit_types|wesnoth.unit_types]] 
[[LuaAPI/wesnoth#wesnoth.version|wesnoth.version]] 
[[LuaAPI/wesnoth#wesnoth.wml_actions|wesnoth.wml_actions]] 
[[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]] 
|-
|''wesnoth.achievements''
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.get|wesnoth.achievements.get]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has|wesnoth.achievements.has]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has_sub_achievement|wesnoth.achievements.has_sub_achievement]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.progress|wesnoth.achievements.progress]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set|wesnoth.achievements.set]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set_sub_achievement|wesnoth.achievements.set_sub_achievement]] 
|-
|''wesnoth.audio''
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list|wesnoth.audio.music_list]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.add|wesnoth.audio.music_list.add]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.all|wesnoth.audio.music_list.all]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.clear|wesnoth.audio.music_list.clear]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.current|wesnoth.audio.music_list.current]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.next|wesnoth.audio.music_list.next]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.play|wesnoth.audio.music_list.play]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.previous|wesnoth.audio.music_list.previous]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.remove|wesnoth.audio.music_list.remove]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.volume|wesnoth.audio.music_list.volume]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.play|wesnoth.audio.play]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.sources|wesnoth.audio.sources]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.volume|wesnoth.audio.volume]] 
|-
|''wesnoth.game_events''
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add|wesnoth.game_events.add]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_menu|wesnoth.game_events.add_menu]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_repeating|wesnoth.game_events.add_repeating]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_wml|wesnoth.game_events.add_wml]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire_by_id|wesnoth.game_events.fire_by_id]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_event|wesnoth.game_events.on_event]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_load|wesnoth.game_events.on_load]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_action|wesnoth.game_events.on_mouse_action]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_button|wesnoth.game_events.on_mouse_button]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_move|wesnoth.game_events.on_mouse_move]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_save|wesnoth.game_events.on_save]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.remove|wesnoth.game_events.remove]] 
|-
|''wesnoth.interface''
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_chat_message|wesnoth.interface.add_chat_message]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_hex_overlay|wesnoth.interface.add_hex_overlay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_halo|wesnoth.interface.add_item_halo]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_image|wesnoth.interface.add_item_image]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_overlay_text|wesnoth.interface.add_overlay_text]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.allow_end_turn|wesnoth.interface.allow_end_turn]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.clear_chat_messages|wesnoth.interface.clear_chat_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.color_adjust|wesnoth.interface.color_adjust]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.delay|wesnoth.interface.delay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.deselect_hex|wesnoth.interface.deselect_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.end_turn|wesnoth.interface.end_turn]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.float_label|wesnoth.interface.float_label]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_displayed_unit|wesnoth.interface.get_displayed_unit]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_hovered_hex|wesnoth.interface.get_hovered_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_items|wesnoth.interface.get_items]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_selected_hex|wesnoth.interface.get_selected_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_viewing_side|wesnoth.interface.get_viewing_side]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.handle_user_interact|wesnoth.interface.handle_user_interact]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.highlight_hex|wesnoth.interface.highlight_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_locked|wesnoth.interface.is_locked]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_skipping_messages|wesnoth.interface.is_skipping_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.lock|wesnoth.interface.lock]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_hex_overlay|wesnoth.interface.remove_hex_overlay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_item|wesnoth.interface.remove_item]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll|wesnoth.interface.scroll]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll_to_hex|wesnoth.interface.scroll_to_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.select_unit|wesnoth.interface.select_unit]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.skip_messages|wesnoth.interface.skip_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.zoom|wesnoth.interface.zoom]] 
|-
|''wesnoth.map''
[[LuaAPI/wesnoth/map#wesnoth.map.add_label|wesnoth.map.add_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.are_hexes_adjacent|wesnoth.map.are_hexes_adjacent]] 
[[LuaAPI/wesnoth/map#wesnoth.map.create|wesnoth.map.create]] 
[[LuaAPI/wesnoth/map#wesnoth.map.distance_between|wesnoth.map.distance_between]] 
[[LuaAPI/wesnoth/map#wesnoth.map.find|wesnoth.map.find]] 
[[LuaAPI/wesnoth/map#wesnoth.map.generate|wesnoth.map.generate]] 
[[LuaAPI/wesnoth/map#wesnoth.map.generate_height_map|wesnoth.map.generate_height_map]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get|wesnoth.map.get]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_adjacent_hexes|wesnoth.map.get_adjacent_hexes]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_area|wesnoth.map.get_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_direction|wesnoth.map.get_direction]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_hexes_in_radius|wesnoth.map.get_hexes_in_radius]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_label|wesnoth.map.get_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_owner|wesnoth.map.get_owner]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_relative_dir|wesnoth.map.get_relative_dir]] 
[[LuaAPI/wesnoth/map#wesnoth.map.iter|wesnoth.map.iter]] 
[[LuaAPI/wesnoth/map#wesnoth.map.make_bitmap|wesnoth.map.make_bitmap]] 
[[LuaAPI/wesnoth/map#wesnoth.map.matches|wesnoth.map.matches]] 
[[LuaAPI/wesnoth/map#wesnoth.map.on_board|wesnoth.map.on_board]] 
[[LuaAPI/wesnoth/map#wesnoth.map.on_border|wesnoth.map.on_border]] 
[[LuaAPI/wesnoth/map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]] 
[[LuaAPI/wesnoth/map#wesnoth.map.place_area|wesnoth.map.place_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.read_location|wesnoth.map.read_location]] 
[[LuaAPI/wesnoth/map#wesnoth.map.remove_area|wesnoth.map.remove_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.remove_label|wesnoth.map.remove_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.rotate_right_around_center|wesnoth.map.rotate_right_around_center]] 
[[LuaAPI/wesnoth/map#wesnoth.map.set_owner|wesnoth.map.set_owner]] 
[[LuaAPI/wesnoth/map#wesnoth.map.split_terrain_code|wesnoth.map.split_terrain_code]] 
[[LuaAPI/wesnoth/map#wesnoth.map.terrain_mask|wesnoth.map.terrain_mask]] 
|-
|''wesnoth.paths''
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_cost_map|wesnoth.paths.find_cost_map]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_path|wesnoth.paths.find_path]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_reach|wesnoth.paths.find_reach]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vacant_hex|wesnoth.paths.find_vacant_hex]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vision_range|wesnoth.paths.find_vision_range]] 
|-
|''wesnoth.schedule''
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_illumination|wesnoth.schedule.get_illumination]] 
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_time_of_day|wesnoth.schedule.get_time_of_day]] 
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.replace|wesnoth.schedule.replace]] 
|-
|''wesnoth.sides''
[[LuaAPI/wesnoth/sides#wesnoth.sides.add_ai_component|wesnoth.sides.add_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.append_ai|wesnoth.sides.append_ai]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.change_ai_component|wesnoth.sides.change_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.create|wesnoth.sides.create]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.debug_ai|wesnoth.sides.debug_ai]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.delete_ai_component|wesnoth.sides.delete_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.find|wesnoth.sides.find]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.get|wesnoth.sides.get]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_enemy|wesnoth.sides.is_enemy]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_fogged|wesnoth.sides.is_fogged]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_shrouded|wesnoth.sides.is_shrouded]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.iter|wesnoth.sides.iter]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.matches|wesnoth.sides.matches]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.override_shroud|wesnoth.sides.override_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_fog|wesnoth.sides.place_fog]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_shroud|wesnoth.sides.place_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_fog|wesnoth.sides.remove_fog]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_shroud|wesnoth.sides.remove_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.set_id|wesnoth.sides.set_id]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.switch_ai|wesnoth.sides.switch_ai]] 
|-
|''wesnoth.sync''
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_multiple|wesnoth.sync.evaluate_multiple]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_single|wesnoth.sync.evaluate_single]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.run_unsynced|wesnoth.sync.run_unsynced]] 
|-
|''wesnoth.units''
[[LuaAPI/wesnoth/units#wesnoth.unit.resistance_against|wesnoth.unit.resistance_against]] 
[[LuaAPI/wesnoth/units#wesnoth.units.ability|wesnoth.units.ability]] 
[[LuaAPI/wesnoth/units#wesnoth.units.add_modification|wesnoth.units.add_modification]] 
[[LuaAPI/wesnoth/units#wesnoth.units.advance|wesnoth.units.advance]] 
[[LuaAPI/wesnoth/units#wesnoth.units.chance_to_be_hit|wesnoth.units.chance_to_be_hit]] 
[[LuaAPI/wesnoth/units#wesnoth.units.clone|wesnoth.units.clone]] 
[[LuaAPI/wesnoth/units#wesnoth.units.create|wesnoth.units.create]] 
[[LuaAPI/wesnoth/units#wesnoth.units.create_animator|wesnoth.units.create_animator]] 
[[LuaAPI/wesnoth/units#wesnoth.units.defense_on|wesnoth.units.defense_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.erase|wesnoth.units.erase]] 
[[LuaAPI/wesnoth/units#wesnoth.units.extract|wesnoth.units.extract]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find|wesnoth.units.find]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_attack|wesnoth.units.find_attack]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_map|wesnoth.units.find_on_map]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] 
[[LuaAPI/wesnoth/units#wesnoth.units.get|wesnoth.units.get]] 
[[LuaAPI/wesnoth/units#wesnoth.units.get_hovered|wesnoth.units.get_hovered]] 
[[LuaAPI/wesnoth/units#wesnoth.units.jamming_on|wesnoth.units.jamming_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.matches|wesnoth.units.matches]] 
[[LuaAPI/wesnoth/units#wesnoth.units.movement_on|wesnoth.units.movement_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.remove_modifications|wesnoth.units.remove_modifications]] 
[[LuaAPI/wesnoth/units#wesnoth.units.scroll_to|wesnoth.units.scroll_to]] 
[[LuaAPI/wesnoth/units#wesnoth.units.select|wesnoth.units.select]] 
[[LuaAPI/wesnoth/units#wesnoth.units.to_map|wesnoth.units.to_map]] 
[[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] 
[[LuaAPI/wesnoth/units#wesnoth.units.transform|wesnoth.units.transform]] 
[[LuaAPI/wesnoth/units#wesnoth.units.vision_on|wesnoth.units.vision_on]] 
|-
|''ai''
[[LuaAPI/ai#ai.aspects|ai.aspects]] 
[[LuaAPI/ai#ai.attack|ai.attack]] 
[[LuaAPI/ai#ai.check_attack|ai.check_attack]] 
[[LuaAPI/ai#ai.check_move|ai.check_move]] 
[[LuaAPI/ai#ai.check_recall|ai.check_recall]] 
[[LuaAPI/ai#ai.check_recruit|ai.check_recruit]] 
[[LuaAPI/ai#ai.check_stopunit|ai.check_stopunit]] 
[[LuaAPI/ai#ai.fallback_human|ai.fallback_human]] 
[[LuaAPI/ai#ai.get_attacks|ai.get_attacks]] 
[[LuaAPI/ai#ai.get_targets|ai.get_targets]] 
[[LuaAPI/ai#ai.move|ai.move]] 
[[LuaAPI/ai#ai.move_full|ai.move_full]] 
[[LuaAPI/ai#ai.read_only|ai.read_only]] 
[[LuaAPI/ai#ai.recall|ai.recall]] 
[[LuaAPI/ai#ai.recruit|ai.recruit]] 
[[LuaAPI/ai#ai.side|ai.side]] 
[[LuaAPI/ai#ai.stopunit_all|ai.stopunit_all]] 
[[LuaAPI/ai#ai.stopunit_attacks|ai.stopunit_attacks]] 
[[LuaAPI/ai#ai.stopunit_moves|ai.stopunit_moves]] 
[[LuaAPI/ai#ai.suitable_keep|ai.suitable_keep]] 
|-
|''filesystem''
[[LuaAPI/filesystem#filesystem.canonical_path|filesystem.canonical_path]] 
[[LuaAPI/filesystem#filesystem.have_asset|filesystem.have_asset]] 
[[LuaAPI/filesystem#filesystem.have_file|filesystem.have_file]] 
[[LuaAPI/filesystem#filesystem.image_size|filesystem.image_size]] 
[[LuaAPI/filesystem#filesystem.read_file|filesystem.read_file]] 
[[LuaAPI/filesystem#filesystem.resolve_asset|filesystem.resolve_asset]] 
|-
|''functional''
[[LuaAPI/functional#functional.choose|functional.choose]] 
[[LuaAPI/functional#functional.choose_map|functional.choose_map]] 
[[LuaAPI/functional#functional.filter|functional.filter]] 
[[LuaAPI/functional#functional.filter_map|functional.filter_map]] 
[[LuaAPI/functional#functional.find|functional.find]] 
[[LuaAPI/functional#functional.find_map|functional.find_map]] 
[[LuaAPI/functional#functional.map|functional.map]] 
[[LuaAPI/functional#functional.map_array|functional.map_array]] 
[[LuaAPI/functional#functional.reduce|functional.reduce]] 
[[LuaAPI/functional#functional.take_while|functional.take_while]] 
[[LuaAPI/functional#functional.zip|functional.zip]] 
|-
|''gui''
[[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition]] 
[[LuaAPI/gui#gui.get_user_choice|gui.get_user_choice]] 
[[LuaAPI/gui#gui.show_dialog|gui.show_dialog]] 
[[LuaAPI/gui#gui.show_help|gui.show_help]] 
[[LuaAPI/gui#gui.show_inspector|gui.show_inspector]] 
[[LuaAPI/gui#gui.show_lua_console|gui.show_lua_console]] 
[[LuaAPI/gui#gui.show_menu|gui.show_menu]] 
[[LuaAPI/gui#gui.show_narration|gui.show_narration]] 
[[LuaAPI/gui#gui.show_popup|gui.show_popup]] 
[[LuaAPI/gui#gui.show_prompt|gui.show_prompt]] 
[[LuaAPI/gui#gui.show_story|gui.show_story]] 
[[LuaAPI/gui#gui.widget|gui.widget]] 
|-
|''location_set''
[[LuaAPI/location_set#location_set.clear|location_set.clear]] 
[[LuaAPI/location_set#location_set.clone|location_set.clone]] 
[[LuaAPI/location_set#location_set.create|location_set.create]] 
[[LuaAPI/location_set#location_set.diff|location_set.diff]] 
[[LuaAPI/location_set#location_set.empty|location_set.empty]] 
[[LuaAPI/location_set#location_set.filter|location_set.filter]] 
[[LuaAPI/location_set#location_set.get|location_set.get]] 
[[LuaAPI/location_set#location_set.insert|location_set.insert]] 
[[LuaAPI/location_set#location_set.inter|location_set.inter]] 
[[LuaAPI/location_set#location_set.inter_merge|location_set.inter_merge]] 
[[LuaAPI/location_set#location_set.invert|location_set.invert]] 
[[LuaAPI/location_set#location_set.iter|location_set.iter]] 
[[LuaAPI/location_set#location_set.of_map|location_set.of_map]] 
[[LuaAPI/location_set#location_set.of_pairs|location_set.of_pairs]] 
[[LuaAPI/location_set#location_set.of_raw|location_set.of_raw]] 
[[LuaAPI/location_set#location_set.of_shroud_data|location_set.of_shroud_data]] 
[[LuaAPI/location_set#location_set.of_triples|location_set.of_triples]] 
[[LuaAPI/location_set#location_set.of_wml_var|location_set.of_wml_var]] 
[[LuaAPI/location_set#location_set.random|location_set.random]] 
[[LuaAPI/location_set#location_set.remove|location_set.remove]] 
[[LuaAPI/location_set#location_set.size|location_set.size]] 
[[LuaAPI/location_set#location_set.stable_iter|location_set.stable_iter]] 
[[LuaAPI/location_set#location_set.symm|location_set.symm]] 
[[LuaAPI/location_set#location_set.to_map|location_set.to_map]] 
[[LuaAPI/location_set#location_set.to_pairs|location_set.to_pairs]] 
[[LuaAPI/location_set#location_set.to_shroud_data|location_set.to_shroud_data]] 
[[LuaAPI/location_set#location_set.to_stable_pairs|location_set.to_stable_pairs]] 
[[LuaAPI/location_set#location_set.to_triples|location_set.to_triples]] 
[[LuaAPI/location_set#location_set.to_wml_var|location_set.to_wml_var]] 
[[LuaAPI/location_set#location_set.union|location_set.union]] 
[[LuaAPI/location_set#location_set.union_merge|location_set.union_merge]] 
|-
|''mathx''
[[LuaAPI/mathx#mathx.clamp|mathx.clamp]] 
[[LuaAPI/mathx#mathx.lerp|mathx.lerp]] 
[[LuaAPI/mathx#mathx.random|mathx.random]] 
[[LuaAPI/mathx#mathx.random_choice|mathx.random_choice]] 
[[LuaAPI/mathx#mathx.round|mathx.round]] 
[[LuaAPI/mathx#mathx.shuffle|mathx.shuffle]] 
|-
|''stringx''
[[LuaAPI/stringx#stringx.anim_split|stringx.anim_split]] 
[[LuaAPI/stringx#stringx.escaped_split|stringx.escaped_split]] 
[[LuaAPI/stringx#stringx.format_conjunct_list|stringx.format_conjunct_list]] 
[[LuaAPI/stringx#stringx.format_disjunct_list|stringx.format_disjunct_list]] 
[[LuaAPI/stringx#stringx.iter_range|stringx.iter_range]] 
[[LuaAPI/stringx#stringx.iter_ranges|stringx.iter_ranges]] 
[[LuaAPI/stringx#stringx.join|stringx.join]] 
[[LuaAPI/stringx#stringx.join_map|stringx.join_map]] 
[[LuaAPI/stringx#stringx.map_split|stringx.map_split]] 
[[LuaAPI/stringx#stringx.parenthetical_split|stringx.parenthetical_split]] 
[[LuaAPI/stringx#stringx.parse_range|stringx.parse_range]] 
[[LuaAPI/stringx#stringx.quoted_split|stringx.quoted_split]] 
[[LuaAPI/stringx#stringx.split|stringx.split]] 
[[LuaAPI/stringx#stringx.trim|stringx.trim]] 
[[LuaAPI/stringx#stringx.vformat|stringx.vformat]] 
|-
|''unit_test''
[[LuaAPI/unit_test#unit_test.assert|unit_test.assert]] 
[[LuaAPI/unit_test#unit_test.assert_approx_equal|unit_test.assert_approx_equal]] 
[[LuaAPI/unit_test#unit_test.assert_contains|unit_test.assert_contains]] 
[[LuaAPI/unit_test#unit_test.assert_equal|unit_test.assert_equal]] 
[[LuaAPI/unit_test#unit_test.assert_greater|unit_test.assert_greater]] 
[[LuaAPI/unit_test#unit_test.assert_greater_equal|unit_test.assert_greater_equal]] 
[[LuaAPI/unit_test#unit_test.assert_in_range|unit_test.assert_in_range]] 
[[LuaAPI/unit_test#unit_test.assert_less|unit_test.assert_less]] 
[[LuaAPI/unit_test#unit_test.assert_less_equal|unit_test.assert_less_equal]] 
[[LuaAPI/unit_test#unit_test.assert_not_equal|unit_test.assert_not_equal]] 
[[LuaAPI/unit_test#unit_test.assert_nothrow|unit_test.assert_nothrow]] 
[[LuaAPI/unit_test#unit_test.assert_throws|unit_test.assert_throws]] 
[[LuaAPI/unit_test#unit_test.assert_throws_with|unit_test.assert_throws_with]] 
[[LuaAPI/unit_test#unit_test.fail|unit_test.fail]] 
[[LuaAPI/unit_test#unit_test.finish|unit_test.finish]] 
[[LuaAPI/unit_test#unit_test.fire_wml_menu_item|unit_test.fire_wml_menu_item]] 
[[LuaAPI/unit_test#unit_test.log|unit_test.log]] 
[[LuaAPI/unit_test#unit_test.succeed|unit_test.succeed]] 
[[LuaAPI/unit_test#unit_test.tostring|unit_test.tostring]] 
|-
|''wml''
[[LuaAPI/wml#wml.all_variables|wml.all_variables]] 
[[LuaAPI/wml#wml.array_access.get|wml.array_access.get]] 
[[LuaAPI/wml#wml.array_access.get_proxy|wml.array_access.get_proxy]] 
[[LuaAPI/wml#wml.array_access.set|wml.array_access.set]] 
[[LuaAPI/wml#wml.array_variables|wml.array_variables]] 
[[LuaAPI/wml#wml.attribute_count|wml.attribute_count]] 
[[LuaAPI/wml#wml.child_array|wml.child_array]] 
[[LuaAPI/wml#wml.child_count|wml.child_count]] 
[[LuaAPI/wml#wml.child_range|wml.child_range]] 
[[LuaAPI/wml#wml.clone|wml.clone]] 
[[LuaAPI/wml#wml.diff|wml.diff]] 
[[LuaAPI/wml#wml.equal|wml.equal]] 
[[LuaAPI/wml#wml.error|wml.error]] 
[[LuaAPI/wml#wml.eval_conditional|wml.eval_conditional]] 
[[LuaAPI/wml#wml.find_child|wml.find_child]] 
[[LuaAPI/wml#wml.fire|wml.fire]] 
[[LuaAPI/wml#wml.get_child|wml.get_child]] 
[[LuaAPI/wml#wml.get_nth_child|wml.get_nth_child]] 
[[LuaAPI/wml#wml.interpolate|wml.interpolate]] 
[[LuaAPI/wml#wml.literal|wml.literal]] 
[[LuaAPI/wml#wml.load|wml.load]] 
[[LuaAPI/wml#wml.matches_filter|wml.matches_filter]] 
[[LuaAPI/wml#wml.merge|wml.merge]] 
[[LuaAPI/wml#wml.parse|wml.parse]] 
[[LuaAPI/wml#wml.parsed|wml.parsed]] 
[[LuaAPI/wml#wml.patch|wml.patch]] 
[[LuaAPI/wml#wml.remove_child|wml.remove_child]] 
[[LuaAPI/wml#wml.remove_children|wml.remove_children]] 
[[LuaAPI/wml#wml.shallow_literal|wml.shallow_literal]] 
[[LuaAPI/wml#wml.shallow_parsed|wml.shallow_parsed]] 
[[LuaAPI/wml#wml.tag|wml.tag]] 
[[LuaAPI/wml#wml.tostring|wml.tostring]] 
[[LuaAPI/wml#wml.tovconfig|wml.tovconfig]] 
[[LuaAPI/wml#wml.valid|wml.valid]] 
[[LuaAPI/wml#wml.variables|wml.variables]] 
[[LuaAPI/wml#wml.variables_proxy|wml.variables_proxy]] 
|-
|''wml-utils''
[[LuaAPI/wml-utils#utils.check_key|utils.check_key]] 
[[LuaAPI/wml-utils#utils.get_sides|utils.get_sides]] 
[[LuaAPI/wml-utils#utils.handle_event_commands|utils.handle_event_commands]] 
[[LuaAPI/wml-utils#utils.optional_side_filter|utils.optional_side_filter]] 
[[LuaAPI/wml-utils#utils.scoped_var|utils.scoped_var]] 
[[LuaAPI/wml-utils#utils.set_exiting|utils.set_exiting]] 
[[LuaAPI/wml-utils#utils.vwriter|utils.vwriter]] 
|}<includeonly>[[Category:Lua Reference]]</includeonly><noinclude>A box with all the Lua functions, each one linking to the page and section they are described in. It was generated using [[/Updating|this method]]. This box should be included in [[LuaAPI|Lua reference]] page.</noinclude>

LuaAPI

2024-04-23T20:41:38Z

Laela: Include Lua_Functions

{{Lua_Functions}}
__NOTOC__
All Lua API functionality is available in one of several global module tables, as well as some global functions which form the basic Lua API. Wesnoth uses [http://www.lua.org/manual/5.4/manual.html Lua 5.4] which is documented in detail on the Lua website.

This page documents the modules, functions, and other APIs available for use when writing Lua for Wesnoth. For information on how to tell the engine about your Lua code, see [[LuaWML]].

== Conventions used in this manual ==

On this page and any page linked from it, variable values will be shown in italic type, while literal names will be shown in bold type. Variable values may be parameters, self values, indexes, or field names on a table. Return values will be indicated by a right arrow (→) followed by a list of names in italics. The arrow will be omitted for a function that returns nothing. Optional portions will be enclosed in square brackets. The commas for optional parameters will not be included in the brackets, even though they must be omitted if the optional parameter is omitted.

===== Functions =====

For example, the following line would be seen in the documentation of a function that returns two values and has an optional parameter:

* '''wesnoth.some_function'''(''some_parameter'', [''some_optional_parameter'']) → ''first_return_value'', ''second_return_value''

===== Methods =====

The following example documents a function that can be called as a method on a ''some_value'', taking one additional parameter and returning one value.

* ''some_value'':'''some_method'''(''some_parameter'') → ''some_new_value''

===== Variadic Functions =====

Functions that take a variable number of parameters or return a variable number of values where the specific meaning of the parameters is unspecified will use the string "..." to indicate this. For example:

* '''wesnoth.variadic_function'''(''required_param'', [...])
* '''wesnoth.get_several_values'''(''param'') → ...

The first of these takes a variable number of parameters, but requires at least one parameter. The second takes one parameter and returns a variable number of values.

===== Member Variables =====

Not all documented APIs are functions. When documenting userdata types, as well as some complex tables returned by API functions, the following syntax is used for member variables. The right arrow may be replaced with a left arrow (←) if it is write-only, or a double-ended arrow (↔) if it is read-write. Read-only members may return multiple values. The following examples document a read-write member, a read-only member that returns two values, and a write-only member respectively.

* ''some_value''.'''some_member''' ↔ ''result''
* ''some_value''.'''read_only_member''' → ''first_result'', ''second_result''
* ''some_value''.'''write_only_member''' ← ''input''

===== Operators =====

Custom types in Lua can overload operators with new functionality. Some examples of how these would be documented:

* #'''wesnoth.list_like_object''' → ''number of somethings''
* '''wesnoth.list_like_object'''[''index''] ↔ ''a something definition table''
* ''comparable_value'' == ''comparable_value'' → ''whether they are equal''
* ''operable_value'' + ''operable_value'' → ''result''

The first example documents that you can get the length of that object. The same format would be used for other unary operators as well.

The second example documents that you can index the object with arbitrary values. Whether the index needs to be a number would usually be mentioned in the detailed description, although the placeholder name may also make it clear. This example could also use a single-directional arrow to indicate that it is read-only or write-only.

The third example documents that you can compare two values of that type with the equality operator, and the fourth example documents that you can add two values of that type together with the addition operator.

===== Iterators =====

For functions that return an iterator, a double arrow indicates the values yielded when you use the iterator in a for loop. The following example documents a function returning an iterator that yields three values.

* '''wesnoth.some_function'''() → ''iterator'' ⇒ ''a'', ''b'', ''c''

===== Hooks =====

Some parts of the API are so-called ''hooks'', meaning that you define a function in a special location and it has some effect on the game. The following example documents a hook which takes one parameter and returns a value. Usually the double-ended arrow is used for hooks, but some may be write-only.

* '''wesnoth.some_table'''.''name'' ↔ '''function'''(''parameter'') → ''expected return value''

===== Context Specifiers =====

Many functions and variables are only available in certain contexts. Currently, there are three possible contexts - plugins, map generators, and the game. Most Lua will run in the game kernel. If a function is only available in certain contexts, that will be indicated with an icon at the beginning of the definition. For example:

* {{LuaGameOnly}} '''wesnoth.game_exclusive_function'''(''parameter'') → ''result''

The possible icons are:

* {{LuaGameOnly}} Available in the game context. Most Lua in Wesnoth runs in the game context, which is initialized when a game begins and destroyed upon victory or loss.
* {{LuaMapOnly}} Available in the map generation context. This context is created at the game creation screen, generally to generate a map for a scenario.
* {{LuaPluginOnly}} Available in the plugins context. There is only one plugins context, which is initialized when Wesnoth launches and remains valid until it shuts down. A plugin is a Lua script loaded via the command-line option <tt>--plugin</tt> that runs as a coroutine in parallel with the game UI. It can automatically connect to a server and host or join a game. This API is documented at [[LuaPluginAPI]].

== Built-in Modules ==

The following built-in Lua modules are available:

* [http://www.lua.org/manual/5.4/manual.html#6.1 basic] — except <tt>dofile</tt>, <tt>require</tt>, and <tt>loadfile</tt>; also note that <tt>print</tt> redirects to the Lua console interface rather than standard output; you can use <tt>std_print</tt> if you need the default Lua behavior.
* [http://www.lua.org/manual/5.4/manual.html#6.2 coroutine]
* [http://www.lua.org/manual/5.4/manual.html#6.4 string]
* [http://www.lua.org/manual/5.4/manual.html#6.5 utf8]
* [http://www.lua.org/manual/5.4/manual.html#6.6 table]
* [http://www.lua.org/manual/5.4/manual.html#6.7 math] — note that <tt>math.random</tt> is unsafe for MP usage; wesnoth provides a separate MP-safe random function
* [http://www.lua.org/manual/5.4/manual.html#6.9 os] — only the <tt>clock</tt>, <tt>date</tt>, <tt>time</tt>, and <tt>difftime</tt> functions are available (but keep in mind that they are not MP safe)
* [http://www.lua.org/manual/5.4/manual.html#6.10 debug] — only the <tt>traceback</tt> function is available

== Wesnoth Modules ==

Wesnoth also provides several modules of its own, some of which are loaded by default while others require you to load them as needed. Note: APIs named '''wesnoth.something''', for example [[LuaAPI/wesnoth#wesnoth.scenario|wesnoth.scenario]], might be part of Core and not a separate module.

* [[LuaAPI/wesnoth|wesnoth]] (Core) - The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.
** [[LuaAPI/wesnoth/interface|wesnoth.interface]] (Game Interface) - {{DevFeature1.15|0}} The <tt>interface</tt> submodule contains functions for querying or manipulating the in-game UI.
** [[LuaAPI/wesnoth/units|wesnoth.units]] (Units) - {{DevFeature1.15|0}} The <tt>units</tt> submodule contains functions for manipulating units on the map or recall list.
** [[LuaAPI/wesnoth/schedule|wesnoth.schedule]] (Schedule) - {{DevFeature1.15|14}} The <tt>schedule</tt> submodule contains functions for manipulating the time of day schedule in the scenario.
** [[LuaAPI/wesnoth/sides|wesnoth.sides]] (Sides) - {{DevFeature1.15|3}} The <tt>sides</tt> submodule contains functions for manipulating sides in the scenario.
** [[LuaAPI/wesnoth/sync|wesnoth.sync]] (Synchronization) - {{DevFeature1.15|3}} The <tt>sync</tt> submodule contains functions for keeping multiplayer games synchronized.
** [[LuaAPI/wesnoth/map|wesnoth.map]] (Game Map) - {{DevFeature1.15|11}} The <tt>map</tt> submodule contains functions for querying and manipulating the game map.
** [[LuaAPI/wesnoth/audio|wesnoth.audio]] (Audio) - {{DevFeature1.15|13}} The <tt>audio</tt> submodule contains functions for playing music and sound effects.
** [[LuaAPI/wesnoth/paths|wesnoth.paths]] (Pathfinding) - {{DevFeature1.15|14}} The <tt>paths</tt> submodule contains functions related to pathfinding.
** [[LuaAPI/wesnoth/game_events|wesnoth.game_events]] (Event Handling) - The <tt>game_events</tt> submodule contains functions and hooks related to event handling.
** [[LuaAPI/wesnoth/achievements|wesnoth.achievements]] (Achievements Support) - {{DevFeature1.17|13}} The <tt>achievements</tt> submodule contains functions for checking and setting achievements.
* [[LuaAPI/gui|gui]] (User Interface) - {{DevFeature1.15|0}} The <tt>gui</tt> module contains routines for showing dialogs on the screen. It does ''not'' contain anything for manipulating the in-game UI, however.
** [[LuaAPI/gui/widget|gui.widget]] (GUI Widget Support) - {{DevFeature1.15|6}} The <tt>widget</tt> submodule contains routines for operating on dialog widgets. Since they take a widget reference an argument, they can only be called while a dialog is onscreen.
* [[LuaAPI/wml|wml]] (WML Tables) - The <tt>wml</tt> module contains functions for working with WML tables.
* [[LuaAPI/location_set|location_set]] (Location Sets) - A module for working with sets of locations, optionally associating data to each location. Not loaded by default.
* [[LuaAPI/functional|functional]] - Higher-order functions module. Not loaded by default.
* [[LuaAPI/stringx|stringx]] - Additional string support functions, to augment the built-in string module.
* [[LuaAPI/mathx|mathx]] - {{DevFeature1.15|13}} Additional math and randomization support functions, to augment the built-in math module.
* [[LuaAPI/filesystem|filesystem]] - {{DevFeature1.15|13}} Functions that allow read-only access to arbitrary files in the data folder.
* [[LuaAPI/ai|ai]] - Functions that instruct the AI on how to move.
* [[LuaAPI/wml-utils|wml-utils]] - Useful functions for implementing custom WML tags.
* [[LuaAPI/unit_test|unit_test]] - Functions that can be used to write unit tests; only available in [test] scenarios.

== Wesnoth Types ==

Wesnoth defines a large number of ''userdata'' types, some of which are quite common and complex. Most of them are documented alongside the function that creates them, but some of the most common or complex ones are listed below.

* [[LuaAPI/wesnoth#wesnoth.textdomain|translatable strings]] - a string that will be translated by the engine.
* [[LuaAPI/wml#wml.tovconfig|vconfig]] - a WML object that automatically substitutes variables on the fly.
* [[LuaAPI/types/unit|unit]] - represents a reference to Wesnoth unit on the map, on the recall list, or private to Lua.
* [[LuaAPI/types#Weapon|weapon]] - represents a unit's weapon.
* [[LuaAPI/types#Race|race]] - represents a unit's race.
* [[LuaAPI/types#Unit_Type|unit type]] - represents a unit's type.
* [[LuaAPI/types/side|side]] - represents a single side (player) in the game.
* [[LuaAPI/types/widget|widget]] - represents a GUI2 widget.
* [[LuaAPI/types/map|map]] - represents the game map.
* [[LuaAPI/types/hex|hex]] - represents a single hex on the map.

== See Also ==
* [[LuaAPI/UpdatingFrom14]]
* [[LuaAPI/old]] - The reference for the 1.14 Lua API, which may be useful if porting older add-ons

[[Category:Lua Reference|*]]

Template:Lua Functions/Updating

2024-04-19T18:06:53Z

Laela:

Reference how this page was made.

For each relevant LuaAPI page run javascript
<syntaxhighlight lang='js'>
[...document.querySelectorAll('.toclevel-2 .toctext')].map(e => e.innerText).filter(s => s.startsWith('wesnoth') || s.startsWith('wml') || s.startsWith('gui') || s.startsWith('location_set') || s.startsWith('functional') || s.startsWith('stringx') || s.startsWith('mathx') || s.startsWith('filesystem') || s.startsWith('ai') || s.startsWith('utils') || s.startsWith('unit_test')) + " @ " + document.location
</syntaxhighlight>
Put output to separate lines of data.txt and run python
<syntaxhighlight lang='py'>
with open("data.txt") as f:
print('{|class="reference-sidebar"')
sections = {}
for line in f:
line = line.strip().strip("'")
line = line.replace(",wesnoth.audio,wesnoth.achievements,wesnoth.game_events,wesnoth.map,wesnoth.interface,wesnoth.paths,wesnoth.schedule,wesnoth.sides,wesnoth.sync,wesnoth.units","")
methods, url = line.split(" @ ")
url = url.removeprefix("https://wiki.wesnoth.org/")
header = url.removeprefix("LuaAPI/").replace("/",".")

sections[header] = []
for method in sorted(methods.split(",")):
methodWithoutLocation = method.split(".")[-1]
row = "[[{}#{}|{}]] ".format(url, method, method)
sections[header].append(row)

for header in sorted(sections, key=lambda x: '_'+x if x.startswith('wesnoth') else x):
print("|-\n|''{}''".format(header))
for row in sections[header]:
print(row)
print('|}')
</syntaxhighlight>

Template:Lua Functions

2024-04-19T17:56:02Z

Laela:

{|class="reference-sidebar"
|-
|''wesnoth''
[[LuaAPI/wesnoth#wesnoth.as_text|wesnoth.as_text]] 
[[LuaAPI/wesnoth#wesnoth.colors|wesnoth.colors]] 
[[LuaAPI/wesnoth#wesnoth.compile_formula|wesnoth.compile_formula]] 
[[LuaAPI/wesnoth#wesnoth.current|wesnoth.current]] 
[[LuaAPI/wesnoth#wesnoth.current_version|wesnoth.current_version]] 
[[LuaAPI/wesnoth#wesnoth.custom_synced_commands|wesnoth.custom_synced_commands]] 
[[LuaAPI/wesnoth#wesnoth.deprecate_api|wesnoth.deprecate_api]] 
[[LuaAPI/wesnoth#wesnoth.deprecated_message|wesnoth.deprecated_message]] 
[[LuaAPI/wesnoth#wesnoth.dofile|wesnoth.dofile]] 
[[LuaAPI/wesnoth#wesnoth.effects|wesnoth.effects]] 
[[LuaAPI/wesnoth#wesnoth.eval_formula|wesnoth.eval_formula]] 
[[LuaAPI/wesnoth#wesnoth.game_config|wesnoth.game_config]] 
[[LuaAPI/wesnoth#wesnoth.get_language|wesnoth.get_language]] 
[[LuaAPI/wesnoth#wesnoth.log|wesnoth.log]] 
[[LuaAPI/wesnoth#wesnoth.micro_ais|wesnoth.micro_ais]] 
[[LuaAPI/wesnoth#wesnoth.ms_since_init|wesnoth.ms_since_init]] 
[[LuaAPI/wesnoth#wesnoth.name_generator|wesnoth.name_generator]] 
[[LuaAPI/wesnoth#wesnoth.named_tuple|wesnoth.named_tuple]] 
[[LuaAPI/wesnoth#wesnoth.persistent_tags|wesnoth.persistent_tags]] 
[[LuaAPI/wesnoth#wesnoth.print_attributes|wesnoth.print_attributes]] 
[[LuaAPI/wesnoth#wesnoth.races|wesnoth.races]] 
[[LuaAPI/wesnoth#wesnoth.require|wesnoth.require]] 
[[LuaAPI/wesnoth#wesnoth.scenario|wesnoth.scenario]] 
[[LuaAPI/wesnoth#wesnoth.simulate_combat|wesnoth.simulate_combat]] 
[[LuaAPI/wesnoth#wesnoth.terrain_types|wesnoth.terrain_types]] 
[[LuaAPI/wesnoth#wesnoth.textdomain|wesnoth.textdomain]] 
[[LuaAPI/wesnoth#wesnoth.type|wesnoth.type]] 
[[LuaAPI/wesnoth#wesnoth.unit_types|wesnoth.unit_types]] 
[[LuaAPI/wesnoth#wesnoth.version|wesnoth.version]] 
[[LuaAPI/wesnoth#wesnoth.wml_actions|wesnoth.wml_actions]] 
[[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]] 
|-
|''wesnoth.achievements''
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.get|wesnoth.achievements.get]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has|wesnoth.achievements.has]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has_sub_achievement|wesnoth.achievements.has_sub_achievement]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.progress|wesnoth.achievements.progress]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set|wesnoth.achievements.set]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set_sub_achievement|wesnoth.achievements.set_sub_achievement]] 
|-
|''wesnoth.audio''
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list|wesnoth.audio.music_list]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.add|wesnoth.audio.music_list.add]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.all|wesnoth.audio.music_list.all]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.clear|wesnoth.audio.music_list.clear]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.current|wesnoth.audio.music_list.current]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.next|wesnoth.audio.music_list.next]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.play|wesnoth.audio.music_list.play]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.previous|wesnoth.audio.music_list.previous]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.remove|wesnoth.audio.music_list.remove]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.volume|wesnoth.audio.music_list.volume]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.play|wesnoth.audio.play]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.sources|wesnoth.audio.sources]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.volume|wesnoth.audio.volume]] 
|-
|''wesnoth.game_events''
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add|wesnoth.game_events.add]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_menu|wesnoth.game_events.add_menu]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_repeating|wesnoth.game_events.add_repeating]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_wml|wesnoth.game_events.add_wml]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire_by_id|wesnoth.game_events.fire_by_id]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_event|wesnoth.game_events.on_event]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_load|wesnoth.game_events.on_load]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_action|wesnoth.game_events.on_mouse_action]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_button|wesnoth.game_events.on_mouse_button]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_move|wesnoth.game_events.on_mouse_move]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_save|wesnoth.game_events.on_save]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.remove|wesnoth.game_events.remove]] 
|-
|''wesnoth.interface''
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_chat_message|wesnoth.interface.add_chat_message]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_hex_overlay|wesnoth.interface.add_hex_overlay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_halo|wesnoth.interface.add_item_halo]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_image|wesnoth.interface.add_item_image]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_overlay_text|wesnoth.interface.add_overlay_text]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.allow_end_turn|wesnoth.interface.allow_end_turn]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.clear_chat_messages|wesnoth.interface.clear_chat_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.color_adjust|wesnoth.interface.color_adjust]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.delay|wesnoth.interface.delay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.deselect_hex|wesnoth.interface.deselect_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.end_turn|wesnoth.interface.end_turn]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.float_label|wesnoth.interface.float_label]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_displayed_unit|wesnoth.interface.get_displayed_unit]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_hovered_hex|wesnoth.interface.get_hovered_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_items|wesnoth.interface.get_items]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_selected_hex|wesnoth.interface.get_selected_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_viewing_side|wesnoth.interface.get_viewing_side]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.handle_user_interact|wesnoth.interface.handle_user_interact]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.highlight_hex|wesnoth.interface.highlight_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_locked|wesnoth.interface.is_locked]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_skipping_messages|wesnoth.interface.is_skipping_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.lock|wesnoth.interface.lock]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_hex_overlay|wesnoth.interface.remove_hex_overlay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_item|wesnoth.interface.remove_item]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll|wesnoth.interface.scroll]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll_to_hex|wesnoth.interface.scroll_to_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.select_unit|wesnoth.interface.select_unit]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.skip_messages|wesnoth.interface.skip_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.zoom|wesnoth.interface.zoom]] 
|-
|''wesnoth.map''
[[LuaAPI/wesnoth/map#wesnoth.map.add_label|wesnoth.map.add_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.are_hexes_adjacent|wesnoth.map.are_hexes_adjacent]] 
[[LuaAPI/wesnoth/map#wesnoth.map.create|wesnoth.map.create]] 
[[LuaAPI/wesnoth/map#wesnoth.map.distance_between|wesnoth.map.distance_between]] 
[[LuaAPI/wesnoth/map#wesnoth.map.find|wesnoth.map.find]] 
[[LuaAPI/wesnoth/map#wesnoth.map.generate|wesnoth.map.generate]] 
[[LuaAPI/wesnoth/map#wesnoth.map.generate_height_map|wesnoth.map.generate_height_map]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get|wesnoth.map.get]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_adjacent_hexes|wesnoth.map.get_adjacent_hexes]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_area|wesnoth.map.get_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_direction|wesnoth.map.get_direction]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_hexes_in_radius|wesnoth.map.get_hexes_in_radius]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_label|wesnoth.map.get_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_owner|wesnoth.map.get_owner]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_relative_dir|wesnoth.map.get_relative_dir]] 
[[LuaAPI/wesnoth/map#wesnoth.map.iter|wesnoth.map.iter]] 
[[LuaAPI/wesnoth/map#wesnoth.map.make_bitmap|wesnoth.map.make_bitmap]] 
[[LuaAPI/wesnoth/map#wesnoth.map.matches|wesnoth.map.matches]] 
[[LuaAPI/wesnoth/map#wesnoth.map.on_board|wesnoth.map.on_board]] 
[[LuaAPI/wesnoth/map#wesnoth.map.on_border|wesnoth.map.on_border]] 
[[LuaAPI/wesnoth/map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]] 
[[LuaAPI/wesnoth/map#wesnoth.map.place_area|wesnoth.map.place_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.read_location|wesnoth.map.read_location]] 
[[LuaAPI/wesnoth/map#wesnoth.map.remove_area|wesnoth.map.remove_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.remove_label|wesnoth.map.remove_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.rotate_right_around_center|wesnoth.map.rotate_right_around_center]] 
[[LuaAPI/wesnoth/map#wesnoth.map.set_owner|wesnoth.map.set_owner]] 
[[LuaAPI/wesnoth/map#wesnoth.map.split_terrain_code|wesnoth.map.split_terrain_code]] 
[[LuaAPI/wesnoth/map#wesnoth.map.terrain_mask|wesnoth.map.terrain_mask]] 
|-
|''wesnoth.paths''
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_cost_map|wesnoth.paths.find_cost_map]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_path|wesnoth.paths.find_path]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_reach|wesnoth.paths.find_reach]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vacant_hex|wesnoth.paths.find_vacant_hex]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vision_range|wesnoth.paths.find_vision_range]] 
|-
|''wesnoth.schedule''
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_illumination|wesnoth.schedule.get_illumination]] 
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_time_of_day|wesnoth.schedule.get_time_of_day]] 
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.replace|wesnoth.schedule.replace]] 
|-
|''wesnoth.sides''
[[LuaAPI/wesnoth/sides#wesnoth.sides.add_ai_component|wesnoth.sides.add_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.append_ai|wesnoth.sides.append_ai]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.change_ai_component|wesnoth.sides.change_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.create|wesnoth.sides.create]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.debug_ai|wesnoth.sides.debug_ai]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.delete_ai_component|wesnoth.sides.delete_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.find|wesnoth.sides.find]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.get|wesnoth.sides.get]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_enemy|wesnoth.sides.is_enemy]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_fogged|wesnoth.sides.is_fogged]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_shrouded|wesnoth.sides.is_shrouded]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.iter|wesnoth.sides.iter]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.matches|wesnoth.sides.matches]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.override_shroud|wesnoth.sides.override_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_fog|wesnoth.sides.place_fog]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_shroud|wesnoth.sides.place_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_fog|wesnoth.sides.remove_fog]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_shroud|wesnoth.sides.remove_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.set_id|wesnoth.sides.set_id]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.switch_ai|wesnoth.sides.switch_ai]] 
|-
|''wesnoth.sync''
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_multiple|wesnoth.sync.evaluate_multiple]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_single|wesnoth.sync.evaluate_single]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.run_unsynced|wesnoth.sync.run_unsynced]] 
|-
|''wesnoth.units''
[[LuaAPI/wesnoth/units#wesnoth.unit.resistance_against|wesnoth.unit.resistance_against]] 
[[LuaAPI/wesnoth/units#wesnoth.units.ability|wesnoth.units.ability]] 
[[LuaAPI/wesnoth/units#wesnoth.units.add_modification|wesnoth.units.add_modification]] 
[[LuaAPI/wesnoth/units#wesnoth.units.advance|wesnoth.units.advance]] 
[[LuaAPI/wesnoth/units#wesnoth.units.chance_to_be_hit|wesnoth.units.chance_to_be_hit]] 
[[LuaAPI/wesnoth/units#wesnoth.units.clone|wesnoth.units.clone]] 
[[LuaAPI/wesnoth/units#wesnoth.units.create|wesnoth.units.create]] 
[[LuaAPI/wesnoth/units#wesnoth.units.create_animator|wesnoth.units.create_animator]] 
[[LuaAPI/wesnoth/units#wesnoth.units.defense_on|wesnoth.units.defense_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.erase|wesnoth.units.erase]] 
[[LuaAPI/wesnoth/units#wesnoth.units.extract|wesnoth.units.extract]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find|wesnoth.units.find]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_attack|wesnoth.units.find_attack]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_map|wesnoth.units.find_on_map]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] 
[[LuaAPI/wesnoth/units#wesnoth.units.get|wesnoth.units.get]] 
[[LuaAPI/wesnoth/units#wesnoth.units.get_hovered|wesnoth.units.get_hovered]] 
[[LuaAPI/wesnoth/units#wesnoth.units.jamming_on|wesnoth.units.jamming_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.matches|wesnoth.units.matches]] 
[[LuaAPI/wesnoth/units#wesnoth.units.movement_on|wesnoth.units.movement_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.remove_modifications|wesnoth.units.remove_modifications]] 
[[LuaAPI/wesnoth/units#wesnoth.units.scroll_to|wesnoth.units.scroll_to]] 
[[LuaAPI/wesnoth/units#wesnoth.units.select|wesnoth.units.select]] 
[[LuaAPI/wesnoth/units#wesnoth.units.to_map|wesnoth.units.to_map]] 
[[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] 
[[LuaAPI/wesnoth/units#wesnoth.units.transform|wesnoth.units.transform]] 
[[LuaAPI/wesnoth/units#wesnoth.units.vision_on|wesnoth.units.vision_on]] 
|-
|''ai''
[[LuaAPI/ai#ai.aspects|ai.aspects]] 
[[LuaAPI/ai#ai.attack|ai.attack]] 
[[LuaAPI/ai#ai.check_attack|ai.check_attack]] 
[[LuaAPI/ai#ai.check_move|ai.check_move]] 
[[LuaAPI/ai#ai.check_recall|ai.check_recall]] 
[[LuaAPI/ai#ai.check_recruit|ai.check_recruit]] 
[[LuaAPI/ai#ai.check_stopunit|ai.check_stopunit]] 
[[LuaAPI/ai#ai.fallback_human|ai.fallback_human]] 
[[LuaAPI/ai#ai.get_attacks|ai.get_attacks]] 
[[LuaAPI/ai#ai.get_targets|ai.get_targets]] 
[[LuaAPI/ai#ai.move|ai.move]] 
[[LuaAPI/ai#ai.move_full|ai.move_full]] 
[[LuaAPI/ai#ai.read_only|ai.read_only]] 
[[LuaAPI/ai#ai.recall|ai.recall]] 
[[LuaAPI/ai#ai.recruit|ai.recruit]] 
[[LuaAPI/ai#ai.side|ai.side]] 
[[LuaAPI/ai#ai.stopunit_all|ai.stopunit_all]] 
[[LuaAPI/ai#ai.stopunit_attacks|ai.stopunit_attacks]] 
[[LuaAPI/ai#ai.stopunit_moves|ai.stopunit_moves]] 
[[LuaAPI/ai#ai.suitable_keep|ai.suitable_keep]] 
|-
|''filesystem''
[[LuaAPI/filesystem#filesystem.canonical_path|filesystem.canonical_path]] 
[[LuaAPI/filesystem#filesystem.have_asset|filesystem.have_asset]] 
[[LuaAPI/filesystem#filesystem.have_file|filesystem.have_file]] 
[[LuaAPI/filesystem#filesystem.image_size|filesystem.image_size]] 
[[LuaAPI/filesystem#filesystem.read_file|filesystem.read_file]] 
[[LuaAPI/filesystem#filesystem.resolve_asset|filesystem.resolve_asset]] 
|-
|''functional''
[[LuaAPI/functional#functional.choose|functional.choose]] 
[[LuaAPI/functional#functional.choose_map|functional.choose_map]] 
[[LuaAPI/functional#functional.filter|functional.filter]] 
[[LuaAPI/functional#functional.filter_map|functional.filter_map]] 
[[LuaAPI/functional#functional.find|functional.find]] 
[[LuaAPI/functional#functional.find_map|functional.find_map]] 
[[LuaAPI/functional#functional.map|functional.map]] 
[[LuaAPI/functional#functional.map_array|functional.map_array]] 
[[LuaAPI/functional#functional.reduce|functional.reduce]] 
[[LuaAPI/functional#functional.take_while|functional.take_while]] 
[[LuaAPI/functional#functional.zip|functional.zip]] 
|-
|''gui''
[[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition]] 
[[LuaAPI/gui#gui.get_user_choice|gui.get_user_choice]] 
[[LuaAPI/gui#gui.show_dialog|gui.show_dialog]] 
[[LuaAPI/gui#gui.show_help|gui.show_help]] 
[[LuaAPI/gui#gui.show_inspector|gui.show_inspector]] 
[[LuaAPI/gui#gui.show_lua_console|gui.show_lua_console]] 
[[LuaAPI/gui#gui.show_menu|gui.show_menu]] 
[[LuaAPI/gui#gui.show_narration|gui.show_narration]] 
[[LuaAPI/gui#gui.show_popup|gui.show_popup]] 
[[LuaAPI/gui#gui.show_prompt|gui.show_prompt]] 
[[LuaAPI/gui#gui.show_story|gui.show_story]] 
[[LuaAPI/gui#gui.widget|gui.widget]] 
|-
|''location_set''
[[LuaAPI/location_set#location_set.clear|location_set.clear]] 
[[LuaAPI/location_set#location_set.clone|location_set.clone]] 
[[LuaAPI/location_set#location_set.create|location_set.create]] 
[[LuaAPI/location_set#location_set.diff|location_set.diff]] 
[[LuaAPI/location_set#location_set.empty|location_set.empty]] 
[[LuaAPI/location_set#location_set.filter|location_set.filter]] 
[[LuaAPI/location_set#location_set.get|location_set.get]] 
[[LuaAPI/location_set#location_set.insert|location_set.insert]] 
[[LuaAPI/location_set#location_set.inter|location_set.inter]] 
[[LuaAPI/location_set#location_set.inter_merge|location_set.inter_merge]] 
[[LuaAPI/location_set#location_set.invert|location_set.invert]] 
[[LuaAPI/location_set#location_set.iter|location_set.iter]] 
[[LuaAPI/location_set#location_set.of_map|location_set.of_map]] 
[[LuaAPI/location_set#location_set.of_pairs|location_set.of_pairs]] 
[[LuaAPI/location_set#location_set.of_raw|location_set.of_raw]] 
[[LuaAPI/location_set#location_set.of_shroud_data|location_set.of_shroud_data]] 
[[LuaAPI/location_set#location_set.of_triples|location_set.of_triples]] 
[[LuaAPI/location_set#location_set.of_wml_var|location_set.of_wml_var]] 
[[LuaAPI/location_set#location_set.random|location_set.random]] 
[[LuaAPI/location_set#location_set.remove|location_set.remove]] 
[[LuaAPI/location_set#location_set.size|location_set.size]] 
[[LuaAPI/location_set#location_set.stable_iter|location_set.stable_iter]] 
[[LuaAPI/location_set#location_set.symm|location_set.symm]] 
[[LuaAPI/location_set#location_set.to_map|location_set.to_map]] 
[[LuaAPI/location_set#location_set.to_pairs|location_set.to_pairs]] 
[[LuaAPI/location_set#location_set.to_shroud_data|location_set.to_shroud_data]] 
[[LuaAPI/location_set#location_set.to_stable_pairs|location_set.to_stable_pairs]] 
[[LuaAPI/location_set#location_set.to_triples|location_set.to_triples]] 
[[LuaAPI/location_set#location_set.to_wml_var|location_set.to_wml_var]] 
[[LuaAPI/location_set#location_set.union|location_set.union]] 
[[LuaAPI/location_set#location_set.union_merge|location_set.union_merge]] 
|-
|''mathx''
[[LuaAPI/mathx#mathx.clamp|mathx.clamp]] 
[[LuaAPI/mathx#mathx.lerp|mathx.lerp]] 
[[LuaAPI/mathx#mathx.random|mathx.random]] 
[[LuaAPI/mathx#mathx.random_choice|mathx.random_choice]] 
[[LuaAPI/mathx#mathx.round|mathx.round]] 
[[LuaAPI/mathx#mathx.shuffle|mathx.shuffle]] 
|-
|''stringx''
[[LuaAPI/stringx#stringx.anim_split|stringx.anim_split]] 
[[LuaAPI/stringx#stringx.escaped_split|stringx.escaped_split]] 
[[LuaAPI/stringx#stringx.format_conjunct_list|stringx.format_conjunct_list]] 
[[LuaAPI/stringx#stringx.format_disjunct_list|stringx.format_disjunct_list]] 
[[LuaAPI/stringx#stringx.iter_range|stringx.iter_range]] 
[[LuaAPI/stringx#stringx.iter_ranges|stringx.iter_ranges]] 
[[LuaAPI/stringx#stringx.join|stringx.join]] 
[[LuaAPI/stringx#stringx.join_map|stringx.join_map]] 
[[LuaAPI/stringx#stringx.map_split|stringx.map_split]] 
[[LuaAPI/stringx#stringx.parenthetical_split|stringx.parenthetical_split]] 
[[LuaAPI/stringx#stringx.parse_range|stringx.parse_range]] 
[[LuaAPI/stringx#stringx.quoted_split|stringx.quoted_split]] 
[[LuaAPI/stringx#stringx.split|stringx.split]] 
[[LuaAPI/stringx#stringx.trim|stringx.trim]] 
[[LuaAPI/stringx#stringx.vformat|stringx.vformat]] 
|-
|''unit_test''
[[LuaAPI/unit_test#unit_test.assert|unit_test.assert]] 
[[LuaAPI/unit_test#unit_test.assert_approx_equal|unit_test.assert_approx_equal]] 
[[LuaAPI/unit_test#unit_test.assert_contains|unit_test.assert_contains]] 
[[LuaAPI/unit_test#unit_test.assert_equal|unit_test.assert_equal]] 
[[LuaAPI/unit_test#unit_test.assert_greater|unit_test.assert_greater]] 
[[LuaAPI/unit_test#unit_test.assert_greater_equal|unit_test.assert_greater_equal]] 
[[LuaAPI/unit_test#unit_test.assert_in_range|unit_test.assert_in_range]] 
[[LuaAPI/unit_test#unit_test.assert_less|unit_test.assert_less]] 
[[LuaAPI/unit_test#unit_test.assert_less_equal|unit_test.assert_less_equal]] 
[[LuaAPI/unit_test#unit_test.assert_not_equal|unit_test.assert_not_equal]] 
[[LuaAPI/unit_test#unit_test.assert_nothrow|unit_test.assert_nothrow]] 
[[LuaAPI/unit_test#unit_test.assert_throws|unit_test.assert_throws]] 
[[LuaAPI/unit_test#unit_test.assert_throws_with|unit_test.assert_throws_with]] 
[[LuaAPI/unit_test#unit_test.fail|unit_test.fail]] 
[[LuaAPI/unit_test#unit_test.finish|unit_test.finish]] 
[[LuaAPI/unit_test#unit_test.fire_wml_menu_item|unit_test.fire_wml_menu_item]] 
[[LuaAPI/unit_test#unit_test.log|unit_test.log]] 
[[LuaAPI/unit_test#unit_test.succeed|unit_test.succeed]] 
[[LuaAPI/unit_test#unit_test.tostring|unit_test.tostring]] 
|-
|''wml''
[[LuaAPI/wml#wml.all_variables|wml.all_variables]] 
[[LuaAPI/wml#wml.array_access.get|wml.array_access.get]] 
[[LuaAPI/wml#wml.array_access.get_proxy|wml.array_access.get_proxy]] 
[[LuaAPI/wml#wml.array_access.set|wml.array_access.set]] 
[[LuaAPI/wml#wml.array_variables|wml.array_variables]] 
[[LuaAPI/wml#wml.attribute_count|wml.attribute_count]] 
[[LuaAPI/wml#wml.child_array|wml.child_array]] 
[[LuaAPI/wml#wml.child_count|wml.child_count]] 
[[LuaAPI/wml#wml.child_range|wml.child_range]] 
[[LuaAPI/wml#wml.clone|wml.clone]] 
[[LuaAPI/wml#wml.diff|wml.diff]] 
[[LuaAPI/wml#wml.equal|wml.equal]] 
[[LuaAPI/wml#wml.error|wml.error]] 
[[LuaAPI/wml#wml.eval_conditional|wml.eval_conditional]] 
[[LuaAPI/wml#wml.find_child|wml.find_child]] 
[[LuaAPI/wml#wml.fire|wml.fire]] 
[[LuaAPI/wml#wml.get_child|wml.get_child]] 
[[LuaAPI/wml#wml.get_nth_child|wml.get_nth_child]] 
[[LuaAPI/wml#wml.interpolate|wml.interpolate]] 
[[LuaAPI/wml#wml.literal|wml.literal]] 
[[LuaAPI/wml#wml.load|wml.load]] 
[[LuaAPI/wml#wml.matches_filter|wml.matches_filter]] 
[[LuaAPI/wml#wml.merge|wml.merge]] 
[[LuaAPI/wml#wml.parse|wml.parse]] 
[[LuaAPI/wml#wml.parsed|wml.parsed]] 
[[LuaAPI/wml#wml.patch|wml.patch]] 
[[LuaAPI/wml#wml.remove_child|wml.remove_child]] 
[[LuaAPI/wml#wml.remove_children|wml.remove_children]] 
[[LuaAPI/wml#wml.shallow_literal|wml.shallow_literal]] 
[[LuaAPI/wml#wml.shallow_parsed|wml.shallow_parsed]] 
[[LuaAPI/wml#wml.tag|wml.tag]] 
[[LuaAPI/wml#wml.tostring|wml.tostring]] 
[[LuaAPI/wml#wml.tovconfig|wml.tovconfig]] 
[[LuaAPI/wml#wml.valid|wml.valid]] 
[[LuaAPI/wml#wml.variables|wml.variables]] 
[[LuaAPI/wml#wml.variables_proxy|wml.variables_proxy]] 
|-
|''wml-utils''
[[LuaAPI/wml-utils#utils.check_key|utils.check_key]] 
[[LuaAPI/wml-utils#utils.get_sides|utils.get_sides]] 
[[LuaAPI/wml-utils#utils.handle_event_commands|utils.handle_event_commands]] 
[[LuaAPI/wml-utils#utils.optional_side_filter|utils.optional_side_filter]] 
[[LuaAPI/wml-utils#utils.scoped_var|utils.scoped_var]] 
[[LuaAPI/wml-utils#utils.set_exiting|utils.set_exiting]] 
[[LuaAPI/wml-utils#utils.vwriter|utils.vwriter]] 
|}