The Battle for Wesnoth Wiki - User contributions [en]

CompatibilityBreakingChanges

2026-05-31T12:36:26Z

Soliton: /* Compatibility breaking (requires updates to work) */ See https://github.com/wesnoth/wesnoth/commit/1187a9c72b54f87a209c09cbb2681f7bfd27cec6

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

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

== Compatibility breaking changes between 1.18 and 1.19/1.20 ==

=== Compatibility breaking (requires updates to work) ===

* '''[kill]''' now reduces target unit hitpoints to 0 before triggering '''last_breath, die''' events. This affects mentioned events that rely on [have_unit] conditions.
* WFL Removed properties '''unit.side''' and '''terrain.owner'''. Use '''unit.side_number''' and '''terrain.owner_side''' instead. They return 1-indexed side, removed properties returned 0-indexed side.
* Abilities with both '''add''' and '''sub''' now calculate value differently
* rotate_loc_around formula now works
* [era] with id=era_dunefolk does not exist anymore
* [side]'s leader attribute has been removed
* [side]'s [variables] tag is now used to set side variables. Use [side]'s [leader] tag to set a unit variable.
* Setting gold to decimal value fails with error. Previously it was converted to int automatically. As of 1.19.21, automatic conversion is only done in [gold], but not in Lua or [modify_side].
* The following macros were removed ([https://github.com/wesnoth/wesnoth/pull/11126 #11126])
** EARLY_FINISH_BONUS_NOTE
** NO_EARLY_FINISH_BONUS_NOTE
** NO_GOLD_CARRYOVER_NOTE
** NEW_GOLD_CARRYOVER_NOTE_100
** NEW_GOLD_CARRYOVER_NOTE_40
** NEW_GOLD_CARRYOVER_NOTE_20
** MISSILE_FRAME_FIREBALL
** MESSAGE
** STORY_PART_SPEECH
** LOYAL_UNDEAD_UNIT
** ON_SIGHTING
** MAKE_AI_SIDE_PERSISTENT
** DRAKE_FLYING_ANIM
** NO_INTERRUPT_NO_UNDO
** ENABLE_NIGHTBLADE
* Parsing of << in quotes has been fixed. This means cases like '''key="<<"''' do not error anymore and cases like '''key="<<" {MACRO} ">>"''' now expand the macro.

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

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

CompatibilityStandards

2026-05-18T14:34:05Z

Soliton: Move CompatibilityStandardsV2 here

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed. This level should also be used for macro and method stubs containing only an error message describing what was removed and why, as well as if an API feature is found to have a security vulnerability which can't be fixed.

APIs that are clearly labeled as being experimental, such as a WML tag having "experimental" in the name or a lua function having "experimental" in its name or package, can be be removed or deprecated at any level at any time. These are APIs which UMC authors use at their own risk.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

StandardAbilityFilter

2026-04-30T15:25:46Z

Soliton:

From [[FilterWML]], this is the experimental way to filtering ability inside [[StandardUnitFilter]] {{DevFeature1.17|17}}.

It is used to filter out abilities or special weapons using multiple attributes simultaneously (ability type, ID, but also if it affects adjacent units, etc.). The concept is still experimental and developers should keep in mind that it is still possible that it will be removed for stable version 1.20 if it is not validated in version 1.19.

The term [[StandardAbilityFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardAbilityFilter]] needs to be included in a [experimental_filter_ability] or [experimental_filter_ability_active],tag. In [overwrite] subtags in weapon specials [experimental_filter_specials] use also [[StandardAbilityFilter]].

The following attributes and sub-tags are allowed:

* '''tag_name''': matches with the specified ability types. If tag_name=heals then any ability [heals] will match.
* '''id''': unit has an ability with the given id. This can be a comma-separated list. The unit must have at least one of the specified abilities.
* '''affect_self''': matches abilities with ''affect_self'' having the specified value, this value is true by default in abilities.
* '''affect_enemies''': matches abilities with ''affect_enemies'' having the specified value, this value is false by default in abilities.
* '''affect_allies''': matches abilities with ''affect_allies'' having the specified value; however ''affect_alllies'' does not have a default value because its absence within an ability means that it only affects units on the same side as the possessor of it. So if ''affect_allies=none'' is checked, this will correspond to any ability not using this attribute.
* '''affect_adjacent''': match abilities with or without the [affect_adjacent] subtag. If the value is yes, matches abilities with this subtag.
* '''type''': specific to [plagues], match if the ability used as a weapon uses a matching type. If ''type=Walking Corpse'', any weapon transforming a killed unit into that unit type will match. Other abilities using ''type'' can also be checked.
* '''replacement_type''' {{DevFeature1.17|23}}: specific to [damage_type], match if the ability used as a weapon uses a matching type. If ''replacement_type=arcane'', any weapon who replace any type of damage by arcane will match.
* '''alternative_type''' {{DevFeature1.17|23}}: specific to [damage_type], match if the ability used as a weapon uses a matching type. If ''alternative_type=arcane'', any weapon who add arcane to type of damage will match.
* '''active_on''': for abilities used as weapons and [resistance], check if the unit is active in the specified situation. If ''active_on=defense'', then corresponds to active abilities only in defense. This attribute has the value ''both'' by default in these abilities.
* '''apply_to''': In special weapons, checks if the weapon applies to self, opponent, attacker and defender, ''apply_to=self'' by default. In resistance ''apply_to'' is used to determine the type of attack for which the resistance must be modified; it is not recommended to check an ability [resistance] with this attribute. {{DevFeature1.19|1}} It is modified to do an inclusion check for a comma-separated list of damage types in [resistance] abilities
* '''cumulative''': checks whether or not the cumulative option is used in abilities like [leadership] and all specials returning a numeric value.
* '''value''': if for example ''value=10-50'', all abilities with value between 10 and 50 will match, [drains] without specified value will also match, [leadership], [illuminates], [heals], [regenerate] and [heal_on_hit] have default value equals to 0, [berserk] has default value to 1 and [drains] an value by default to 50. Abilities without a default value like [teleport] or [hides] but also '[dummy]' abilities will not be able to match. {{DevFeature1.19|0}} If '''value=default''' and the ability does have a default value like [drains], then match if the value (specified or not) equals the default value.
* '''add, sub, multiply and divide''': as for value, match if the ability uses the specified attribute with the correct value. For add and sub, if ''add=10'' checked and an ability uses ''sub=-10'', it will match. Multiply and divide do not have this reversibility.
* '''overwrite_specials''': works with capabilities using this attribute with the option specified ''none'', ''one_side'' or ''both_sides''. If ''overwrite_specials=none'' is checked, abilities without overwrite_specials will match.
* '''[filter_wml]''' {{DevFeature1.19|0}}: Converts the ability to WML and tests it against a [[FilterWML#Filtering_on_WML_data|WML filter]]. Note that this is slower than other methods, so if possible it's better to use other filter keys; but it can be used to check sub-tags or keys that don't exist in [[StandardAbilityFilter]].

== See Also ==

* [[FilterWML]]
* [[AbilitiesWML]]

[[Category: WML Reference]]

CompatibilityStandardsV2

2026-04-23T19:07:47Z

Soliton: /* Deprecation levels - When to remove deprecated features */

Testers

2026-04-22T08:50:14Z

Soliton: Created page with "Add yourself here if you are available to test anything around wesnoth and mention what environment (OS, platform, windowing system, etc) you can test and/or debug issues in...."

Add yourself here if you are available to test anything around wesnoth and mention what environment (OS, platform, windowing system, etc) you can test and/or debug issues in. Maybe also mention what kind of issues you're mostly interested in or when you're likely available and which way you can best be reached.

* Soliton: can test+debug on macOS, ios, linux (flatpak, X11), android
** reachable via IRC/discord/forum/github

DevelopersHome

2026-04-22T08:42:18Z

Soliton: /* Communication, Feedback, Events */

== General Information ==
* Links
** [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
** [https://github.com/wesnoth/wesnoth/commits/master Latest commits] - Up-to-date commit messages

* Coding Guidelines
** [[Git_for_Wesnoth_Crash_Course]] - guide for contributors who are new to git
** [[HackingWesnoth]] - guide for programmers
** [[CodingStandards]] - for programmers
** [[DeveloperGuide]] - for those who received repository commit rights
** [[SoftwareTesting]] - for programmers

* Library documentation
** [http://cppreference.com C++ Reference]
** [http://www.boost.org/doc/ Boost documentation]

* Debugging Tips
** [[DebuggingWesnoth]]

== Tools and Packaging ==
* Supporting Websites
** [[WesnothRepository]] - accessing the source code
** http://gettext.wesnoth.org/ - gettext status
* Compiling and Building
** [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - how to compile Battle for Wesnoth (it's not hard)
* Packaging and Releasing
** [[ReleasingWesnoth]] - steps to follow to release a new version
* Documentation
** Doxygen - Documentation generator
* More stuff
** [[MaintenanceTools]] WMLLint, WMLIndent and WMLScope
** [[UsingGooglePerformanceTools]] to profile Wesnoth CPU and memory usage.

== I want to start coding, what can I do? ==
* [[EasyCoding]] - Bugs and features that are easy to implement for new coders
* [[NotSoEasyCoding]] - Bugs and features which are doable but lacking someone working on them
* [[GettingStarted]]
* [https://forums.wesnoth.org/viewtopic.php?f=12&t=34904 Frequently Proposed Ideas] - summary of past often-repeated forum discussions
* [[Glossary]]

== Game - Create content ==
* [[BuildingScenarios]] and related useful forum discussions:
** [http://www.wesnoth.org/forum/viewtopic.php?t=4188 Beginning Campaign Development]
** [http://www.wesnoth.org/forum/viewtopic.php?t=4301 A Balancing Act]
* [[ReferenceWML]]
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]

== Code documentation ==
* http://devdocs.wesnoth.org - generated code documentation
* AI
** [[Wesnoth_AI]] - Starting point for AI documentation
* Themes
** [[ThemeSystem]] - customizing the screen layout for the game and the editor
* Multiplayer
** [[WesnothdDesign]] - Guide to the design of wesnothd, the multiplayer server.
* Gui2 - The new Gui-Framework
** [[GUIWidgetInstanceWML]]
** [[GUIWidgetDefinitionWML]]
** [[GUIToolkit]]
** [[GUILayout]]
** Gui2 WML
*** [[GUICanvasWML]]
*** [[GUIToolkitWML]]
*** [[WindowDefinitionWML]]

== Communication, Feedback, Events ==
* http://bugs.wesnoth.org/ - bug reports and feature requests
* http://patches.wesnoth.org/ - patches/pull requests
* [[Testers]] - List of people that can test/debug on specific setups (OS, platform, windowing system, etc)

* Mailing lists
** https://listengine.tuxfamily.org/wesnoth.org/ (old: https://mailman.wesnoth.org/)

* IRC
** [irc://irc.wesnoth.org/#wesnoth-dev Libera.Chat/#wesnoth-dev] - IRC (alias to irc.libera.chat)
** http://irclog.wesnoth.org/ - IRC logs

* Forum - http://forum.wesnoth.org

* This wiki - http://www.wesnoth.org/wiki/Main_Page

* FOSDEM
** [[Fosdem2008]]
** [[Fosdem2009]]
** [[Fosdem2010]]
** [[Fosdem2011]]
** [[Fosdem2012]]

* Google Summer of Code
** [[SummerOfCodeIdeas]] - Ideas for GSoC
** [[SoC_Information_for_Google]] - Our organization profile for Google
** [[SoC_People_to_bug_on_IRC]] - Who GSoC students can ask for help

== Miscellaneous ==
* [[DebugMode]] and [[CommandMode]] - in game debugging commands
* [http://www.wesnoth.org/units/trunk/animations.html Missing unit animations] - what's available and what's missing
* http://units.wesnoth.org/ - Unit reference

[[Category:Development]]

CompatibilityBreakingChanges

2026-04-13T12:29:39Z

Soliton:

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

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

== Compatibility breaking changes between 1.18 and 1.19/1.20 ==

=== Compatibility breaking (requires updates to work) ===

* '''[kill]''' now reduces target unit hitpoints to 0 before triggering '''last_breath, die''' events. This affects mentioned events that rely on [have_unit] conditions.
* WFL Removed properties '''unit.side''' and '''terrain.owner'''. Use '''unit.side_number''' and '''terrain.owner_side''' instead. They return 1-indexed side, removed properties returned 0-indexed side.
* Abilities with both '''add''' and '''sub''' now calculate value differently
* rotate_loc_around formula now works
* [era] with id=era_dunefolk does not exist anymore
* [side]'s leader attribute has been removed
* [side]'s [variables] tag is now used to set side variables. Use [side]'s [leader] tag to set a unit variable.
* Setting gold to decimal value fails with error. Previously it was converted to int automatically. As of 1.19.21, automatic conversion is only done in [gold], but not in Lua or [modify_side].
* The following macros were removed ([https://github.com/wesnoth/wesnoth/pull/11126 #11126])
** EARLY_FINISH_BONUS_NOTE
** NO_EARLY_FINISH_BONUS_NOTE
** NO_GOLD_CARRYOVER_NOTE
** NEW_GOLD_CARRYOVER_NOTE_100
** NEW_GOLD_CARRYOVER_NOTE_40
** NEW_GOLD_CARRYOVER_NOTE_20
** MISSILE_FRAME_FIREBALL
** MESSAGE
** STORY_PART_SPEECH
** LOYAL_UNDEAD_UNIT
** ON_SIGHTING
** MAKE_AI_SIDE_PERSISTENT
** DRAKE_FLYING_ANIM
** NO_INTERRUPT_NO_UNDO
** ENABLE_NIGHTBLADE

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

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

StandardUnitFilter

2026-04-10T09:42:25Z

Soliton: Remove nonsensical radius mention

{{WML Tags}}

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

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

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

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

__TOC__

The following attributes and sub-tags are allowed:

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

== [[Wesnoth Formula Language]] ==

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

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

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

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

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

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

== Tutorial ==

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

== See Also ==

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

[[Category: WML Reference]]

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) */

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