The Battle for Wesnoth Wiki - User contributions [en]

UsefulLinks

2026-03-27T13:24:53Z

Soliton: /* Battle for Wesnoth */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Compatibility-breaking changes || https://forums.wesnoth.org/viewtopic.php?t=58532
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Site status || https://status.wesnoth.org
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth [https://insights.linuxfoundation.org/project/wesnoth LFX insights]
|-
|Packages || https://repology.org/project/wesnoth/versions [https://pkgs.org/search/?q=wesnoth pkgs.org] [https://pkgdex.org/search/all/wesnoth pkgdex.org]
|-
|F-Droid || https://f-droid.org/packages/org.wesnoth.Wesnoth/
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

ReferenceWML

2026-03-23T17:36:46Z

Soliton: /* Predefined macros */

{{WML Tags}}
== The Wesnoth Markup Language ==

The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML. A major feature in WML are macros, which are alike those found in the C language and similarily are handled by a preprocessor. Implementation-wise, WML files are handled mainly by the ''config'' class (and ''simple_wml'' in [[wesnothd]]).

This page is a collection of pointers to different common WML structures.

See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]
for a tutorial style overview.

''Note: this reference may contain slight inaccuracies, might not list all existing keys and tags or might contain some deprecated syntax. If you find that this reference doesn't give you the answer to how to implement some feature in WML, the most reliable way is to look at the WML code of existing units and campaigns that have done so.''

== How WML works ==

* [[SyntaxWML]] Description of WML syntax
* [[VariablesWML]] How to use WML variables
* [[PreprocessorRef]] the WML preprocessor syntax
* [[GrammarWML]] A more formal definition of the WML syntax. More useful for implementing a WML parser than for writing WML documents.
* [[AddonsWML]] Content that can be published and downloaded via the add-ons server

== WML toplevel tags ==

The following covers most of the possible toplevel tags in a typical main WML file. Some minor and dev-oriented tags (not intended for use by UMC) are omitted.

* [[GameConfigWML]] the top level '''[game_config]''' tag
* [[UnitsWML]] the top level '''[units]''' tag
** [[AbilitiesWML]] a list of the different abilities a unit or weapon can have
** [[UnitTypeWML]] how to describe a unit type
** [[AnimationWML]] how to animate units
* [[CoreWML]] the top level '''[core]''' tag
* [[CampaignWML]] the top level '''[campaign]''' tag
** [[CreditsWML]] how to describe the credits (the '''[about]''' tag)
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', and '''[test]'''
** [[EventWML]] how to describe an event (the '''[event]''' tag)
** [[SideWML]] how to describe a side (the '''[side]''' tag)
** [[MapGeneratorWML]] the random map generator
** [[TimeWML]] how to describe a day
** [[IntroWML]] how to describe the intro screen (the '''[story]''' and '''[part]''' tags)
* [[EraWML]] the top level '''[era]''' tag
* [[ModificationWML]] the top level '''[modification]''' and '''[resource]''' tags
* [[TerrainWML]] the top level '''[terrain_type]''' tag
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag
* [[ThemeWML]] the top level '''[theme]''' tag
* [[LanguageWML]] the top level '''[language]''' tag
* [[LocaleWML]] the top level '''[locale]''' tag
* [[HelpWML]] the top level '''[help]''' tag
* [[BinaryPathWML]] the top level '''[binary_path]''' tag
* [[FontsWML]] the top level '''[fonts]''' tag
* [[GettextForWesnothDevelopers#The_textdomain_tag|Textdomains]] the '''[textdomain]''' tag

Some other files use the WML format, but with different tags.

* [[AchievementsWML]] the '''[achievement_group]''' and '''[achievement]''' tags.
* [[SavefileWML]] a description of the format of savegames
** [[ReplayWML]] a description of the format of player actions such as moving a unit
** [[StatisticalScenarioWML]] used to generate statistics of a savegame
* [[PblWML]] a description of the format of server-uploadable campaigns
* [[SchemaWML]] a description of WML files that define the structure of other WML files
* [[DiffWML]] used to describe structural differences between preprocessed WML documents
* [[GUIToolkit]] gives an overview of Wesnoth's current UI system and how to create user interfaces with it.

== Other WML tags ==

* [[EventWML]] how to describe an event
** [[FilterWML]] the construct to filter on [[StandardUnitFilter|units]], [[StandardLocationFilter|locations]], [[StandardSideFilter|sides]], weapons, vision, and WML data.
** [[ActionWML]] to describe the actions which occur when the event is fired
*** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met
*** [[DirectActionsWML]] actions that directly affect gameplay: for example, creating a unit
**** [[SingleUnitWML]] how to describe a unit (for uses such as placing one on the map with the '''[unit]''' tag)
*** [[InternalActionsWML]] actions that WML uses internally: for example, storing a variable
*** [[InterfaceActionsWML]] actions that do not affect gameplay: for example, displaying a message
*** [[LuaWML]] how to code actions with the Lua language (BfW 1.14 and earlier)
*** [[LuaAPI]] how to code actions with the Lua language (BfW 1.16 and later)
* [[AiWML]] how to describe parameters for AI (the '''[ai]''' tag)
* [[EffectWML]] the construct to modify a unit (the '''[effect]''' tag)
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns
* [[EditorWML]] tags controlling the post-1.4 editor's behavior
* [[MusicListWML]] for playing music (see also [[Available Music]] for a list of what's available)

== Predefined macros ==

Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.
* [https://www.wesnoth.org/macro-reference.html WML Macros] - description of all such macros.
* [https://www.wesnoth.org/macro-reference-master.html WML Macros (master)] - latest development version.

== Other ==

* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted
* [[ConventionsWML]] how to make your WML more readable
* [[Wml_optimisation]] how to make your WML code more efficient
* [[UsefulWMLFragments]] Various pieces of WML for various purposes. If you have some WML you're proud of that you think others can use, add it here.
* [[Maintenance tools]] for wmlindent, wmllint, wmlscope
* [[CommandMode]] commands are not strictly speaking part of WML, but they are useful for debugging it, and could be a little hard to find, so linking to them here makes sense.
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
* [[ImagePathFunctions]] (IPFs) are used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.
* [[Pango formatting]] shows ways to enrich descriptions using pango markup, which can use basic html style formatting tags, such as <nowiki>, , </nowiki> and others.
* [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] often used with $() formulas.
* [[PreprocessorRef|Syntax of preprocessor mini-language]] : symbols, macros, file inclusions...

== See Also ==

* [[BuildingMaps]] the text-based format for Wesnoth maps
* [[TerrainCodeTableWML]] a list of all terrains, and [[TerrainCodesWML]], on how to use them
* [[MultiHexTutorial]] a description of the multi-hex tiling system
* [[IGNFileFormat]] a description of the ignore file format
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]
* [[Environment_variables]] a cheat-sheet for CLI environment variables
* Back to [[Create]]

[[Category: WML Reference]]

ConditionalActionsWML

2026-03-22T18:21:17Z

Soliton: /* [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 unset when this value is ''yes'' and set 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]]

InternalActionsWML

2026-03-21T11:25:49Z

Soliton: /* [set_variables] */

{{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 variable '''name''' and replace it with given data. This is the default value. If given an explicit index, such as name=my_array[1], only that single element of the array is replaced, and the new data is inserted into that slot, potentially pushing other elements up. If ''not'' given an explicit index, the entire array is replaced.
** ''append'': will append given data to the current array. An explicit index is ignored if given.
** ''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. If given an explicit index, all the '''[value]''' and '''[literal]''' tags will be joined together into a single tag, and this resulting container will then be merged into the container at the specified element. 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. Otherwise, it is inserted so as to become the element at the specified index, meaning that the element previously at that index and all later elements are pushed up by one. '''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.

'''Note''': Only events whose IDs are explicitly specified will be removed. For example, this will ''not'' automatically remove events nested within the events with those IDs.

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

UsefulLinks

2026-03-09T19:25:53Z

Soliton: /* Battle for Wesnoth */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Compatibility-breaking changes || https://forums.wesnoth.org/viewtopic.php?t=58532
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Site status || https://status.wesnoth.org
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth [https://insights.linuxfoundation.org/project/wesnoth LFX insights]
|-
|Packages || https://repology.org/project/wesnoth/versions [https://pkgs.org/search/?q=wesnoth pkgs.org] [https://pkgdex.org/search/all/wesnoth pkgdex.org]
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2026-03-09T17:41:49Z

Soliton: /* Battle for Wesnoth */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Compatibility-breaking changes || https://forums.wesnoth.org/viewtopic.php?t=58532
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Site status || https://status.wesnoth.org
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
|Packages || https://repology.org/project/wesnoth/versions [https://pkgs.org/search/?q=wesnoth pkgs.org] [https://pkgdex.org/search/all/wesnoth pkgdex.org]
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2026-03-09T17:40:33Z

Soliton: /* Battle for Wesnoth */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Compatibility-breaking changes || https://forums.wesnoth.org/viewtopic.php?t=58532
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Site status || https://status.wesnoth.org
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
|Packages || https://repology.org/project/wesnoth/versions [https://pkgs.org/search/?q=wesnoth pkgs.org] [https://pkgdex.org/search/all/wesnoth pkgdex.org]
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

WesnothTranslations

2026-03-06T15:18:47Z

Soliton: /* Mailing List */

== Translations ==

Wesnoth is currently being translated into the following languages. These languages are active, with maintainer.
{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AncientGreekTranslation|Ancient Greek]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[ArabicTranslation|Arabic]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[BengaliTranslation|Bengali]] || Subhraman Sarkar (LumiousE) || lumious_e on Discord
|-
| [[BulgarianTranslation|Bulgarian]] || Ivan Petrov (TheWhiteKnight) || [mailto:vankata_petrovATabvDOTbg]
|-
| [[CatalanTranslation|Catalan]] || Arnau Vàzquez Palma || [mailto:arnauvpATmurenaDOTio]
|-
| [[ChineseTranslation|Chinese]] || CloudiDust || [mailto:cloudidustATgmailDOTcom]
|-
| [[ChineseTaiwanTranslation|Chinese (Taiwan)]] || 楊綮銘 (Taiwan) || [mailto:steven2880ATgmailDOTcom]
|-
| [[CzechTranslation|Czech]] || Michal Žejdl || [mailto:lachimATemerDOTcz]
|-
| [[DutchTranslation|Dutch]] || Merijn de Vet || [mailto:merijndevetAThotmailDOTcom]
|-
| [[EnglishGBTranslation|English (GB)]] || Wedge009 || [mailto:wedge009ATwedge009DOTnet]
|-
| [[EnglishShawTranslation|English (Shaw)]] || Arc Riley || [mailto:ArcRileyATubuntuDOTcom]
|-
| [[Esperanto_translation|Esperanto]] || Mariano Street (mctpyt) || [mailto:mctpytATprotonDOTme]
|-
| [[FinnishTranslation|Finnish]] || Jaakko Saarikko (styxnix) || [mailto:jaakkoDOTsaarikkoATprotonmailDOTcom]
|-
| [[FrenchTranslation|French]] || demario || [mailto:wesnothfr-request@lists.tuxfamily.org?subject=subscribe mailing list]
|-
| [[GermanTranslation|German]] || Aaron Winter (Bitron) ||
|-
| [[HungarianTranslation|Hungarian]] || Berda Jenő (bigbilly) || [mailto:big4billyATgmailDOTcom]
|-
| [[IndonesianTranslation|Indonesian]] || Irsyad Musthafa || [mailto:sevennightmareATtutanotaDOTde]
|-
| [[ItalianTranslation|Italian]] || Antonio Rosella || [mailto:arosellaATyahooDOTcom]
|-
| [[JapaneseTranslation|Japanese]] || Hironori Fujimoto (RatArmy) || [mailto:broadbarredfirefishATgmailDOTcom]
|-
| [[KoreanTranslation|Korean]] || mistzone || [mailto:drier22ATgmailDOTcom]
|-
| [[LatinTranslation|Latin]] || Daniel Faustmann || [mailto:donnerstag.freitag213@gmail.com]
|-
| [[NorwegianTranslation|Norwegian]] || Bloodaxe || [mailto:bloodaxenor@protonmail.com]
|-
| [[PolishTranslation|Polish]] || ForPeace || [https://forums.wesnoth.org/viewtopic.php?f=7&t=3796 forum thread]
|-
| [[PortugueseTranslation|Portuguese Brazilian]] || Andrei Machado || [mailto:andreisp.machadoATyahooDOTcom]
|-
| [[PortugueseContinentalTranslation|Portuguese (European)]] || trewe || [mailto:sjrs456ATyahooDOTfr]
|-
| [[RussianTranslation|Russian]] || Artem Khrapov || ([[User:kabachuha|kabachuha]]) [mailto:artemkhrapov2001ATyandexDOTru]
|-
| [[Scottish_Gaelic_Translation|Scottish Gaelic]] || GunChleoc || [mailto:fiosAIGforamnagaidhligDOTnet]
|-
| [[SlovakTranslation#Preklad|Slovak]] || Stanislav Hoferek || [mailto:shoferek@gmail.com]
|-
| [[SpanishTranslation|Spanish]] || Sebastián Lecchini (Sebas38760) || [mailto:sebas38760@gmail.com]
|-
| [[SwedishTranslation|Swedish]] || Alex Alowersson (fluxbird) || [mailto:alexalowersonATgmailDOTcom]
|-
| [[TurkishTranslation|Turkish]] || Nilgün Belma Bugüner || [mailto:nilgunATbelgelerDOTorg]
|-
| [[UkrainianTranslation|Ukrainian]] || Oleksii Okhrimenko (lexa04) || Discord: amakri Email: [mailto:ohrimaleATgmailDOTcom]
|}

Currently inactive translations. If you wish to improve some of these languages (or one of the above maintainers is not responsive), contact Ivanovic on the [https://wiki.wesnoth.org/Support Wesnoth Discord channel].

{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AfrikaansTranslation|Afrikaans]] || None || N/A
|-
| [[BasqueTranslation|Basque]] || None || N/A
|-
| [[BurmeseTranslation|Burmese]] || None || N/A
|-
| [[CroatianTranslation|Croatian]] || None || N/A
|-
| [[DanishTranslation|Danish]] || None || N/A
|-
| [[GalicianTranslation|Galician]] || None || N/A
|-
| [[GreekTranslation|Greek]] || None || N/A
|-
| [[HebrewTranslation|Hebrew]] || None || N/A
|-
| [[IcelandicTranslation|Icelandic]] || None || N/A
|-
| [[IrishTranslation|Irish]] || None || N/A
|-
| [[LatvianTranslation|Latvian]] || None || N/A
|-
| [[LithuanianTranslation|Lithuanian]] || None || N/A
|-
| [[MarathiTranslation|Marathi]] || None || N/A
|-
| [[MacedonianTranslation|Macedonian]] || None || N/A
|-
| [[OldEnglishTranslation|Old English]] || None || N/A
|-
| [[RACVTranslation|RACV]] || None || N/A
|-
| [[RomanianTranslation|Romanian]] || None || N/A
|-
| [[SerbianTranslation|Serbian]] || None || N/A
|-
| [[SlovenianTranslation|Slovenian]] || None || N/A
|-
| [[SpanishLatinAmericanTranslation|Spanish (Latin American)]] || None || N/A
|-
| [[ValencianTranslation|Valencian]] || None || N/A
|-
| [[VietnameseTranslation|Vietnamese]] || None || N/A
|}

== Mailing List ==

There now is a mailing list dedicated to translation matters. It is mainly intended to be used for informing translation maintainers about important changes, to announce string freezes and other special things. Everyone is free to subscribe to this list.

* [https://groups.io/g/wesnoth-translations From Februar 2025]
* [https://listengine.tuxfamily.org/wesnoth.org/i18n/ List info, how to subscribe, and archives from April 2022]
* [https://mailman.wesnoth.org/pipermail/i18n/ Old list archives (up until April 2022)]

Please keep in mind that this list is not meant for discussing changes for one single translation but instead subjects which are relevant to all translations.

== See also ==

* [[WesnothTranslationsHowTo]]
* [[ImageLocalization]]
* [[GetText]]
* [http://gettext.wesnoth.org Translations statistics (stable)]
* [http://gettext.wesnoth.org/index.php?version=trunk&package=alloff Translations statistics (development)]
* [[GettextForTranslators#For_add-ons|Translating User Made Campaigns and add-ons]]
* [[SpellingMistakes]]
* [[CharactersStorys| Character descriptions for Translators (Spoiler Warning)]]
* [[Poetry of Wesnoth Translations]]

[[Category:Translations|*]]

WesnothTranslations

2026-03-06T15:08:39Z

Soliton: /* Translations */

== Translations ==

Wesnoth is currently being translated into the following languages. These languages are active, with maintainer.
{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AncientGreekTranslation|Ancient Greek]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[ArabicTranslation|Arabic]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[BengaliTranslation|Bengali]] || Subhraman Sarkar (LumiousE) || lumious_e on Discord
|-
| [[BulgarianTranslation|Bulgarian]] || Ivan Petrov (TheWhiteKnight) || [mailto:vankata_petrovATabvDOTbg]
|-
| [[CatalanTranslation|Catalan]] || Arnau Vàzquez Palma || [mailto:arnauvpATmurenaDOTio]
|-
| [[ChineseTranslation|Chinese]] || CloudiDust || [mailto:cloudidustATgmailDOTcom]
|-
| [[ChineseTaiwanTranslation|Chinese (Taiwan)]] || 楊綮銘 (Taiwan) || [mailto:steven2880ATgmailDOTcom]
|-
| [[CzechTranslation|Czech]] || Michal Žejdl || [mailto:lachimATemerDOTcz]
|-
| [[DutchTranslation|Dutch]] || Merijn de Vet || [mailto:merijndevetAThotmailDOTcom]
|-
| [[EnglishGBTranslation|English (GB)]] || Wedge009 || [mailto:wedge009ATwedge009DOTnet]
|-
| [[EnglishShawTranslation|English (Shaw)]] || Arc Riley || [mailto:ArcRileyATubuntuDOTcom]
|-
| [[Esperanto_translation|Esperanto]] || Mariano Street (mctpyt) || [mailto:mctpytATprotonDOTme]
|-
| [[FinnishTranslation|Finnish]] || Jaakko Saarikko (styxnix) || [mailto:jaakkoDOTsaarikkoATprotonmailDOTcom]
|-
| [[FrenchTranslation|French]] || demario || [mailto:wesnothfr-request@lists.tuxfamily.org?subject=subscribe mailing list]
|-
| [[GermanTranslation|German]] || Aaron Winter (Bitron) ||
|-
| [[HungarianTranslation|Hungarian]] || Berda Jenő (bigbilly) || [mailto:big4billyATgmailDOTcom]
|-
| [[IndonesianTranslation|Indonesian]] || Irsyad Musthafa || [mailto:sevennightmareATtutanotaDOTde]
|-
| [[ItalianTranslation|Italian]] || Antonio Rosella || [mailto:arosellaATyahooDOTcom]
|-
| [[JapaneseTranslation|Japanese]] || Hironori Fujimoto (RatArmy) || [mailto:broadbarredfirefishATgmailDOTcom]
|-
| [[KoreanTranslation|Korean]] || mistzone || [mailto:drier22ATgmailDOTcom]
|-
| [[LatinTranslation|Latin]] || Daniel Faustmann || [mailto:donnerstag.freitag213@gmail.com]
|-
| [[NorwegianTranslation|Norwegian]] || Bloodaxe || [mailto:bloodaxenor@protonmail.com]
|-
| [[PolishTranslation|Polish]] || ForPeace || [https://forums.wesnoth.org/viewtopic.php?f=7&t=3796 forum thread]
|-
| [[PortugueseTranslation|Portuguese Brazilian]] || Andrei Machado || [mailto:andreisp.machadoATyahooDOTcom]
|-
| [[PortugueseContinentalTranslation|Portuguese (European)]] || trewe || [mailto:sjrs456ATyahooDOTfr]
|-
| [[RussianTranslation|Russian]] || Artem Khrapov || ([[User:kabachuha|kabachuha]]) [mailto:artemkhrapov2001ATyandexDOTru]
|-
| [[Scottish_Gaelic_Translation|Scottish Gaelic]] || GunChleoc || [mailto:fiosAIGforamnagaidhligDOTnet]
|-
| [[SlovakTranslation#Preklad|Slovak]] || Stanislav Hoferek || [mailto:shoferek@gmail.com]
|-
| [[SpanishTranslation|Spanish]] || Sebastián Lecchini (Sebas38760) || [mailto:sebas38760@gmail.com]
|-
| [[SwedishTranslation|Swedish]] || Alex Alowersson (fluxbird) || [mailto:alexalowersonATgmailDOTcom]
|-
| [[TurkishTranslation|Turkish]] || Nilgün Belma Bugüner || [mailto:nilgunATbelgelerDOTorg]
|-
| [[UkrainianTranslation|Ukrainian]] || Oleksii Okhrimenko (lexa04) || Discord: amakri Email: [mailto:ohrimaleATgmailDOTcom]
|}

Currently inactive translations. If you wish to improve some of these languages (or one of the above maintainers is not responsive), contact Ivanovic on the [https://wiki.wesnoth.org/Support Wesnoth Discord channel].

{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AfrikaansTranslation|Afrikaans]] || None || N/A
|-
| [[BasqueTranslation|Basque]] || None || N/A
|-
| [[BurmeseTranslation|Burmese]] || None || N/A
|-
| [[CroatianTranslation|Croatian]] || None || N/A
|-
| [[DanishTranslation|Danish]] || None || N/A
|-
| [[GalicianTranslation|Galician]] || None || N/A
|-
| [[GreekTranslation|Greek]] || None || N/A
|-
| [[HebrewTranslation|Hebrew]] || None || N/A
|-
| [[IcelandicTranslation|Icelandic]] || None || N/A
|-
| [[IrishTranslation|Irish]] || None || N/A
|-
| [[LatvianTranslation|Latvian]] || None || N/A
|-
| [[LithuanianTranslation|Lithuanian]] || None || N/A
|-
| [[MarathiTranslation|Marathi]] || None || N/A
|-
| [[MacedonianTranslation|Macedonian]] || None || N/A
|-
| [[OldEnglishTranslation|Old English]] || None || N/A
|-
| [[RACVTranslation|RACV]] || None || N/A
|-
| [[RomanianTranslation|Romanian]] || None || N/A
|-
| [[SerbianTranslation|Serbian]] || None || N/A
|-
| [[SlovenianTranslation|Slovenian]] || None || N/A
|-
| [[SpanishLatinAmericanTranslation|Spanish (Latin American)]] || None || N/A
|-
| [[ValencianTranslation|Valencian]] || None || N/A
|-
| [[VietnameseTranslation|Vietnamese]] || None || N/A
|}

== Mailing List ==

There now is a mailing list dedicated to translation matters. It is mainly intended to be used for informing translation maintainers about important changes, to announce string freezes and other special things. Everyone is free to subscribe to this list.

* [https://listengine.tuxfamily.org/wesnoth.org/i18n/ List info, how to subscribe, and archives from April 2022]
* [https://mailman.wesnoth.org/pipermail/i18n/ Old list archives (up until April 2022)]

Please keep in mind that this list is not meant for discussing changes for one single translation but instead subjects which are relevant to all translations.

== See also ==

* [[WesnothTranslationsHowTo]]
* [[ImageLocalization]]
* [[GetText]]
* [http://gettext.wesnoth.org Translations statistics (stable)]
* [http://gettext.wesnoth.org/index.php?version=trunk&package=alloff Translations statistics (development)]
* [[GettextForTranslators#For_add-ons|Translating User Made Campaigns and add-ons]]
* [[SpellingMistakes]]
* [[CharactersStorys| Character descriptions for Translators (Spoiler Warning)]]
* [[Poetry of Wesnoth Translations]]

[[Category:Translations|*]]

UsefulLinks

2026-03-04T15:47:06Z

Soliton: /* Battle for Wesnoth */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Compatibility-breaking changes || https://forums.wesnoth.org/viewtopic.php?t=58532
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
|Packages || https://repology.org/project/wesnoth/versions [https://pkgs.org/search/?q=wesnoth pkgs.org] [https://pkgdex.org/search/all/wesnoth pkgdex.org]
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

EraWML

2026-03-02T14:55:08Z

Soliton: /* Defining Factions */

{{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''': a comma separated 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]]

ImageMetadata

2026-02-18T12:36:36Z

Soliton: /* Image Metadata */

== Image Metadata ==

Author and [[Wesnoth:Copyrights#The_Battle_for_Wesnoth_-_Visual_and_Audio_Contributions|copyright]] data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool is supposed to read but not write this flag (so ''-all='' argument shouldn't clobber it, but sometimes it does). GIMP will set this flag, but it can get removed by further processing. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - were briefly used for PNG because they are most likely to be edited with GIMP. However, this fact was not worth the extra size and complication, so they are no longer used. Please use the EXIF tags for PNG, just like JPG and WEBP.
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP, JPG and PNG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -EXIF:CreateDate="<Y:m:d H:M:S>" -EXIF:Copyright="<copyright>" -EXIF:Artist="<name (account name)>" -EXIF:UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy github continuous integration (CI), image metadata is checked for a small set of entries.

For PNG, JPEG, WEBP:
* '''EXIF:Artist''' must exist. The format is "Real Name (screen/account name)" with each person separated by a semicolon (;) and either real name or screen name may be omitted. More than one "artist" does not imply a collaboration, it may just mean there was a visible edit to the image.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0". The copyright cannot be changed arbitrarily.

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
'''Note:''' Since most of the information below deals with XMP data, it is of limited value. However, the more relevant EXIF data can often be preserved if editing an existing image, so pay attention to save/export options in whatever editor you use. The XMP metadata may still be worth saving because information can be transferred from XMP to EXIF. An example from '''exiftool''' would be the -[+]TAG[+-]<SRCTAG option:

<code>exiftool '-EXIF:Artist<XMP:Creator' my_image.png</code>

====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

===Examples===
A sprite (PNG) with the needed EXIF tags is shown below.

https://forums.wesnoth.org/download/file.php?id=99973&type=.png

Examples of WebP showing the Alpha flag issue can be found at this forum post:

https://forums.wesnoth.org/viewtopic.php?p=694451#p694451

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

EventWML

2026-02-06T21:10:33Z

Soliton: /* turn refresh */

{{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). Once created, there is no relation between the nested event and the parent event (for example, removing the parent event would not remove the nested 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 (for side 1), 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]]

UsefulLinks

2025-12-11T18:21:46Z

Soliton:

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Compatibility-breaking changes || https://forums.wesnoth.org/viewtopic.php?t=58532
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2025-12-11T18:20:45Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|Compatibility-breaking changes || https://forums.wesnoth.org/viewtopic.php?t=58532
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UnitTypeWML

2025-12-02T16:54:22Z

Soliton: /* Unit Type */

{{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 an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units 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 [[UnitsWML#.5Brace.5D|[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. If the image width or height is equal or above 300 the engine will scale the image with a factor between 1/2 and 1. 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]].
** '''specials_list''': {{DevFeature1.19|17}} A comma-separated list of weapon special [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]], these will be added to this attack as if their full definition was included in '''[weapon_specials]'''. Example: ''weapon_specials=plague,magical''.
** '''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}} decouples the attack's alignment from the unit's alignment. One of ''lawful'', ''neutral'', ''chaotic'', ''liminal'' (See [[TimeWML]]). If unspecified, the unit alignment is used. Only useful for units with multiple attacks, otherwise you can change the unit alignment instead.

== 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]]
* '''abilities_list''': {{DevFeature1.19|17}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this unit type as if their full definition was included in '''[abilities]'''. Example: ''abilities=heals_8,regenerates''.

* '''[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]]

Cpp features blocked by version

2025-11-28T22:35:16Z

Soliton:

== Summary ==
This is a listing of C++ features that would be useful to have but can't yet be used. The Feature column is the language or standard library feature (https://en.cppreference.com/w/cpp/compiler_support is a good reference). The Benefit column is what having this feature will allow to be done. The remaining three columns are for the minimum requirements for the feature to be available on each platform. The minimum requirements can be anything - Visual Studio version, compiler version, OS version, etc.

== Benefits that don't justify version increases ==
This is a non-exhaustive list:
* Improving compile speed.
* Pretty much any standard library feature that we can just as well get through boost or other means.
* Core language features that allow writing more succinct code.

== Benefits that do justify version increases ==
This is a non-exhaustive list:
* Required to fix a bug that has a significant impact to players.
* Core language features that make classes of bugs impossible or significantly harder to accidentally introduce.
* Required to fix a relevant security vulnerability.
* A group of multiple smaller features that individually don't justify a version increase, if there's minimal to no impact to developers and players.

== Features ==
{| class="wikitable sortable"
|-
! Feature !! Benefit !! Windows !! macOS !! Linux !! Notes
|-
| Modules || Faster compile time || Unknown || Unknown || Unknown || While part of C++20, usable support seems to be progressing very slowly.
|-
| std::starts_with and ends_with || Simplies string checking in various places, including filesystem || MSVC STL 19.21 (VS 2019 16.1) || Apple Clang 10.0.0 (Xcode 10.0 beta (10L176w), 10.0 (10A255), 10.1 (10B61)) || GCC libstdc++ 9/Clang libc++ 6 || Boost offers similar functions.
|-
| std::format || Cleans up our numerous uses of manual string concatenation, especially with pango strings in the UI || Unknown || Unknown || Unknown || The wesnoth variable substitution facility offers similar functions, though with a little less versatility (but it could be extended).
|-
| std::span || Potential to reduce templates where we only need a container view || Unknown || Unknown || Unknown ||
|-
| Concepts || Cleaner template requirements (increased code clarity) || Unknown || Unknown || Unknown || https://gcc.gnu.org/bugzilla/show_bug.cgi?id=concepts
|-
| Standard feature check macros || Ability to enable features on an individual basis without doing a whole-language flag || Unknown || Unknown || Unknown || Clang and likely GCC already support them on older versions as an extension.
|-
| std::filesystem || || Unknown || Just need to target 10.15 || Unknown || We do have boost....
|}

[[Category:Development]]

Context-free grammar

2025-11-19T10:58:26Z

Soliton:

Context-free grammar can be used to generate random strings, from short words to entire paragraphs. If you are interested in its theory, read more on [https://en.wikipedia.org/wiki/Context-free_grammar Wikipedia's article on the topic].

== Syntax ==
In WML, it uses its own simple syntax. It is usually a translatable string and should be in <nowiki><></nowiki>. The code is composed from nonterminals. They are written on separate lines. Each nonterminal is substituted by one of its possibilities separated by the '''|''' symbol, the name is separated from possibilities with '''='''. The nonterminal that makes the result is named <nowiki>main</nowiki>. The possibilities can contain other nonterminals, marked by <nowiki>{curly brackets}</nowiki>.

Including literal vertical bars or curly braces can be done by using the following predefined nonterminals:
* <code>{!}</code> - expands to a |
* <code>{(}</code> - expands to a {
* <code>{)}</code> - expands to a }

== Examples ==

<syntaxhighlight lang=wml>
name_generator= _ <<
main=Hello world|Hi world|Ahoi world
>>
</syntaxhighlight>

The result is either ''Hello world'' or ''Hi world'' or ''Ahoi world''.

<syntaxhighlight lang=wml>
name_generator= _ <<
main=Hello {noun}|Hi {noun}
noun=world|planet|Universe|Earth
>>
</syntaxhighlight>

The result is either ''Hello'' or ''Hi'', followed by one of the four possible nouns, ''world'', ''planet'', ''Universe'' or ''Earth''.

== Other rules ==
A nonterminal can reference itself, which can, under the right circumstances, lead to a loop that expands indefinitely, causing a stack overflow. Avoid this unless you really know what you are doing.

Each nonterminal has a reduced probability for possibilities that were chosen the last time.

== External links ==
* [https://dugy.github.io/?M2NvbvRmdWzsbGFu5zJzb3VyY+V0eXDlf21haW49e0hlbGxvfSwge3Zpc2l0b3J9IQpIZWxsbz1IZWxsb3xIZXl8V2VsY29tZQp2aXNpdG9yPXZpc2l0b3J8ZnJpZW5kfHBhbABjY2ZnAkA= Dugi's online context-free grammar tester] (warning: if opening, be sure to do so in a new tab)

Context-free grammar

2025-11-19T10:53:40Z

Soliton: /* Syntax */

Context-free grammar can be used to generate random strings, from short words to entire paragraphs. If you are interested in its theory, read more on [https://en.wikipedia.org/wiki/Context-free_grammar Wikipedia's article on the topic].

== Syntax ==
In WML, it uses its own simple syntax. It is usually a translatable string and should be in <nowiki><></nowiki>. The code is composed from nonterminals. They are written on separate lines. Each nonterminal is substituted by one of its possibilities separated by the '''|''' symbol, the name is separated from possibilities with '''='''. The nonterminal that makes the result is named <nowiki>main</nowiki>. The possibilities can contain other nonterminals, marked by <nowiki>{curly brackets}</nowiki>.

== Examples ==

<syntaxhighlight lang=wml>
name_generator= _ <<
main=Hello world|Hi world|Ahoi world
>>
</syntaxhighlight>

The result is either ''Hello world'' or ''Hi world'' or ''Ahoi world''.

<syntaxhighlight lang=wml>
name_generator= _ <<
main=Hello {noun}|Hi {noun}
noun=world|planet|Universe|Earth
>>
</syntaxhighlight>

The result is either ''Hello'' or ''Hi'', followed by one of the four possible nouns, ''world'', ''planet'', ''Universe'' or ''Earth''.

== Other rules ==
A nonterminal can reference itself, which can, under the right circumstances, lead to a loop that expands indefinitely, causing a stack overflow. Avoid this unless you really know what you are doing.

Each nonterminal has a reduced probability for possibilities that were chosen the last time.

A production may include vertical bars or curly braces by using the following predefined nonterminals:
* <code>{!}</code> - expands to a |
* <code>{(}</code> - expands to a {
* <code>{)}</code> - expands to a }

== External links ==
* [https://dugy.github.io/?M2NvbvRmdWzsbGFu5zJzb3VyY+V0eXDlf21haW49e0hlbGxvfSwge3Zpc2l0b3J9IQpIZWxsbz1IZWxsb3xIZXl8V2VsY29tZQp2aXNpdG9yPXZpc2l0b3J8ZnJpZW5kfHBhbABjY2ZnAkA= Dugi's online context-free grammar tester] (warning: if opening, be sure to do so in a new tab)

Android

2025-10-02T11:04:15Z

Soliton: /* Other version code scheme drafts */

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

=== Dev Notes ===
==== Version Code scheme (1191601001 - post 1.19.16 fixup) ====
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

==== New Version Code scheme draft ====
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

==== Other version code scheme drafts ====

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid creates the file /data/dist with contents "F-Droid" during the build process)
* we may want various variants of builds, that is, a "clean" build, a build with google play integrations, a build with a different integration, and so on. This may or may not be tied to the store the APK is distributed on

Drafts of possible approaches:

===== <code>MMMPPpxxVA</code> =====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - Build variant (0 is clean, 1 might be google play integrations. Could be a bitfield or an enum)
* A - ABI (as above)
* x - Unspecified, available for expanding these fields or adding other flags (like store and/or integrations)

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, default (clean) variant, arm64

===== <code>12MMMPPpVA</code> =====
Basically the same thing, just shifted to the right by eating up the unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 clean arm64, as above.

===== <code>12MMPPpxVA</code> =====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 clean arm64, as above.

Android

2025-10-01T09:18:52Z

Soliton: /* Version Code scheme (1.19.16) */

Android

2025-10-01T09:16:40Z

Soliton: /* Version Code scheme (1.19.16) */

Android

2025-10-01T09:15:53Z

Soliton: /* Version Code scheme (1.19.16) */

UsefulLinks

2025-09-22T12:31:27Z

Soliton: /* Battle for Wesnoth */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|Roadmap || https://wiki.wesnoth.org/1.19_Roadmap
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

AddonServers

2025-09-17T11:42:30Z

Soliton:

To connect to the default Add-on server from inside Wesnoth, use the <code>Add-ons</code> option from the title screen.

Alternatively, there is a website generated from the Add-on server contents here: [https://addons.wesnoth.org addons.wesnoth.org]. The web page is for reference purposes, archival purposes, and for people who cannot use the game client for technical reasons or otherwise. You may have a look at the list of add-ons available from each one and optionally download their contents from there. The recommended way is to install via the in-game client.

Also, from the in-game client, it is possible to connect to another version's Add-on server by using the correct port number like this: <code>addons.wesnoth.org:15018</code>. The last two digits of the port specified (<code>15018</code>) are the same as the minor number (<code><major>.<minor>.<patch></code>) of the Wesnoth version whose Add-on server you wish to connect to. In this example, it will connect to the Add-on server of version 1.18.x. Note that this is in general not recommended because add-ons from another version may not be compatible or refuse to correctly work, and is intended for advanced users or for development purposes only. The port scheme may change at any point in the future and is not recommended to be used as a permanent link. The port for the latest development server (trunk/master) is 15004.

InterfaceActionsWML

2025-09-01T11:21:52Z

Soliton: /* [label] */

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

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

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

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

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}} whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}} same as the '''image''' attribute, but the image is displayed on the right of the message text. {{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 putting the mouse over 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]]

UnitTypeWML

2025-08-22T16:04:41Z

Soliton: /* Unit Type */

{{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 an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units 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. If the image width or height is equal or above 300 the engine will scale the image with a factor between 1/2 and 1. 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]]

UnitTypeWML

2025-08-22T16:00:02Z

Soliton: /* Unit Type */ clarify portrait scaling

{{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 an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units 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. If the image width or height is below 300 the engine will scale the image with a factor between 1/2 and 1. 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]]

UsefulLinks

2025-08-07T09:21:00Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
| Github CI || https://github.com/wesnoth/wesnoth/actions
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2025-08-07T09:09:32Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Jenkins CI || https://jenkins.wesnoth.org:8443/
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2025-08-07T09:08:36Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-
|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2025-08-07T09:07:28Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-|Git web interface || https://github.com/wesnoth/wesnoth ([https://git-scm.com/ git] [https://git-scm.com/documentation doc])
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

DebugMode

2025-07-30T16:19:42Z

Soliton: /* Debug Mode */ debug mode is not disabled in network games since a while

== Debug Mode ==

Running the game with commandline option ''--debug'' or ''-d''
enables '''debug mode''' within the game.

Debug mode displays additional information. It also enables
context menu options to create units anywhere on the map, changing unit sides, and some additional [[CommandMode]] commands. If you create units in debug mode, you can then use the :unit command to set the unit's attributes (see [[CommandMode]]).

Debug mode can also be enabled within the game using :debug (see [[CommandMode]]), and on Mac versions of the game, by holding down the Option key when starting Wesnoth.

== Building the game with extra debugging ==

The game can be built to support debugging, enabling a few code snippets for the benefit of external debuggers like ''gdb'', and disabling compiler optimizations.

It is a good idea to run a debug build of the game if you do development, since it can be necessary to diagnose serious problems.

'''scons:'''

scons build=debug [...]

'''cmake:'''

cmake -DCMAKE_BUILD_TYPE=Debug [...] <path to top source dir>
make

An unstripped debug build on linux is over 400 MB, compared to around 16 MB stripped. You probably don't want to strip a debugging build, though, since the extra symbols are required by debug tools.

== See Also ==

* [[CommandMode]]
* [[DebuggingWesnoth]]
* [[DeveloperResources]]

[[Category:Building and Installing]]
[[Category:Development]]

AbilitiesWML

2025-07-29T15:53:47Z

Soliton: /* The [specials] tag */

{{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]''': 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
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]'''
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage 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]]

UsefulLinks

2025-07-28T09:49:36Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-|Git web interface || https://github.com/wesnoth/wesnoth
|-
|Git homepage || https://git-scm.com/
|-
|Git documentation || https://git-scm.com/documentation
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || [https://groups.io/g/wesnoth-packagers wesnoth-packagers] - [https://groups.io/g/wesnoth-translations wesnoth-translations] ([https://listengine.tuxfamily.org/wesnoth.org/ old] - [https://mailman.wesnoth.org/ oldold])
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2025-07-28T09:45:01Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-|Git web interface || https://github.com/wesnoth/wesnoth
|-
|Git homepage || https://git-scm.com/
|-
|Git documentation || https://git-scm.com/documentation
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || https://groups.io/g/wesnoth-packagers 
https://groups.io/g/wesnoth-translations 
old: https://listengine.tuxfamily.org/wesnoth.org/ 
oldold: https://mailman.wesnoth.org/
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

UsefulLinks

2025-07-28T09:42:31Z

Soliton: /* Developers */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-|Git web interface || https://github.com/wesnoth/wesnoth
|-
|Git homepage || https://git-scm.com/
|-
|Git documentation || https://git-scm.com/documentation
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || https://groups.io/g/wesnoth-packagers - https://groups.io/g/wesnoth-translations 
(old: https://listengine.tuxfamily.org/wesnoth.org/ - oldold: https://mailman.wesnoth.org/)
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

LuaAPI/wesnoth/interface

2025-07-03T16:13:29Z

Soliton: /* wesnoth.interface.float_label */

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

{{DevFeature1.15|0}}

The entire interface module is only available in the game. It is not available to plugins or map generators.

== Interface functions ==

=== wesnoth.interface.delay ===

* {{LuaGameOnly}} '''wesnoth.interface.delay'''(''milliseconds'')

Delays the engine for a period of time, specified in milliseconds.

<syntaxhighlight lang=lua>
wesnoth.interface.delay(500)
</syntaxhighlight>

=== wesnoth.interface.deselect_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.deselect_hex'''()

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

=== wesnoth.interface.highlight_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.highlight_hex'''(''x'', ''y'')

Draws an outline around the specified hex.

=== wesnoth.interface.select_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.select_unit'''(''x'', ''y'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} '''wesnoth.units.select'''(''unit'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} ''unit'':'''select'''([''show_movement'', [''fire_events'']])

Selects the given unit in the game map as if the player had clicked on it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false).

This function is available under two different names, but the possible arguments are the same in both cases. In other words, '''wesnoth.units.select''' can be called with a location instead of a unit, and '''wesnoth.interface.select_unit''' can be called with a unit instead of a location.

<syntaxhighlight lang=lua>
wesnoth.interface.select_unit(14, 6, true, true)
</syntaxhighlight>

If called without arguments, this function deselects the current unit from the map as long as the mouse cursor is not on its hex. It will continue to be displayed on the UI sidebar in any case.

=== wesnoth.interface.float_label ===

* {{LuaGameOnly}} '''wesnoth.interface.float_label'''(''x'', ''y'', ''text'')

Adds a floating label above a map tile. The text will float upwards at 100 pixels per second.

<syntaxhighlight lang=lua>
wesnoth.interface.float_label(unit.x, unit.y, "Ouch")
</syntaxhighlight>

=== wesnoth.interface.get_displayed_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.get_displayed_unit'''() → ''unit''
* {{LuaGameOnly}} '''wesnoth.units.get_hovered'''() → ''unit''

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

<syntaxhighlight lang=lua>
local name = tostring(wesnoth.interface.get_displayed_unit().name)
</syntaxhighlight>

=== wesnoth.interface.get_hovered_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_hovered_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently hovered tile, that is, where the mouse cursor is located. This is mostly useful for defining command-mode helpers.

=== wesnoth.interface.get_selected_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_selected_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently selected (highlighted) tile. This is mostly useful for defining command-mode helpers.

<syntaxhighlight lang=lua>
function chg_unit(attr, val)
local x, y = wesnoth.interface.get_selected_hex()
if not x then wesnoth.message("Error", "No unit selected."); return end
wesnoth.units.modify({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)
</syntaxhighlight>

=== wesnoth.interface.get_viewing_side ===

* {{LuaGameOnly}} '''wesnoth.interface.get_viewing_side'''() → ''side'', ''full_vision''

Returns the viewing side of the current client in a multiplayer game.

For a player participating in the game, this will always be the side that they control, or, if they control multiple sides, the one they most recently had control over. However, for an observer client, this will return the currently-active side instead.

The second return value indicates whether the current client has full vision. This can only happen in replays or for observers.

For obvious reasons, use of this function can easily cause out-of-sync errors. Use with care.

=== wesnoth.interface.lock===

* {{LuaGameOnly}} '''wesnoth.interface.lock'''(''lock'')

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

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_hex still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

<syntaxhighlight lang=lua>
wesnoth.interface.lock_view(true)
wesnoth.interface.scroll_to_hex(12, 14, false, true)
</syntaxhighlight>

=== wesnoth.interface.is_locked ===

* {{LuaGameOnly}} '''wesnoth.interface.is_locked'''() → ''locked?''

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

=== wesnoth.interface.scroll_to_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll_to_hex'''(''x'', ''y'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} '''wesnoth.units.scroll_to'''(''unit'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} ''unit'':'''scroll_to'''([''only_if_visible'', [''instant'', [''only_if_needed'']]])

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen. It is also possible to pass a unit instead of a pair of tile coordinates (regardless of which module the function is called from).

<syntaxhighlight lang=lua>
local u = wesnoth.units.get "hero"
u:scroll_to()
</syntaxhighlight>

=== wesnoth.interface.scroll ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll'''(''dx'', ''dy'')

Scrolls the map by the given amount, which may be either positive or negative.

=== wesnoth.interface.zoom ===

* {{LuaGameOnly}} '''wesnoth.interface.zoom'''(''factor'', [''relative'']) → ''new_zoom''

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

This function also returns the resulting zoom level. Because of this, you can call
<syntaxhighlight lang=lua inline>wesnoth.zoom(1, true)</syntaxhighlight>
to simply get the current zoom level.

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

=== wesnoth.interface.skip_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.skip_messages'''([''skip?''])

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

=== wesnoth.interface.is_skipping_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.is_skipping_messages'''()

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

=== wesnoth.interface.add_chat_message ===

* {{LuaGameOnly}} '''wesnoth.interface.add_chat_message'''([''speaker'',] ''message'')

Displays a string in the onscreen chat. The chat line speaker is "Lua" by default, but it can be changed by passing a string before the message.

<syntaxhighlight lang=lua>
wesnoth.interface.add_chat_message "Hello World!" -- will result in "<Lua> Hello World!"
wesnoth.interface.add_chat_message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."
</syntaxhighlight>

See also [[LuaAPI/wml#wml.error|wml.error]] for displaying error messages.

=== wesnoth.interface.clear_chat_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.clear_chat_messages'''()

Removes all messages from the onscreen chat, including error messages.

=== wesnoth.interface.add_item_image ===

* {{LuaGameOnly}} '''wesnoth.interface.add_item_image'''(''location'', ''filename'')

Places an image at a given location and registers it as a WML ''[item]'' would do, so that it can be restored after save/load. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.add_item_image(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.add_item_halo ===

* {{LuaGameOnly}} '''wesnoth.interface.add_item_halo'''(''location'', ''filename'')

Behaves the same as [[#wesnoth.interface.add_item_image]] but for halos.

=== wesnoth.interface.remove_item ===

* {{LuaGameOnly}} '''wesnoth.interface.remove_item'''(''location'', [''filename''])

Removes an overlay set by [[#wesnoth.interface.add_item_image]] or [[#wesnoth.interface.add_item_halo]]. If no filename is provided, all the overlays on a given tile are removed. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_item(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.get_items ===

* {{LuaGameOnly}} '''wesnoth.interface.get_items'''(''location'') → ''array of item tables''

Get all items placed on the specified location. Note that the location must be passed as separate x and y coordinates.

=== wesnoth.interface.add_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.interface.add_hex_overlay'''(''location'', ''item_wml'')

Places a hex overlay (either an image or a halo) on the given location. The overlay is described by a table supporting the same fields as [[InterfaceActionsWML|[item]]]. This is a lower-level version of the item functions above. Note that the overlay is not kept over save/load cycles.

<syntaxhighlight lang=lua>
wesnoth.interface.add_hex_overlay(17, 42, { image = "items/orcish-flag.png" })
</syntaxhighlight>

=== wesnoth.interface.remove_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.interface.remove_hex_overlay'''(''location'', [''filename''])

Removes all the overlays at the given location, including any added by '''wesnoth.interface.add_item_halo''' or '''wesnoth.interface.add_item_image''' (however, such a removal will not be kept over save/load cycles). If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_hex_overlay(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.end_turn'''([''next_side''])

Immediately ends the current side's turn. By default, the next sequential side will gain control, but if you pass an argument that side gains control instead.

The ''next_side'' can either be a valid side number, or a valid side number plus the total number of sides in the scenario. In the latter case, this function also increases the turn counter by 1.

Using this, it's entirely possible to pass control around without ever increasing the turn counter.

=== wesnoth.interface.allow_end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''allow'')
* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''reason'')

Enables or disables ending the turn in the UI. You can optionally pass a translatable string to show to the player if they attempt to do so anyway. It will be shown to the player without any additional framing, so it should normally be phrased similar to "You cannot end your turn because...".

To allow the player to end their turn again, just pass '''true'''. If you pass '''false''', a default message will be shown.

=== wesnoth.interface.color_adjust ===

* {{LuaGameOnly}} '''wesnoth.interface.color_adjust'''(''red'', ''green'', ''blue'')

Adjust the screen tint. (0,0,0) is no tint, and possible values range from -255 to 255.

=== wesnoth.interface.add_overlay_text ===

{{DevFeature1.17|3}}

* {{LuaGameOnly}} '''wesnoth.interface.add_overlay_text'''(''text'' [, ''options'']) → ''text handle''

Adds a text overlay to the screen that does not move with the map. [[Pango formatting]] is supported. The ''options'' table supports the following keys:

* ''size'' - The font size.
* ''max_width'' - Sets the maximum width the text can occupy on the screen, either in screen units (pixels) or as a percentage (a string ending in <tt>%</tt>). If the text is too long to fit in that width, it will automatically be word-wrapped. Defaults to 100%.
* ''color'' - The text color, either as a six-digit hex string (no leading <tt>#</tt>) or an array of three integers (red, green, and blue).
* ''bgcolor'' - If present, a background in this color is placed behind the text to enhance readability. This works like the background behind chat messages, but can be any colour. It is formatted the same as ''color''. If omitted, the background is fully transparent (ie, there is no background).
* ''bgalpha'' - If a background colour is specified, this sets its transparency. The default is fully opaque.
* ''duration'' - How long the text should be displayed, in milliseconds, or the string <syntaxhighlight lang=lua inline>'unlimited'</syntaxhighlight> for an infinite duration. Defaults to two seconds.
* ''fade_time'' - When the label is removed, either explicitly or because its duration expired, this is the time it takes to fade out, in milliseconds. A value of 0 means the label disappears instantly. Defaults to 100.
* ''halign'' - Where to anchor the text horizontally on the screen. Must be one of <syntaxhighlight lang=lua inline>'left', 'center', 'right'</syntaxhighlight>.
* ''valign'' - Where to anchor the text vertically on the screen. Must be one of <syntaxhighlight lang=lua inline>'top', 'center', 'bottom'</syntaxhighlight>.
* ''location'' - The screen offset where the text should be placed, relative to the specified anchor. Defaults to (0,0).

The text handle returned from this function supports the following method calls:

* ''handle'':'''move'''(''x'', ''y'')

Moves the text to a new location on the screen. The provided ''x'' and ''y'' are offsets from its current location.

* ''handle'':'''remove'''([''fade_time''])

Remove the text from the screen, optionally overriding the fade-out time.

* ''handle'':'''replace'''(''text'', ''options'') → ''handle''

Replaces the text with new text. Options are the same as in ''add_overlay_text'', and the returned handle is the same one.

=== wesnoth.interface.handle_user_interact ===

{{DevFeature1.17|6}}

* {{LuaGameOnly}} '''wesnoth.interface.handle_user_interact'''()

Handle user interaction with the game interface. This can be inserted into Lua code that takes a long time to execute in order to prevent the user interface from freezing.

== wesnoth.interface.game_display ==

* {{LuaGameOnly}} '''wesnoth.interface.game_display'''.''theme_item'' ↔ '''function'''() → ''wml table of theme elements''

This is an associative table linking item names to functions that describe the content of the in-game user interface. These functions are called with no arguments whenever the user interface is refreshed, and must return a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a '''help''' field that points to the help section that is displayed when the user clicks on the theme item.

Note that the '''wesnoth.interface.game_display''' cannot be iterated using '''pairs''' or '''next''' to retrieve the items from the current theme. However, built-in items ''can'' be recovered as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

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

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

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

The following is a list of valid entries in '''wesnoth.interface.game_display''' which will have an effect in the game, together with sample output and a brief description of their use.

=== unit_name ===

Shows the name of the unit the mouse is hovering over.

=== unit_type ===

Shows the type of the unit the mouse is hovering over.

=== unit_race ===

Shows the race of the unit the mouse is hovering over.

=== unit_side ===

Shows the side number and team color of the unit the mouse is hovering over.

=== unit_level ===

Shows the level of the unit the mouse is hovering over.

=== unit_amla ===

Similar to unit_advancement_options but shows AMLAs only.

=== unit_traits ===

Shows the list of trait names for the unit the mouse is hovering over.

=== unit_status ===

Shows the status icons for statuses afflicting the unit the mouse is hovering over.

=== unit_alignment ===

Shows the alignment of the unit the mouse is hovering over.

=== unit_abilities ===

Shows the ability names of the unit the mouse is hovering over.

=== unit_hp ===

Shows the current and maximum hit points of the unit the mouse is hovering over.

=== unit_xp ===

Shows the current and target experience points of the unit the mouse is hovering over.

=== unit_advancement_options ===

Shows the options the unit the mouse is hovering over has for advancement, including both level ups and AMLAs. This item is not used in the default theme.

=== unit_defense ===

Shows the defense of the unit the mouse is hovering over.

=== unit_vision ===

Shows the current and maximum vision points of the unit the mouse is hovering over.

=== unit_moves ===

Shows the current and maximum movement points of the unit the mouse is hovering over.

=== unit_weapons ===

Shows the available weapons of the unit the mouse is hovering over. The default generator expresses each weapon line (basic details, specials, etc) as a separate <code>element</code>. For example:

<syntaxhighlight lang=wml>
[element]
image="melee.png"
tooltip="...stuff..."
[/element]
[element]
image="arcane.png"
tooltip="...stuff..."
[/element]
[element]
text="6×3 holy sword"
tooltip="...stuff..."
[/element]
[element]
# This is empty if the range and type icons both exist.
text="melee-arcane"
tooltip="...stuff..."
[/element]
# If the weapon has accuracy or parry...
[element]
text="+20%/-10%"
tooltip="Accuracy: +20%
Parry: -10%
"
[/element]
# If the weapon has special abilities...
[element]
text="magical"
tooltip="...stuff..."
[/element]
</syntaxhighlight>

=== unit_image ===

Shows the sprite of the unit the mouse is hovering over.

=== unit_profile ===

Shows the portrait of the unit the mouse is hovering over.

=== selected_unit ===

Nearly every item beginning with '''unit_''' has a corresponding item beginning with '''selected_unit_''', which describes the currently-selected unit (if any) rather than the unit the mouse is hovering over. These items are not used in the default theme.

There is no '''selected_unit_amla''' however.

=== highlighted_unit_weapons ===

This is almost the same as '''selected_unit_weapons''' but with slightly different logic of choosing which unit to show.

=== tod_stats and selected_tod_stats ===

Shows the time of day stats for the hex the mouse is hovering over or the hex the selected unit is on. The time of day stats shows the counter of your position in the schedule as well as the entire cycle.

=== time_of_day and selected_time_of_day ===

Shows the time of day image for the hex the mouse is hovering over or the hex the selected unit is on.

=== unit_box ===

This is an experimental item that combines a unit display and the time of day.

=== turn ===

Shows the current turn count.

=== gold ===

Shows the amount of gold for the active side.

=== villages ===

Shows the number of villages owned by the active side.

=== num_units ===

Shows the number of units owned by the active side.

=== upkeep ===

Shows the upkeep and expenses for the active side.

=== income ===

Shows the income for the active side

=== terrain_info ===

Shows the icons of the terrain on hex the mouse is hovering over.

=== terrain  ===



Shows the name of the terrain on the hex the mouse is hovering over. For example:

<syntaxhighlight lang=wml>
[element]
text="Grassland (Flat)"
[/element]
</syntaxhighlight>

=== position ===

Shows the map coordinates of the hex the mouse is hovering over.

=== zoom_level ===

Shows the zoom level as a percentage. This item is not used in the default theme.

=== side_playing ===

Shows the active side's flag.

=== observers ===

When there is no observer, it returns an empty table. When there are observers, it returns:

<syntaxhighlight lang=wml>
[element]
tooltip="Observers
<observer1>
<observer2>
"
image="misc/eye.png"
[/element]
</syntaxhighlight>

=== report_clock ===

This returns the current time in HH:MM format according to the user's preferences, for example:

<syntaxhighlight lang=wml>
[element]
text="22:32"
[/element]
</syntaxhighlight>

=== report_countdown ===

This returns the current chess-timer countdown in MM:SS format for the player's turn, for example:

<syntaxhighlight lang=wml>
[element]
text="12:43"
[/element]
</syntaxhighlight>

Depending on the time limit, the text may also be colored using [[Pango formatting|Pango markup]].

If there is no time limit set then it forwards to [[#wesnoth.interface.game_display.report_clock|report_clock]].

[[Category:Lua Reference]]

InterfaceActionsWML

2025-07-02T12:10:08Z

Soliton: /* [item] */

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

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

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

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

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}} whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}} same as the '''image''' attribute, but the image is displayed on the right of the message text. {{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 #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]]

InterfaceActionsWML

2025-07-02T12:09:22Z

Soliton: /* [item] */ fix external links

{{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 #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]]

InterfaceActionsWML

2025-07-02T12:02:09Z

Soliton: /* [item] */ move example where it belongs

{{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). ''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]]

InterfaceActionsWML

2025-07-02T11:57:47Z

Soliton: /* [item] */ document submerge and z_order

{{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.
* '''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]]

GameConfigWML

2025-06-27T14:34:48Z

Soliton: /* The [game_config] tag */

{{WML Tags}}
== The [game_config] tag ==

This tag is a top level WML tag which can only be used once because
it defines basic settings that are used everywhere in the game.
In official versions of Wesnoth it is in ''game_config.cfg''; values used there are labeled 'standard'.

{{Note|This page is very outdated, and will take multiple edits to update.}}

The following keys are recognised
* '''base_income''': (standard 2) how much your leader earns without any villages
* '''village_income''': (standard 1) how much your leader earns for each village you control
* '''village_support''': (standard 1) how many unit levels a village supports
* '''poison_amount''': (standard 8) the amount of damage poison deals to a unit
* '''rest_heal_amount''': (standard 2) how much HP a unit gains each turn it rests
* '''recall_cost''': (standard 20) how much it costs to recall a unit; this cost is independent of level.
* '''kill_experience''': (standard 8) killing a unit with ''level=X'' will give ''X''*''kill_experience'' experience to the killing unit. However, if a unit has ''level=0'', it will still give half of ''X'' experience.

* '''default_defeat_music''': (standard 'defeat.ogg,defeat2.ogg') default list of music tracks that are chosen to play on player's defeat; this can be overriden per-scenario
* '''default_victory_music''': (standard 'victory.ogg,victory2.ogg') default list of music tracks that are chosen to play on player's victory; this can be overriden per-scenario
* '''title_music''': (standard 'main_menu.ogg') the music to play at the title screen

* '''energy''': (standard 'misc/bar-energy.png') the images used to display hp/xp bars.
* '''orb''': (standard 'misc/orb.png') the orb image to add on top of the hp bar, this is recolorable to show the status; see 'Orbs', [[WesnothManual]]
* '''orb_two_color''': (standard 'misc/orb-two-color.png') like '''orb''', but has two separate recolorable parts. Note this is the image to use, although the colors to use for recoloring it also have names that end '_color'.
* '''show_moved_orb''', '''show_partial_orb''', '''show_unmoved_orb''': (default to 'yes' when omitted from the .cfg) whether to show the orb for the player's own units when they're in the given state
* '''show_disengaged_orb''': (defaults to 'yes' when omitted from the .cfg) whether to show a special orb instead of the "partial" orb when a unit can move but can't attack
* '''show_ally_orb''': (defaults to 'yes' when omitted from the .cfg) whether to show an orb on allied units
* '''show_enemy_orb''': (defaults to '' 'no' '' when omitted from the .cfg) whether to show an orb on opposing units
* '''show_status_on_ally_orb''': (defaults to 'yes' when omitted from the .cfg) if true, during allies' turns their units have orbs that show the unmoved/partial/moved status. If true, overrides 'show_ally_orb' during that ally's turn.
* '''ally_orb_color''': (standard 'lightblue') target for recoloring the ally orb
* '''enemy_orb_color''': (standard 'black') target for recoloring the enemy orb, although by default this orb is not shown
* '''moved_orb_color''': (standard 'red') target for recoloring the moved orb
* '''partial_orb_color''': (standard 'brightorange') target for recoloring the partially-moved orb, also used for half of the disengaged orb
* '''unmoved_orb_color''': (standard 'brightgreen') target for recoloring the fully-moved orb, also used for half of the disengaged orb

* '''flag_image''': (standard 'image/flag'terrain/flag-1.png:150,terrain/flag-2.png:150,terrain/flag-3.png:150,terrain/flag-4.png:150') the default flag animation to mark captured villages (if no custom flag is defined in the [side] tag). By example, this animation has 4 frames of 150ms each. An automatic side-coloring is applied.
* '''flag_icon_image''': (standard 'flags/flag-icon.png') the default flag icon to indicate the side playing in the statusbar (if no custom flag_icon is defined in the [side] tag). An automatic side-coloring is applied.
* ''' hp_bar_scaling ''': (standard '0.6') The ratio of hitpoints to height used for displaying the hp bar. Can be overwritten in [unit] and [unit_type].
* ''' xp_bar_scaling ''': (standard '0.5') The ratio of xp to height used for displaying the xp bar. Can be overwritten in [unit] and [unit_type].

* '''footprint_left_nw''', '''footprint_left_n''', '''footprint_right_nw''', '''footprint_right_n''': images used to display the path that a unit would take to the tile the cursor is on.
The first image of each key is used for tiles which would take only 1 movement point for the selected unit to move onto;
the second for ones which would take more.
The 'n' and 'nw' designations distinguish between tiles which are moved from orthogonally and diagonally in the same way as described in '''[missile_frame]''', [[AnimationWML]].
The 'left' and 'right' designations are used alternately throughout the path;
however, the standard values are the same for 'left' and 'right'.

* '''terrain_mask_image''': (standard 'terrain/alphamask.png') used to give a hex-shape from a rectangular image.
* '''grid_image''': (standard 'terrain/grid.png') the image used by the grid option
* '''unreachable_image''': (standard 'terrain/darken.png') the stripes mask used to show unreachable locations

* '''observer_image''': (standard 'misc/eye.png') the image to use for observer in multi-player games. (The eye in the upper right hand corner.)
* '''zoom_levels''': {{DevFeature1.13|8}} A comma-separated list of valid zoom levels, with 1.0 representing 100%.

== Color Palettes ==

Color palettes are defined by two tags within '''[game_config]'''. These tags also work in a couple of other places (https://github.com/wesnoth/wesnoth/issues/8555) like the top level.

* '''[color_palette]''': Contains the definitions of source palettes, such as magenta. Each key defines a palette, and must be set to a comma-separated list of hexadecimal colors.
* '''[color_range]''': Defines a target color palette.
** '''id''': Used to reference the palette, for example from '''[side]''' or ~RC().
** '''name''': A translatable name for the color. <s>This may be ignored for non-core colors?</s>
** '''rgb''': A comma-separated sequence of four hexadecimal colors:
**# the average shade of a unit's team-color portions
**# the maximum highlight shade of a unit's team-color portions
**# the minimum shadow shade of a unit's team-color portions
**# the color of the markers on the mini-map.
** '''default''': (only under '''[game_config]''') if yes this color is added to the colors that get assigned to sides by default in the order they appear (side 1 gets the first color with default=yes (red) etc)

== See Also ==

* [[ReferenceWML]]

[[Category: WML Reference]]

Template:WML Tags

2025-06-27T12:20:34Z

Soliton: remove duplicate

{| 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]],
[[SavefileWML|menu_item]],
[[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]],
[[SavefileWML|replay_start]],
[[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:''
[[SavefileWML|save]],
[[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]],
[[SavefileWML|snapshot]],
[[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>

SideWML

2025-06-27T08:16:04Z

Soliton: /* Common Keys */

{{WML Tags}}

The term "side" refers to a single player in the Wesnoth turn order, which can be controlled by either a human or an AI. Every [[ScenarioWML|scenario]] must have at least one side. There is no hard limit on the number of sides a single scenario can have.

Usually the number of sides in a scenario is fixed. However, the Lua function [[LuaAPI/wesnoth/sides#wesnoth.sides.create|wesnoth.sides.create]] can be used to dynamically add new sides if required.

Sides in a scenario are described by the '''[side]''' tag, which recognizes the following keys and tags.

== Common Keys ==

These keys are always permitted in a '''[side]''' tag.

* '''side''': a number. The leader of this side is placed on the tile represented by this number (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far. Currently, the Multiplayer server rejects entering a scenario with more than 9 sides, even if those extra sides are AI sides. {{DevFeature1.13|2}} The server doesn't limit the number of sides anymore.

* {{anchor|controller|'''controller'''}} (required): how moves for this side should be inputted.
** '''ai''': the Wesnoth AI makes this side's moves.
** '''human''': a player controls this side's moves.
** '''null''': the side doesn't get a turn to move. Events that would usually occur on the side's turn will not take place. This includes healing (ability, villages and rest) and ''side turn'' events.
** '''a number''': gives this side's control to a side with '''side''' matching the number (multiplayer only). {{DevFeature1.13|2}} using a number is deprecated, use previous_save_id= instead.
** Note: in multiplayer, when reading the side's data with ''[store_side]'', the value may differ between clients and using it for conditional actions may cause OOS. Discussion in https://r.wesnoth.org/p643343

* '''type''': if present, the keys describing a unit (including '''type''') which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using ''canrecruit=yes'') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are ''id'', ''name'' and ''unrenamable=yes'', see [[SingleUnitWML]]. The unit will automatically be set to be able to recruit.

* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units. Units in the side recruit list can always be recruited by a leader on this side, in addition to any units in the individual leader's '''extra_recruit''' list. {{DevFeature1.13|?}} in multiplayer, unless you specify ''faction=Custom'', this will be overwritten by the recruit list from the faction.

* '''gold''': the starting gold for this side. Default: 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

* '''income''': additional income for this side. Default: 0. This is added to '''[[GameConfigWML|[game_config]]]'''''base_income'' to determine the side's base income.

* '''hidden''': if 'yes', side is not shown in status table.

* '''fog''': if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

* '''fog_data''': describes the area which this team has de-fogged, using the same format as shroud_data. (This is not particularly useful when defining a side, though, as the game will recalculate fog as turns begin and end.) It is used in saved games.

* {{anchor|fog_override|'''[fog_override]'''}}: With keys x= and y=, this records the hexes that have been cleared (multiturn) with {{tag|DirectActionsWML|lift_fog}}.

* '''shroud''': if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud. NOTE: with shroud=no, this team *ignores* shroud, so it is not possible to modify it using place_shroud and remove_shroud tags. If you want to do so, use "shroud=yes" and place_shroud/remove_shroud tags.

* '''shroud_data''': describes the area which this team has de-shrouded. An example:
|
|00011111000
:This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[ShroudDataWML]].

* '''persistent''': whether the side exists in any other scenarios. If 'yes', then ''save_id'' (see below) is used to identify the side in other scenarios. Defaults to 'yes' for sides with a human controller, and 'no' for ai controlled sides.

* '''save_id''': defaults to the leader's ''id'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog.

* '''previous_save_id''': {{DevFeature1.13|2}} defaults to ''save_id''. Only used in mp games, specially mp campaigns. This attribute specifies which user should play this side by default. For example if a side has previous_save_id="Konrad" then the side will be assigned to that player who played the side with the save_id="Konrad" in the previous level. If used in the first scenario, multiple sides with the same ''previous_save_id'' will be assigned to the same player.

* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''. ''team_name'' is now a comma-separated list of teams that the side is on.

* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.

* '''current_player''': a translatable string representing the player's or leader's name. Defaults to the leader's id; if the side's leader is a human player in multiplayer, the default is the player's username. {{DevFeature1.13|0}} This field is now always the player name (mp server nick) it impossible to change it with wml/lua. {{DevFeature1.13|5}} You can use ''side_name'' instead to specify the name for the side (which is then used in new turn dialogs, statisitc dialogs etc.)

* '''side_name''': {{DevFeature1.13|5}} a translatable string representing the name of the side, used for example in the new turn dialog. Defaults to ''name'' if the side was inside a '''[scenario]''' and to the player's name if the side was inside a '''[multiplayer]'''.

* '''color''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colors can be found in data/core/team_colors.cfg. Can also be an inline color range (the rgb key from [[GameConfigWML#Color_Palettes]]).

* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-[1~3].png:750''

* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]).

* '''village_support''': the number of unit levels this side is able to support (does not pay upkeep on) per village it controls. Default specified in ''village_support'', '''[game_config]''' ([[GameConfigWML]]).

* '''recall_cost''': the amount of gold it costs to recall a unit. Default specified in ''recall_cost'', '''[game_config]''' ([[GameConfigWML]]). {{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.

* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud. {{DevFeature1.13|1}} This has been deprecated in favor of share_vision (see below).

* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog). {{DevFeature1.13|1}} This has been deprecated in favor of share_vision (see below).

* '''share_vision''': {{DevFeature1.13|1}} all/shroud/none. If ''all'', both shroud and fog view will be shared by this side. If ''shroud'', only shroud view will be shared. If ''none'', the view is not shared.

* '''scroll_to_leader''': optional. If 'no', scroll to the leader is not performed on the start of each turn. (default: yes)

* '''suppress_end_turn_confirmation''': If "yes", then the player will not be asked to confirm ending their turn even if they have not done anything. This is provided for some (probably few) user-made scenarios in which players often skip their turns. (default: no)

* {{anchor|ai|'''[ai]'''}}: if '''controller=ai''', gives parameters to the AI. See [[AiWML]].

* {{anchor|village|'''[village]'''}}: describes a village the side begins in control of.
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another '''[village]''' tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

* {{anchor|unit|'''[unit]'''}}: describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.

* {{anchor|leader|'''[leader]'''}}: describes the leader for the side, basically same as '''[unit]''' except that ''canrecruit'' will default to yes and current position to the side starting location if not specified. {{DevFeature1.17|17}} Furthermore, if left out, the '''name''' and '''save_id''' attributes in '''[side]''' will be set to the '''name''' and '''id''' attributes in the first '''[leader]''' tag.

* {{anchor|variables|'''[variables]'''}}: {{DevFeature1.19|8}} Can be used to define side variables. When you use :inspect to see the variables, they will be listed under ''team''. This tag can also be placed in '''[unit]''' and '''[leader]''', where it will create variables as part of this unit. See [[VariablesWML#The_.5Bvariables.5D_tag|here]] for more info.

* {{anchor|defeat_condition|'''defeat_condition'''}}: Specifies when a side is considered ''defeated'' this is checked ''for all sides'', after every player action and at the beginning of every turn.
** '''no_leader_left''': (default) The side is considered defeated if it has no units with canrecruit=yes
** '''no_units_left''': The side is defeated as soon as it has no units left.
** '''never''': The side is never considered defeated.
** '''always''': The side is always considered defeated.

: For the meaning and significance of ''defeated'', see [[ScenarioWML#Scenario_End_Conditions]]

== Multiplayer Keys ==

These keys are only permitted in a '''[side]''' tag for a '''[multiplayer]''' scenario.

* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation. False also prevents this side from being included in shuffle sides. Defaults to yes.

* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)

* '''disallow_shuffle''': {{DevFeature1.13|0}} do not shuffle this side if the "shuffle sides" option is used. (Usually all playable sides are shuffled.) (default: no)

* '''chose_random''': {{DevFeature1.13|0}} indicates if a side chose a random faction during creation

* '''controller_lock''': if true then this side's controller ("Player/Type") modification is limited. It is bound to the '''controller''' attribute in [[SideWML]].

* '''team_lock''': if true then this side's team is not allowed to be modified.

* '''color_lock''': if true then this side's color is not allowed to be modified.

* '''gold_lock''': if true then this side's gold is not allowed to be modified.

* '''income_lock''': if true then this side's income is not allowed to be modified.

* '''faction_lock''': if true then this side's faction is not allowed to be modified.

* '''no_leader''': if 'yes', prevents the engine from generating a leader from the multiplayer faction, basically an alias of '''leader_lock'''

* '''leader_lock''': if true then this side's leader (type or gender) is not allowed to be modified. Note that if ''type='' key is missing, ''leader_lock=yes'' means the side will have no leader.

* '''faction''': if a valid faction id is provided then this side's faction will default to it in the game setup screen. {{DevFeature1.13|?}} if this key isn't included in the ''[side]'' then a random faction will be chosen, and the side's recruit list set from the faction. To use a custom ''recruit'' list, you must also specify ''faction=Custom''.

* '''faction_from_recruit''': if true then this side will be locked to the faction that matches the recruits better.

N.B. the ''lock'' attributes use [[ScenarioWML]] '''force_lock_settings''' as their default value. I.e. if no value to ''lock'' was set, it will take '''force_lock_settings''' value.

== See Also ==
* [[EraWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AbilitiesWML

2025-06-20T20:15:09Z

Soliton: Revert last 3 non-sensical edits

{{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]''': 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]]

StandardLocationFilter

2025-06-17T09:23:12Z

Soliton: /* Attributes */

{{WML Tags}}
From [[FilterWML]], this is the standard way of filtering on locations.
The term [[StandardLocationFilter]] means that the set of such keys and tags (see below) can appear at that point. Sometimes a [[StandardLocationFilter]] needs to be included in a [filter_location] tag. There are however many tags which accept the [[StandardLocationFilter]] directly as an argument such as [store_locations]. Generally, if the tag [filter_location] is not mentioned to be a possible subtag of the outer tag in question, then don't put it.

== Attributes ==
The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, or neutral). Note: ''chaotic'', ''lawful'', and ''neutral''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [[#Filtering_Terrains|Filtering Terrains]]).
* '''x,y''': the same as in the unit filter; supports any range ([[StandardLocationFilter#Notes_about_Coordinate_Usage|notes]])
* '''location_id''': {{DevFeature1.13|?}} Matches a special location set in the map. This can also be a side number to match that side's starting location. Note: this does not accept a comma separated list, one has to use [or] tags. {{DevFeature1.15|0}} Accepts a comma separated list. This key can be set in the map editor or with the [terrain] tag.
* '''area''': matches locations assigned to the [[DirectActionsWML#.5Btime_area.5D|[time_area]]] with the given id.
* '''include_borders''': {{DevFeature1.13|0}} whether the SLF will include border hexes or not. Will override the default behavior of the tag this appears in.
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [[TerrainWML|[terrain_type]]]<nowiki/>gives_income= parameter was set to yes (which means a side can own that hex).
* '''gives_income''': {{DevFeature1.15|11}} Matches whether or not a hex gives income, based on its terrain_type settings.
* {{anchor|filter_vision|'''[filter_vision]'''}}: this tests whether or not the location is currently visible
** '''visible''': yes or no, default yes. "yes" filters for visible locations, "no" filters for invisible locations.
** '''respect_fog''': yes or no, default yes. "yes" filters for locations that are clear of both fog and shroud, "no" filters for locations that are clear of shroud.
** [[StandardSideFilter]] tags and keys as arguments. If there is '''at least one''' matching side which can see the location then the filter matches, and otherwise it fails to match.
* {{anchor|filter_owner|'''[filter_owner]'''}}: If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable. Expects containers to contain '''x''','''y''' pairs, not '''location_id''' names.
* '''radius''': matches if any location within the radius matches this filter ([[StandardLocationFilter#Notes_about_Radius_Usage|notes]])
* {{anchor|filter_radius|'''[filter_radius]'''}}: a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* {{anchor|filter_adjacent_location|'''[filter_adjacent_location]'''}}: a standard location filter; if present the correct number of adjacent locations must match this filter
** '''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 [[#Directions|notes]])
* '''formula''': {{DevFeature1.13|5}} a [[Wesnoth Formula Language]] formula. Some terrain-specific variables, for example "light" and "castle", can be used in the filter [[#Wesnoth_Formula_Language|(see list below)]]. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
* '''lua_function''': {{DevFeature1.13|5}} the name of a [[LuaWML|Lua]] function in the global environment that takes arguments <code>x, y</code> and returns true if the given location matches the filter. 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>.

==Notes about Coordinate Usage==

When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

While some locations should only be one hex (like the starting position of a unit),
others filter over multiple hexes.
The following syntax is used to filter over multiple hexes:

Dashes('''-''') are used to have the location be a range of hexes.
There must be values before and after the dash;
everything in between these numbers (inclusively) is part of the range.

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.
E.g. in order to specify multiple locations 1,4 and 2,5, use:

<syntaxhighlight lang='wml'>
[tag]
x=1,2
y=4,5
[/tag]
</syntaxhighlight>

You should have the same number of commas in each list, and both '''x''' and '''y''' are always lists. For example, this does not mean the locations (1,4) and (2,4):
<syntaxhighlight lang='wml'>
[tag]
x=1,2
y=4 # bad example, implementation-defined behavior
[/tag]
</syntaxhighlight>

A pair can have a single value for one coordinate and a range for the other. This matches (1,4) and the entire column from (2,1) downwards:
<syntaxhighlight lang='wml'>
[tag]
x=1, 2
y=4,1-999
[/tag]
</syntaxhighlight>

Providing only '''x''' or only '''y''' is valid. This matches the entire columns from (1,1) and (2,1) downwards:
<syntaxhighlight lang='wml'>
[tag]
x=1,2
[/tag]
</syntaxhighlight>

Note: although the ordering of locations in a list generally does not matter,
the action '''[move_unit_fake]''' takes in a list of hexes,
and moves an image onto each of those hexes in order.

==Notes about Radius Usage==
If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.

<syntaxhighlight lang='wml'>
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
</syntaxhighlight>

Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:

<syntaxhighlight lang='wml'>
[have_location]
x,y=15,23
radius=5 # oops... this time it won't work as expected
[not]
[filter]
[/filter]
[/not]
[have_location]
</syntaxhighlight>

will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.

== Directions ==

Some attributes expect a direction or list of directions. Valid base directions are n, ne, nw, s, se, sw, and there are three operators supported as well:

* To take the opposite direction, use - (eg -n is the same as s)
* {{DevFeature1.13|2}} To rotate clockwise, use :cw (eg n:cw is the same as ne)
* {{DevFeature1.13|2}} To rotate counterclockwise, use :ccw (eg n:ccw is the same as nw)

You can't apply multiple rotation operators - for example, "n:cw:ccw" is not a valid direction. If for some reason you really need multiple rotations, you can use parentheses (so, "(n:cw):ccw" is valid and is the same as n). Similarly, "--n" is not valid, but "-(-n)" is valid and is the same as n.

This syntax is mainly useful when used in conjunction with variable substitution in the adjacent key in [filter_adjacent_location] and in [filter_adjacent] (in [[StandardUnitFilter]]), but will work anywhere a direction is expected. For example, using [modify_unit] to change a unit's direction:

<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
# ... Whatever filter you need
[/filter]
facing=-$this_unit.facing
[/modify_unit]
</syntaxhighlight>

That will cause the matched units to turn around.

== Filtering Terrains ==

The '''terrain=''' key allows you to filter based on the terrain of a space, for example:

<syntaxhighlight lang='wml'>
[event]
[filter]
[filter_location]
terrain=Ch
[/filter_location]
[/filter]
[/event]
</syntaxhighlight>

At some places the terrains can be filtered with a match list. This list is a comma separated list of [[TerrainCodesWML|terrain strings]] and patterns which will be processed in order. As soon as a pattern matching the reference terrain is found, the result of the filter will be determined.

Normally, if one of the patterns matches, the filter is considered successful. However, the special pattern <tt>!</tt> inverts this every time it is encountered – when inverted, the filter is considered ''unsuccessful'' when one of the patterns matches. In other words, <tt>Gg</tt> matches only basic grass, while <tt>!,Gg</tt> matches ''anything but'' basic grass.

When the end of the list is reached without any matches, normally the result is an unsuccessful match. However, if the match is currently inverted, ie there are an odd number of <tt>!</tt>, then the result is a successful match.

An individual terrain pattern consists of two parts, the base and the overlay, separated by the <tt>^</tt> character. The overlay (including the preceding <tt>^</tt>) is optional; if omitted, only terrains without overlays can be matched. The pattern may end with the wildcard character <tt>*</tt> (or be composed solely of the wildcard character). The pattern to match any terrain is <tt>*^*</tt>.

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

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

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

== Wesnoth Formula Language ==

When using SLF's '''formula''' attribute, the context object is a '''terrain hex object''' with the following properties:

* '''x''', '''y''', '''loc''': the latter is a '''location object''' such as what would be returned by [[Wesnoth_Formula_Language#loc|loc()]].
* '''id'''
* '''name'''
* '''editor_name'''
* '''description'''
* '''icon'''
* '''light'''
* '''village''': a boolean containing the value of [terrain_type]gives_income=
* '''castle'''
* '''keep'''
* '''healing''': an integer containing the value of [terrain_type]heals=
* '''owner_side'''

For an up-to-date list, check the C++ function terrain_callable::get_value(const std::string& key) const.

Some location formulas also have access to a '''teleport_unit''' variable, which is a '''[[StandardUnitFilter#Wesnoth_Formula_Language|unit object]]'''.

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

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

TerrainCodesWML

2025-06-05T15:39:51Z

Soliton: /* Terrain codes in map data */

{{WML Tags}}

Note: the old (1.2) terrain system is no longer documented here. If you have 1.2 maps you will need to convert them using [[Maintenance_tools|wmllint]].

== Terrain strings ==

The following rules hold for terrain strings. Note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.

* terrain strings are composed from one or two terrain codes of 2 to 4 characters (bytes) each, separated by ^.
* terrain codes start with a capital letter and the following letters are lower case
* terrain strings can only contain letters, the symbols /|\ which are meant for directional items like bridges and the symbol ^
* the underscore is used as a leader for internal terrain codes
* the star '*' can be used for wildcards in some places where a terrain code is required for matching
* the symbol ^ indicates that a terrain is created with layers, for example Gs^Fp means Semi-dry Grass(Gs) with a Forest(Fp) overlay.

Starting positions are defined by a number followed by 1 space and then the terrain string.

The letters Y,y,Z,z are reserved for UMC and mainline campaigns, so any string containing any of these letters is a custom terrain. Other undefined terrain strings are reserved for future expansion within Wesnoth.

=== Terrain Table ===

The list of terrains can be found at [[TerrainCodeTableWML]]. Since most overlays can be combined with most bases the list is not complete.

== Adding terrains ==
When adding terrains make sure the following files are also checked:

data/multiplayer/factions/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.

data/core/macros/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.

== Decoding the Terrain Codes ==
The initial letters of each terrain code have a standard meaning, though some are not obvious.
* A = “Arctic” i.e. frozen
* B = “Bridge”
* C = “Castle”
* D = “Desert”
* E = "Embellishment"
* F = “Forest”
* G = “Grass” i.e. flat
* H = “Hills”
* I = "Interior" (possible future use)
* J = ''testing''
* K = “Keep”
* L
* M = “Mountains”
* N
* O
* P = “Portal” i.e. doors, gates
* Q = "Un-walkable", {{DevFeature1.17|7}} also used for elevation overlays
* R = “Road”, also used for “Rails”
* S = “Swamp”
* T = {{DevFeature1.15|2}} “Toadstool” i.e. fungus
* U = “Underground”
* V = “Village”
* W = “Water”
* X = "Impassable"
* Y = ''Reserved for UMC''
* Z = ''Reserved for UMC''
* _ = "special system stuff"

Additional letters do not always follow the same meaning, but are as consistent as possible.

* \, |, / = for indicating the direction of bridges
* a =
* b =
* c = "city"
* d = "dry or desert, deciduous"
* e = "encampment"
* f = "flowers, fall"
* g
* h = "human"
* i = "ice"
* j
* k
* l = "lava"
* m = "mixed"
* n
* o = "orc"
* p = "pine"
* q
* r
* s = "simple"
* t = "archetype", a hidden terrain used only as a base for other terrains
* u = "underground"
* v = "elvish"
* w
* x = "chasm"
* y = ''Reserved for UMC''
* z = ''Reserved for UMC''

== Terrain codes in map data ==

This is not the Matrix. You normally don't need to look at encoded maps. However, it can be beneficial and useful for more advanced users to understand the usage of terrain strings in raw map file.

The encoding for maps has a specific format in Wesnoth:

* A map starts with a header with the following keys
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
** {{DevFeature1.13|12}} These keys are now deprecated and will be ignored if present. The blank line mentioned below is not required if these keys are absent.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of terrain codes.
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each terrain code will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''.
** For Wesnoth 1.12.6, ''n'' = 1, 2, 3, ... 9, and the multiplayer server will refuse maps with more than 9 sides.
** For Wesnoth 1.14, more than 9 sides can work, discussion https://r.wesnoth.org/t48129 and https://r.wesnoth.org/t48082
* {{DevFeature1.13|12}} In addition to side numbers, terrains may be prefixed by any number of strings (which should consist of alphanumeric characters only, including underscores). All names and side numbers must be delimited by spaces and are separated from the actual terrain code by an additional space.
** <s>This is broken according to https://r.wesnoth.org/p627595</s> I don't see how this is broken. The editor (as of 1.19.12) only displays a single string per hex though.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== See Also ==
* [[TerrainWML]]
* [[TerrainCodeTableWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

UsefulLinks

2025-05-22T16:43:16Z

Soliton: /* Battle for Wesnoth */

__TOC__
{|class=wikitable
!colspan=2 style='text-align:left'|
=== Battle for Wesnoth ===
|-
|Home Page || https://www.wesnoth.org/
|-
|GitHub Project Page || https://github.com/wesnoth/
|-
|SPI project page || https://www.spi-inc.org/projects/wesnoth/
|-
|Changelog || https://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
|-
|This wiki || [[StartingPoints|https://wiki.wesnoth.org/]]
|-
|The manual || https://manual.wesnoth.org/
|-
|Translation statistics || https://gettext.wesnoth.org/
|-
|Add-on server web interface || https://addons.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
|-
|Code and Content Copyright || https://wiki.wesnoth.org/Wesnoth:Copyrights
|-
|Multiplayer server statistics || https://wesnothd.wesnoth.org/
|-
|Multiplayer statistics || https://replays.wesnoth.org/dashboard/
|-
|Multiplayer replays || https://replays.wesnoth.org
|-
|Unit advancement tree || https://units.wesnoth.org/
|-
|SteamDB || https://steamdb.info/app/599390/
|-
|Forum for users and developers || https://forums.wesnoth.org/ [https://forums.wesnoth.org/search.php?search_id=newposts new posts]
|-
|List of Frequently Proposed Ideas || https://forums.wesnoth.org/viewtopic.php?f=12&t=34904
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/#wesnoth
|-
|Discord server || https://discord.gg/battleforwesnoth
|-
|IRC logs || https://wesnoth.org/irclogs/
|-
|Mastodon Account || https://fosstodon.org/@wesnoth
|-
|Project statistics || https://openhub.net/p/wesnoth
|-
!colspan=2 style='text-align:left'|

=== Developers ===
|-|Git web interface || https://github.com/wesnoth/wesnoth
|-
|Git homepage || https://git-scm.com/
|-
|Git documentation || https://git-scm.com/documentation
|-
|Code documentation || https://devdocs.wesnoth.org/
|-
|GUI(2) documentation || https://wiki.wesnoth.org/GUIToolkit
|-
|Lua documentation || https://wiki.wesnoth.org/LuaAPI
|-
|WML documentation || https://wiki.wesnoth.org/WML
|-
|WFL documentation || https://wiki.wesnoth.org/WFL
|-
|Mailing lists || https://listengine.tuxfamily.org/wesnoth.org/ (old: https://mailman.wesnoth.org/)
|-
|Bug/Feature tracker || https://bugs.wesnoth.org/
|-
|Patch tracker || https://patches.wesnoth.org/
|-
|wesnoth.org server stats || https://collectd.wesnoth.org
|-
|IRC channel (Libera.Chat) || ircs://irc.libera.chat/wesnoth-dev
|-
!colspan=2 style='text-align:left'|

=== Other Links ===
|-
|1vs1 Wesnoth ladder || https://wesnoth.gamingladder.info/
|-
|Wesnoth matches with commentary || http://www.youtube.com/user/NekisBrutalWesnoth
|-
|Wesnoth campaign with commentary in german || https://www.youtube.com/playlist?list=PLc3DmuDuA2imW1vg9xXMNjGHm8VaXvEaz
|-
|WSNPP || [[WSNPP|http://wiki.wesnoth.org/WSNPP]]
|-
|Run Wesnoth online (Windows) || http://spoon.net/the-battle-for-wesnoth
|-
!colspan=2 style='text-align:left'|
=== Multilingual Players' Sites ===
|-
|Community in China || http://wesnoth.cn/
|-
|Polish Community || https://www.wesnoth.com.pl/forum/index.php
|}

[[Category:Wesnoth Wiki]]

Wesnoth Formula Language

2025-05-12T09:40:35Z

Soliton: /* Numbers */

<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 (or use as_decimal if variables are involved) - <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'>
'Hello World'.char = ['H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd']
'Hello World'.word = ['Hello', 'World']
'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.