The Battle for Wesnoth Wiki - User contributions [en]

CompatibilityStandards

2018-02-12T10:10:59Z

DeFender1031: /* The Problem - The paradox of progress */ add word for clarity

Created: 2017-07-11
Updated: 2017-07-11

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

=== How to deprecate ===
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 as well as displayed in-game if running in debug mode. In-game deprecation messages should ONLY appear if debug mode is active. Deprecation notices should, ideally, point the user in the direction of the replacement API that they should be using instead. Documentation on deprecated features should be updated to reflect the deprecated nature of the given API, and should likewise have appropriate signposting toward the preferred replacement.

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.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible at least 90% of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore allows for four different levels of deprecation, depending on the severity of the change being made and the cost of maintaining backwards compatibility:

#Deprecated indefinitely — This deprecation level is for changes which are mostly stylistic or organizational in nature and, though the current conventions for core content say not to use them, can theoretically be maintained as wrappers forever. (For example, functions or attributes which have had their names changed or macros which have been replaced with tags.) It is the lowest level of deprecation and is used to signify that a certain API has been replaced with something cleaner which is what should ideally be used, but that there is also no forseeable reason why it will ever need to be forcibly removed while still in use. (This excludes the possibility that an even newer paradigm replaces the one obsoleting this one and causes the need for more aggressive deprecation, in which case the deprecation level should obviously be raised accordingly to match.)
#Deprecated preemptively — This deprecation level is the one which should be aimed for the vast majority of the time. Obsolete APIs which can be implemented in terms of a simple minimal-maintenance wrapper should be deprecated, but left in the code indefinitely. At such time as an obsolete API presents itself as an active obstacle toward further development, it can be slated for removal in the next release, or even removed at will immediately, so long as it has already survived a minimum deprecation period of at least one stable release version. The functions for generating deprecation messages for this level should take a parameter for the first version in which the given feature was deprecated, and their output should reflect whether that period has passed or not, with gentler warnings for those which have not ("this feature is a candidate for removal and may be removed as early as the next version") and harsher warnings for those which have ("this feature is obsolete and may be removed without warning at any time"). Logistically, this differs from "Deprecated indefinitely" only in that it provides a hint to content creators about how likely it is that a future removal will occur, allowing them to prioritize their updates accordingly.
#Deprecated for removal — This deprecation level should be used for features which cannot be maintained as simple wrappers, but which could be maintained as separate, coexisting code. In order to prevent the problem of double-maintenance and code bloat, this level has a built-in lifespan cap of one stable release version following its initial deprecation, after which it will be removed. There may also be cases where a level 1 deprecated feature presents itself as a hindrance to future development, but can be temporarily maintained in this manner as well. In such cases, it is ideal to move the deprecated feature from level 1 to level 2 rather than removing it outright. Deprecation messages for this level should reflect the severity of the deprecation ("this feature will be removed in the next version and requires immediate maintenance").
#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.

It should also be noted that for the purposes of reducing clutter, a deprecated API may also be removed at whatever point that API is no longer being used by any actively maintained add-ons, even if keeping them around would not actively hinder current progress. For the purposes of this rule an "actively maintained add-on" is any add-on in the current stable release or the one directly previous to that. Add-ons which exist for both are to have their current considered the "active" version (meaning that an add-on which used a deprecated API in the previous release but no longer does in the current release is not considered to be actively using that API, and can be disregarded).

=== Post-removal ===
Features which have been removed (subsequent to any of the deprecation levels) should ideally maintain a skeleton of their former interface for at least one stable release version following their removal. This skeleton should print a more detailed error message than the usual "invalid tag/function/object/attribute/whatever" which would result from their complete removal, and the messages should include information on when (and possibly why) the feature was deprecated and where to look for its replacement.

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

=== The Net Result - Mutual benefit ===
By deprecating old methods while keeping them around for as long as feasible, the work for content creators to update for a newer release is drastically reduced. They need only update a bare minimum in order to get their content working again, while still being encouraged to update the rest. While it is true that ideally, a content creator would update all deprecated code to use the updated APIs, the human element can't be ignored here. It is extremely frustrating to find that your existing code has thousands of places which need updating before any of it works at all. It is far more pleasant for to be able to do a small amount of tweaking to get something back into working order and then spend time gradually correcting the "uglier" or "less desirable" code while still having something functional to work off of. Counter-intuitive though it may be, indefinite deprecation actually does a better job of encouraging users to update their code than deprecation with a hard removal time does, by avoiding what would otherwise be a massive drain on motivation. Likewise, when things are deprecated as early as possible, developers have the freedom to remove things at will when the need arises, which will better maintain their motivation as well.

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

MP Tutorial

2017-07-26T01:15:19Z

DeFender1031: /* Game legend */ switch order of bold and coloring to work around css issue.

{| style="float:right;"
|
__TOC__
|}
If you want to play Multiplayer games and are unsure of how, or seek more information on the workings of Wesnoth multiplayer, this is the place for you. Welcome to our MP tutorial.
 
This tutorial was designed for version 1.4 of Battle for Wesnoth, but most information here is still accurate.
 
Don't be daunted by the length of this page. It's not a required read, meant mostly as a bulletproof description on how to do everything on multiplayer and you can skim through it pretty quickly.

=== Multiplayer menu ===

<div class="thumb tright"><div>
[http://img140.imageshack.us/img140/1740/menu1zw9.png http://img140.imageshack.us/img140/1740/menu1zw9.th.png]
<div class="thumbcaption">Battle for Wesnoth main menu</div></div>
</div>

The first thing you need to do if you want to play a multiplayer game is to choose which kind of game you want to play.

* Click the multiplayer button in the general menu of wesnoth.

A new window will pop-up, asking you what kind of multiplayer game you want to play :

<div class="thumb tright"><div>
[http://img142.imageshack.us/img142/1139/menu2lu0.png http://img142.imageshack.us/img142/1139/menu2lu0.th.png]
<div class="thumbcaption">Pop-up window</div></div>
</div>

* Put your username on the top.

Your username is how you will appear on the servers and during games. The next time you will click on the multiplayer button on the main screen, this username will be automatically set, but you will be able to change it anytime you come back to this pop-up window. It is advised that you keep the same username (in 1.5, you are reserved your forum name), as players are often recognized by their names, and so you will build a reputation if you use the same name each time you play.

* Choose the kind of game you want to play.

Under your username, you now have three choices:
* Join official server : Allows you to join the official Battle for Wesnoth server, where most of the multiplayer games are played.
* Connect to host/server : Allows you to connect to a different server, useful when the official server is down for example...
* Local game : Allows you to play a multiplayer game on a sole computer, this is Battle for Wesnoth "Hot-Seat" mode.

Double click on the selected option or press the OK button to start playing. A click on the cancel button will bring you back to the main menu.

==== Welcome to the official server ====

When you connect to the server, a welcome message appears in the chat area at the bottom. It contains some useful directions and occasionally some current information. 
Perhaps the most important part of it is the link to the official server's [[MP_CodeOfConduct|Code of Conduct]]. All players who stay on the server are supposed to have read it, but of course we can't force anyone. : )

=== The lobby ===
The multiplayer '''lobby''' is a game screen with interactive list of games, of players and a [[MP_Tutorial#Talking_to_players|simple chat interface]].
 
<div class="thumb tright"><div>
[http://img76.imageshack.us/img76/628/lobby3ar3.png http://img76.imageshack.us/img76/628/lobby3ar3.th.png]
<div class="thumbcaption">Official server</div></div>
</div>The lobby looks like the image on the right. (without the green lines of course) 

It is divided into four areas, each further described below:

* 1: [[MP_Tutorial#Menu|Menu]].
* 2: [[MP_Tutorial#Game_legend|Games]].
* 3: [[MP_Tutorial#Players|Players]].
* 4: [[MP_Tutorial#Talking_to_players|Chat Area]].

==== Menu ====

The server menu allows you to join, observe or create a game.

* To join a game, click on a game and then click on the "Join Game" button. We will see which games you can join and which you can not join in the Game legend section.
* To observe a game, click on the game you want to observe, then click the "Observe Game" button. If you want to go straight to the current turn of the game, check the "Quick Replays" box, if this box is unchecked, you will be able to see all the moves of each player during all the turns of the game.
* To create a game, click the "Create Game" button. We will go back to this in the "Create a game" section.
* "Preferences" allows you to change Battle for Wesnoth configuration, sound, video... this button brings you to the same menu that the "Preferences" button on the title page of Battle for Wesnoth.
* The "Quit" button brings you back to the title menu.

==== Game legend ====

Games appear in the lobby in different colors :

* ''' White ''' are games that already have started. You can only observe those games.
* ''' Red ''' are games that have started and that you can't observe.
* ''' Green ''' are games you can join or observe and which haven't started yet.
* ''' Yellow ''' are reloaded games, only people with the same name as the original players can join.

Here is an example of a "green" game, it's to say a game you are able to play :
http://img155.imageshack.us/img155/2041/gamefk7.png

* On the left appears a thumbnail of the map.
* On the top, in green, appears the name of the game : in this example "remfarkas jateka" (remfarkas's game)
* On the top right corner appears the number of players needed for the game to start, or "vacant slot". In our example you can learn that the game is designed for four players and that three players are already waiting for the game to start.

Next comes a white line where you can see a description of what is needed to play :
* First comes the "era" (Default in this example). '''"Default" means that everyone can join''' the game to play. In some other cases, you will need a specific era to play.
* Just right to the era appears the size of the map, in remfarkas's game, 20x20 tiles (which means this is a small map).
* Then comes the number of players the map is designed for (4p in the same example).
* And last is the name of the map : "Isar's Cross".

The last line shows some icons :

* The eye : http://img154.imageshack.us/img154/2681/eye1gs1.png means that you can observe this game. When you can't observe a game, this eye is scratched in red.
* The gold pile : http://img83.imageshack.us/img83/9238/goldpileak2.png tells you the number of gold you get each turn per village (in this example two gold per village per turn).
* The experience needed to level up a unit is described near this icon : http://img504.imageshack.us/img504/9579/xperienceqh7.png (70% is the required experience using map settings most of the time).
* This icon: http://img147.imageshack.us/img147/1123/fogmk5.png shows if there will be fog of war or no fog during the game.
* At last can in some cases be seen "Use Map Settings" this tells you that the game is set with the original configuration developers gave to their map.

Here are some other examples, with different configurations:

http://img293.imageshack.us/img293/6357/game2bc3.png

"jeu de Prince" (prince's game) needed that you had the "era_magic" to play, anyway it's a "white game" so you can't join.

'''''Eras can be downloaded on the main screen of Battle for Wesnoth, in the "Add-ons" menu.'''''

Also, please be sure to have the appropriate era before joining a game, if you do not have it and that the game starts, you will crash while other players will be less likely to play with you again.

On the top-right corner you can see that the game has already started and is currently at turn 1.
The game can be observed (once more, you need the appropriate era).
Players get 5 gold per village per turn, units need 30% of experience to level up and there is no fog of war.

Some other games are reserved, most of the times the word "reserved" appears in the name of the game. Ladder games are reserved for ladder players only for example.
http://img187.imageshack.us/img187/74/laddergamepg6.png

This game also uses a timer. Players will have 270 seconds per turn, a 200 seconds reserve and a 20 seconds action bonus (they will get 20 seconds more each time they do an action).

'''In any case, please read the name of the game before joining''', a lot of informations is written here by the game hosts.

==== Players ====

You may have noticed that players on the right panel can appear in different colors :
* Players  in blue  are those in the currently selected game (as players or as observers).
* Players  '''in red'''  are players currently involved in a game.
* Players  in white  are on the lobby, they are not playing and may be available for a game.

Your name appears first, then appear the names of your friends.

Names are sorted alphabetically (once with major caps and then with minor caps) for each color type.

==== Talking to players ====

You might need to talk to other players, for example to set up a game. It's not always easy to find players so you may have to ask who is interested for what kind of games... Or maybe you just want to ask something.

<div align="center">You have two ways to talk on the official server :</div>

* Using the chat box. Just type your message then press "return/enter". Your message will be visible for everyone on the lobby.
* Send a 'private message' also know as 'whisper' to a player -- it will only be visible for the player you send it to...
:'''*''' Double click on a player name on the right panel, a window will pop-up, then type your message and press Enter.
:'''*''' When combined with [[MP_Tutorial#Tips|tab-completion]], the faster way to whisper is by typing in the following command and pressing Enter: 
:::: "/m username message", changing "username" the the desired nickname. To see more useful commands check the following page: [[MP_CodeOfConduct#Useful_commands|Useful_commands]]

==== Hosts ====
Any player who creates a game is that game's host. 
He/she is in charge of solving any in-game issues or disputes between players, possibly with the aid of the host-only [[MP_CodeOfConduct#command_type_2|commands]].

=== Time To Play ===

==== Joining a game ====

To join a game, double click on a green game or click a game and then press the "Join Game" button.
You will then be asked to choose a faction and a leader, you can also choose to play with a random faction and leader.

If you decide to change faction/hero, you can ask the host to change it for you while the game hasn't started yet.

==== Creating a game ====

<div class="thumb tright"><div>
[http://img505.imageshack.us/img505/9342/creategamekd1.png http://img505.imageshack.us/img505/9342/creategamekd1.th.png]
<div class="thumbcaption">Creating a game</div></div>
</div>
When pressing the create game button, you should see something like this :

This window will allow you to configure the game you want to play. Different options are available.

* On the top of the screen, put the desired name for your game. Battle for Wesnoth will automatically name your game "username's game" (in the language you use Battle for Wesnoth), but you can change this name just clicking in the text field.
* Under the name of your game, you have to choose the map on which you want to play. 2p maps are designed for two players, 3p for three players etc... A thumbnail of the map will appear on the left.
* Under the picture of your map, you have two buttons, "Default" is the current era for the map, you can change it by clicking, a list will show you the available eras.
* You can set a password by clicking the "Set Password..." button. When trying to join your game, people will be asked for this password. Useful for reserved games.

The right of the screen contains more gameplay options:

* The first horizontal scroll bar allows you to choose a determined number of turns before the game stops. At maximum the game will not have turn limit.
* The second scroll bar will determine the number of gold a player gains each turn by holding a village.
* The third scroll bar determines the experience required for any unit to level up.

''''' You may not be able to change some of the configurations if the box "Use map settings" is set.'''''

Then come check boxes :

* Use map settings, when checked, the game will be played with the developers configuration.
* Observers, allows observers to watch your game when checked.
* Time limit, when checked determines a time limit for each turn, you can set this time limit with the little scroll bars, where (in seconds) :
*** "Init. Limit" is the initial amount of time a player have.
*** "Turn Bonus" is the amount of time a player gets each turn.
*** "Reservoir" is a granted number of seconds each turn to complete the turn bonus.
*** "Action Bonus" is a granted number of seconds for each unit who have done an action this turn.

The right options can only be checked/unchecked when you don't use the map settings:

* Fog of war : if unchecked both player can see the whole map when playing. If checked, each player will only be able to see as far as his/her units can move next turn + one hexagon.
* Shroud of war : this is a kind of fog of war, but darker ;).
* Random start time : instead of starting at sunrise, game will start at a random time of the day.

When you have set all the desired options, press OK, if you don't want to continue further, press cancel and you'll get back to the lobby.

Once you have pressed OK, choose your faction and your hero and wait for other players.
You're also able to toggle position between players by clicking a player name. (The player whom name comes first will play first)

=== Other servers/ Local games ===

You now know all to play on any [[MultiplayerServers|other server]] or to play a local game, those work exactly the same way as described above.

=== Tips ===
These assorted bits of advice could make your stay on the server more comfortable.

==== Registering a nickname ====
registering a nick has a number of advantages:
* it makes it harder for someone to impersonate you, and people will immediately know it's you
* you can kick an old instance of your connection by reconnecting (remove the 'ghost')

&emsp;you can register a nickname by going [http://forum.wesnoth.org/ucp.php?mode=register here] 
 
'''Tab-completion''' 
Instead of typing a person's whole name, you can have the remainder of it filled-in by pressing the Tab key. 
 
To catch a person's attention, send them a PM or type out their whole nick as it's written. 
(NOTE: sending PM's to people who don't know you might offend them)

=== Final Word ===

Hope this tutorial has helped you, good luck, have fun ;).

=== See Also ===

* [[MP_CodeOfConduct|Wesnoth Code of Conduct]]
* [[GettingStarted|Getting Started]]
* [[CommandMode|Useful Commands]]
Maybe also some :
* [[BasicStrategy|Basic Strategy]] or
* [[AdvancedTactics|Advanced Tactics]]

[[Category:Playing_Wesnoth]]

CompatibilityStandards

2017-07-11T18:03:00Z

DeFender1031: /* Deprecation levels - When to remove deprecated features */ add a fourth discussed in the channel.

Created: 2017-07-11
Updated: 2017-07-11

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

=== How to deprecate ===
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 as well as displayed in-game if running in debug mode. In-game deprecation messages should ONLY appear if debug mode is active. Deprecation notices should, ideally, point the user in the direction of the replacement API that they should be using instead. Documentation on deprecated features should be updated to reflect the deprecated nature of the given API, and should likewise have appropriate signposting toward the preferred replacement.

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.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible at least 90% of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore allows for four different levels of deprecation, depending on the severity of the change being made and the cost of maintaining backwards compatibility:

#Deprecated indefinitely — This deprecation level is for changes which are mostly stylistic or organizational in nature and, though the current conventions for core content say not to use them, can theoretically be maintained as wrappers forever. (For example, functions or attributes which have had their names changed or macros which have been replaced with tags.) It is the lowest level of deprecation and is used to signify that a certain API has been replaced with something cleaner which is what should ideally be used, but that there is also no forseeable reason why it will ever need to be forcibly removed while still in use. (This excludes the possibility that an even newer paradigm replaces the one obsoleting this one and causes the need for more aggressive deprecation, in which case the deprecation level should obviously be raised accordingly to match.)
#Deprecated preemptively — This deprecation level is the one which should be aimed for the vast majority of the time. Obsolete APIs which can be implemented in terms of a simple minimal-maintenance wrapper should be deprecated, but left in the code indefinitely. At such time as an obsolete API presents itself as an active obstacle toward further development, it can be slated for removal in the next release, or even removed at will immediately, so long as it has already survived a minimum deprecation period of at least one stable release version. The functions for generating deprecation messages for this level should take a parameter for the first version in which the given feature was deprecated, and their output should reflect whether that period has passed or not, with gentler warnings for those which have not ("this feature is a candidate for removal and may be removed as early as the next version") and harsher warnings for those which have ("this feature is obsolete and may be removed without warning at any time"). Logistically, this differs from "Deprecated indefinitely" only in that it provides a hint to content creators about how likely it is that a future removal will occur, allowing them to prioritize their updates accordingly.
#Deprecated for removal — This deprecation level should be used for features which cannot be maintained as simple wrappers, but which could be maintained as separate, coexisting code. In order to prevent the problem of double-maintenance and code bloat, this level has a built-in lifespan cap of one stable release version following its initial deprecation, after which it will be removed. There may also be cases where a level 1 deprecated feature presents itself as a hindrance to future development, but can be temporarily maintained in this manner as well. In such cases, it is ideal to move the deprecated feature from level 1 to level 2 rather than removing it outright. Deprecation messages for this level should reflect the severity of the deprecation ("this feature will be removed in the next version and requires immediate maintenance").
#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.

It should also be noted that for the purposes of reducing clutter, a deprecated API may also be removed at whatever point that API is no longer being used by any actively maintained add-ons, even if keeping them around would not actively hinder current progress. For the purposes of this rule an "actively maintained add-on" is any add-on in the current stable release or the one directly previous to that. Add-ons which exist for both are to have their current considered the "active" version (meaning that an add-on which used a deprecated API in the previous release but no longer does in the current release is not considered to be actively using that API, and can be disregarded).

=== Post-removal ===
Features which have been removed (subsequent to any of the deprecation levels) should ideally maintain a skeleton of their former interface for at least one stable release version following their removal. This skeleton should print a more detailed error message than the usual "invalid tag/function/object/attribute/whatever" which would result from their complete removal, and the messages should include information on when (and possibly why) the feature was deprecated and where to look for its replacement.

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

=== The Net Result - Mutual benefit ===
By deprecating old methods while keeping them around for as long as feasible, the work for content creators to update for a newer release is drastically reduced. They need only update a bare minimum in order to get their content working again, while still being encouraged to update the rest. While it is true that ideally, a content creator would update all deprecated code to use the updated APIs, the human element can't be ignored here. It is extremely frustrating to find that your existing code has thousands of places which need updating before any of it works at all. It is far more pleasant for to be able to do a small amount of tweaking to get something back into working order and then spend time gradually correcting the "uglier" or "less desirable" code while still having something functional to work off of. Counter-intuitive though it may be, indefinite deprecation actually does a better job of encouraging users to update their code than deprecation with a hard removal time does, by avoiding what would otherwise be a massive drain on motivation. Likewise, when things are deprecated as early as possible, developers have the freedom to remove things at will when the need arises, which will better maintain their motivation as well.

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

CompatibilityStandards

2017-07-11T08:28:30Z

DeFender1031: add dates

Created: 2017-07-11
Updated: 2017-07-11

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

=== How to deprecate ===
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 as well as displayed in-game if running in debug mode. In-game deprecation messages should ONLY appear if debug mode is active. Deprecation notices should, ideally, point the user in the direction of the replacement API that they should be using instead. Documentation on deprecated features should be updated to reflect the deprecated nature of the given API, and should likewise have appropriate signposting toward the preferred replacement.

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.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible at least 90% of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore allows for three different levels of deprecation, depending on the severity of the change being made and the cost of maintaining backwards compatibility:
#Deprecated indefinitely — This deprecation level is the one which should be aimed for the vast majority of the time. Obsolete APIs which can be implemented in terms of a simple minimal-maintenance wrapper should be deprecated, but left in the code indefinitely. At such time as an obsolete API presents itself as an active obstacle toward further development, it can be slated for removal in the next release, or even removed at will immediately, so long as it has already survived a minimum deprecation period of at least one stable release version. The functions for generating deprecation messages for this level should take a parameter for the first version in which the given feature was deprecated, and their output should reflect whether that period has passed or not, with gentler warnings for those which have not ("this feature is a candidate for removal and may be removed as early as the next version") and harsher warnings for those which have ("this feature is obsolete and may be removed without warning at any time").
#Deprecated for removal — This deprecation level should be used for features which cannot be maintained as simple wrappers, but which could be maintained as separate, coexisting code. In order to prevent the problem of double-maintenance and code bloat, this level has a built-in lifespan cap of one stable release version following its initial deprecation, after which it will be removed. There may also be cases where a level 1 deprecated feature presents itself as a hindrance to future development, but can be temporarily maintained in this manner as well. In such cases, it is ideal to move the deprecated feature from level 1 to level 2 rather than removing it outright. Deprecation messages for this level should reflect the severity of the deprecation ("this feature will be removed in the next version and requires immediate maintenance").
#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.

=== Post-removal ===
Features which have been removed (subsequent to any of the deprecation levels) should ideally maintain a skeleton of their former interface for at least one stable release version following their removal. This skeleton should print a more detailed error message than the usual "invalid tag/function/object/attribute/whatever" which would result from their complete removal, and the messages should include information on when (and possibly why) the feature was deprecated and where to look for its replacement.

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

=== The Net Result - Mutual benefit ===
By deprecating old methods while keeping them around for as long as feasible, the work for content creators to update for a newer release is drastically reduced. They need only update a bare minimum in order to get their content working again, while still being encouraged to update the rest. While it is true that ideally, a content creator would update all deprecated code to use the updated APIs, the human element can't be ignored here. It is extremely frustrating to find that your existing code has thousands of places which need updating before any of it works at all. It is far more pleasant for to be able to do a small amount of tweaking to get something back into working order and then spend time gradually correcting the "uglier" or "less desirable" code while still having something functional to work off of. Counter-intuitive though it may be, indefinite deprecation actually does a better job of encouraging users to update their code than deprecation with a hard removal time does, by avoiding what would otherwise be a massive drain on motivation. Likewise, when things are deprecated as early as possible, developers have the freedom to remove things at will when the need arises, which will better maintain their motivation as well.

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

CompatibilityStandards

2017-07-11T06:19:27Z

DeFender1031: Rough draft of policy recently discussed and agreed upon by many in the dev channel.

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

=== How to deprecate ===
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 as well as displayed in-game if running in debug mode. In-game deprecation messages should ONLY appear if debug mode is active. Deprecation notices should, ideally, point the user in the direction of the replacement API that they should be using instead. Documentation on deprecated features should be updated to reflect the deprecated nature of the given API, and should likewise have appropriate signposting toward the preferred replacement.

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.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible at least 90% of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore allows for three different levels of deprecation, depending on the severity of the change being made and the cost of maintaining backwards compatibility:
#Deprecated indefinitely — This deprecation level is the one which should be aimed for the vast majority of the time. Obsolete APIs which can be implemented in terms of a simple minimal-maintenance wrapper should be deprecated, but left in the code indefinitely. At such time as an obsolete API presents itself as an active obstacle toward further development, it can be slated for removal in the next release, or even removed at will immediately, so long as it has already survived a minimum deprecation period of at least one stable release version. The functions for generating deprecation messages for this level should take a parameter for the first version in which the given feature was deprecated, and their output should reflect whether that period has passed or not, with gentler warnings for those which have not ("this feature is a candidate for removal and may be removed as early as the next version") and harsher warnings for those which have ("this feature is obsolete and may be removed without warning at any time").
#Deprecated for removal — This deprecation level should be used for features which cannot be maintained as simple wrappers, but which could be maintained as separate, coexisting code. In order to prevent the problem of double-maintenance and code bloat, this level has a built-in lifespan cap of one stable release version following its initial deprecation, after which it will be removed. There may also be cases where a level 1 deprecated feature presents itself as a hindrance to future development, but can be temporarily maintained in this manner as well. In such cases, it is ideal to move the deprecated feature from level 1 to level 2 rather than removing it outright. Deprecation messages for this level should reflect the severity of the deprecation ("this feature will be removed in the next version and requires immediate maintenance").
#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.

=== Post-removal ===
Features which have been removed (subsequent to any of the deprecation levels) should ideally maintain a skeleton of their former interface for at least one stable release version following their removal. This skeleton should print a more detailed error message than the usual "invalid tag/function/object/attribute/whatever" which would result from their complete removal, and the messages should include information on when (and possibly why) the feature was deprecated and where to look for its replacement.

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

=== The Net Result - Mutual benefit ===
By deprecating old methods while keeping them around for as long as feasible, the work for content creators to update for a newer release is drastically reduced. They need only update a bare minimum in order to get their content working again, while still being encouraged to update the rest. While it is true that ideally, a content creator would update all deprecated code to use the updated APIs, the human element can't be ignored here. It is extremely frustrating to find that your existing code has thousands of places which need updating before any of it works at all. It is far more pleasant for to be able to do a small amount of tweaking to get something back into working order and then spend time gradually correcting the "uglier" or "less desirable" code while still having something functional to work off of. Counter-intuitive though it may be, indefinite deprecation actually does a better job of encouraging users to update their code than deprecation with a hard removal time does, by avoiding what would otherwise be a massive drain on motivation. Likewise, when things are deprecated as early as possible, developers have the freedom to remove things at will when the need arises, which will better maintain their motivation as well.

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

DirectActionsWML

2016-11-08T18:21:38Z

DeFender1031: /* [teleport] */ as it was written before, it basically meant "if it's occupied, we'll just randomly send the unit anywhere else"

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

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

The following tags are actions:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) floating text to display above the unit, such as a damage amount
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
* '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

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

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

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

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit.
* '''extra_recruit''': the types of units that the side can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

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

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

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

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

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't take any arguments.

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

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''': if 'yes', displays the unit dying (fading away).
* '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.

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

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

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter.
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this to work around a bug when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP, SPECIAL_BACKSTAB, or any other effect that uses variable substitution or when using [effect][filter] with a $this_unit (see http://gna.org/bugs/index.php?18893).
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

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

=== [transform_unit] ===
Transforms every unit matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

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

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

=== [object] ===
Gives some unit an object which modifies their stats in some way.
* '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per scenario. In a campaign objects with the same id can be assigned once per scenario. For filtering objects, custom key can be used, such as item_id.
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} Enables the above behaviour. If set to no, the object ID is not used to prevent the object from being taken more than once, but can still be used to remove it using [remove_object].
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this to work around a bug when adding ABILITY_TELEPORT (or any other effect that uses variable substitution) via an [object] or when using [object][effect][filter]with a $this_unit (see http://gna.org/bugs/index.php?18893). {{DevFeature1.13|5}} ABILITY_LEADERSHIP and SPECIAL_BACKSTAB now also use variable substitution and thus require this to be set to "yes".
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed)
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to true, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
* '''no_write''': {{DevFeature1.13|1}} (bool, default false). If true, the contents of [effect] will be applied to the relevant unit, but the [object] tag will not be written to unit.modifications. This renders duration= irrelevant. {{DevFeature1.13|6}} This is deprecated and will probably be removed in the release after 1.13.6. To get the same effect, use [effect] tags in [modify_unit].

=== [remove_object] ===

{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units matching the filter have matching objects removed
* '''object_id''': The id of the object to be removed.

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

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

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

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

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

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

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

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

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

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".

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

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

''Example:'' (caves in parts of a map)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [remove_time_area] ===

{{DevFeature1.13|2}}

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

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

=== [replace_map] ===

Replaces the entire map.
* '''map''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

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

=== [tunnel] ===

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

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

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

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

=== [do_command] ===

{{DevFeature1.13|0}}

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

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it.

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

This command should always be replay safe.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

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

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

== See Also ==

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

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

InternalActionsWML

2016-11-08T00:36:16Z

DeFender1031: /* [store_villages] */ this is apparently not how that behaves. interesting

{{WML Tags}}

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

== Variable Actions ==

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

=== [set_variable] ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.

=== [set_variables] ===

Manipulates a WML array or container

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

* '''mode''': one of the following values:
** ''replace'': will clean the array '''name''' and replace it with given data
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

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

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

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

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

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

=== Capturing Game Data ===

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

==== [store_gold] ====

Stores a side's gold into a variable.

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

==== [store_locations] ====

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

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

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

==== [store_reachable_locations] ====

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

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

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

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

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")

'''Result'''

Variable will contain following members:
* '''color''': It indicates team color. Can be one of the following:
{| border = 1
| ''color''
| red
| blue
| green
| purple
| black
| brown
| orange
| white
| teal
|-
| ''value''
| 1
| 2
| 3
| 4
| 5
| 6
| 7
| 8
| 9
|}
* '''controller''': Indicates type of player that control this side. ''In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''network''': In multiplayer for sides that client does not control, both what would normally be human and ai. For host values are as usual, this is where OOS comes from.
** '''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 have.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Base income for this side (without villages).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''team_name''': String representing the team's description.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.

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

==== [store_time_of_day] ====

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

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

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

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

==== [store_turns] ====

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

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

==== [store_unit] ====

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

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

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

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

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

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

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

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

==== [store_unit_type] ====

* '''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")

==== [store_unit_type_ids] ====

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

==== [store_villages] ====

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

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

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

==== [store_items] ====

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

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

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

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

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

==== [find_path] ====

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

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

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

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

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

=== [clear_variable] ===

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

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

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

=== [sync_variable] ===

{{DevFeature1.13|0}}

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

== Other Internal Actions ==

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

=== [fire_event] ===

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

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

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

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

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

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

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

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

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

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

=== [insert_tag] ===

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

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

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

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

=== [role] ===

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

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

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

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

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

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

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

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

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

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

=== Flow control actions ===

{{DevFeature1.13|2}}

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

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. No further WML actions are executed in this context. If there was another event queued, that event will be run as usual.

== Examples ==

=== Using [set_variables] to Create Arrays of 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}

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

=== [insert_tag] Example ===

[event]
name=moveto

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

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

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]

This is effectively identical to:

[event]
name=moveto

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

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

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

LuaWML/Reorganization

2016-11-06T20:56:43Z

DeFender1031: /* file */ update

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

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

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

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

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

The categories and names being proposed are as follows:

== variable ==
APIs for dealing with WML variables
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_variable
|wesnoth.variable.get
|
|-
|wesnoth.set_variable
|wesnoth.variable.set
|
|-
|wesnoth.get_all_vars
|wesnoth.variable.get_all
|
|-
|helper.set_wml_var_metatable
|wesnoth.variable.get_proxy
|
|-
|helper.get_variable_array
|wesnoth.variable.get_array
|
|-
|helper.set_variable_array
|wesnoth.variable.set_array
|
|-
|helper.get_variable_proxy_array
|wesnoth.variable.get_proxy_array
|
|}

== wml ==
APIs for dealing with wml tables and vconfigs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|helper.get_child
|wesnoth.wml.get_child
|
|-
|helper.get_nth_child
|wesnoth.wml.get_nth_child
|
|-
|helper.child_count
|wesnoth.wml.child_count
|
|-
|helper.child_range
|wesnoth.wml.child_range
|
|-
|helper.child_array
|wesnoth.wml.child_array
|
|-
|wesnoth.tovconfig
|wesnoth.wml.tovconfig
|
|-
|helper.literal
|wesnoth.wml.literal
|
|-
|helper.parsed
|wesnoth.wml.parsed
|
|-
|helper.shallow_literal
|wesnoth.wml.shallow_literal
|
|-
|helper.shallow_parsed
|wesnoth.wml.shallow_parsed
|
|-
|wesnoth.debug
|wesnoth.wml.debug
|
|-
|helper.set_wml_tag_metatable
|wesnoth.wml.get_tag_creator
|
|}

== interface ==
APIs for dealing with the main game interface
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.delay
|wesnoth.interface.delay
|
|-
|wesnoth.float_label
|wesnoth.interface.float_label
|
|-
|wesnoth.select_hex
|wesnoth.interface.select_hex
|
|-
|wesnoth.select_unit
|wesnoth.interface.select_unit
|
|-
|wesnoth.highlight_hex
|wesnoth.interface.highlight_hex
|
|-
|wesnoth.deselect_hex
|wesnoth.interface.deselect_hex
|
|-
|wesnoth.get_selected_tile
|wesnoth.map.get_selected_hex
|
|-
|wesnoth.scroll_to_tile
|wesnoth.interface.scroll_to_hex
|
|-
|wesnoth.lock_view
|wesnoth.interface.lock
|
|-
|wesnoth.view_locked
|wesnoth.interface.is_locked
|
|-
|wesnoth.is_skipping_messages
|wesnoth.interface.is_skipping_messages
|
|-
|wesnoth.skip_messages
|wesnoth.interface.skip_messages
|
|-
|wesnoth.add_tile_overlay
|wesnoth.interface.add_hex_overlay
|
|-
|wesnoth.remove_tile_overlay
|wesnoth.interface.remove_hex_overlay
|
|-
|items.place_image
|wesnoth.interface.add_item_image
|
|-
|items.place_halo
|wesnoth.interface.add_item_halo
|
|-
|items.remove
|wesnoth.interface.remove_item
|
|-
|wesnoth.theme_items
|wesnoth.interface.game_display
|
|-
|helper.move_unit_fake
|wesnoth.interface.move_unit_fake
|
|}

== dialog ==
GUI2 APIs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.show_message_dialog
|wesnoth.dialog.show_message
|
|-
|wesnoth.show_popup_dialog
|wesnoth.dialog.show_popup
|
|-
|wesnoth.show_dialog
|wesnoth.dialog.show
|
|-
|wesnoth.set_dialog_value
|wesnoth.dialog.set_value
|
|-
|wesnoth.get_dialog_value
|wesnoth.dialog.get_value
|
|-
|wesnoth.set_dialog_active
|wesnoth.dialog.set_active
|
|-
|wesnoth.set_dialog_callback
|wesnoth.dialog.set_callback
|
|-
|wesnoth.set_dialog_markup
|wesnoth.dialog.set_markup
|
|-
|wesnoth.set_dialog_focus
|wesnoth.dialog.set_focus
|
|-
|wesnoth.set_dialog_visible
|wesnoth.dialog.set_visible
|
|-
|wesnoth.set_dialog_canvas
|wesnoth.dialog.set_canvas
|
|-
|wesnoth.add_dialog_tree_node
|wesnoth.dialog.add_tree_node
|
|-
|wesnoth.remove_dialog_item
|wesnoth.dialog.remove_item
|
|-
|wesnoth.get_displayed_unit
|wesnoth.dialog.get_displayed_unit
|
|-
|helper.get_user_choice
|wesnoth.dialog.get_user_choice
|
|}

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

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

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

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

== unit ==
APIs for working with unit data
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_units
|wesnoth.unit.get_array
|
|-
|wesnoth.get_unit
|wesnoth.unit.get
|
|-
|wesnoth.match_unit
|wesnoth.unit.matches
|
|-
|wesnoth.put_unit
|wesnoth.unit.put
|
|-
|wesnoth.erase_unit
|wesnoth.unit.erase
|
|-
|wesnoth.get_recall_units
|wesnoth.unit.get_recall
|
|-
|wesnoth.put_recall_unit
|wesnoth.unit.put_recall
|
|-
|wesnoth.create_unit
|wesnoth.unit.create
|
|-
|wesnoth.copy_unit
|wesnoth.unit.copy
|
|-
|wesnoth.extract_unit
|wesnoth.unit.extract
|
|-
|wesnoth.advance_unit
|wesnoth.unit.advance
|
|-
|wesnoth.add_modification
|wesnoth.unit.add_modification
|
|-
|wesnoth.unit_resistance
|wesnoth.unit.resistance
|
|-
|wesnoth.unit_defense
|wesnoth.unit.defense
|
|-
|wesnoth.unit_movement_cost
|wesnoth.unit.movement_cost
|
|-
|wesnoth.unit_vision_cost
|wesnoth.unit.vision_cost
|
|-
|wesnoth.unit_jamming_cost
|wesnoth.unit.jamming_cost
|
|-
|wesnoth.unit_ability
|wesnoth.unit.ability
|
|-
|wesnoth.unit_types
|wesnoth.unit.types
|
|-
|wesnoth.transform_unit
|wesnoth.unit.transform
|
|-
|helper.modify_unit
|wesnoth.unit.modify_unit
|
|}

== side ==
APIs for working with sides
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.sides
|wesnoth.side.proxy
|
|-
|wesnoth.get_sides
|wesnoth.side.get_all
|
|-
|wesnoth.is_enemy
|wesnoth.side.is_enemy
|
|-
|wesnoth.match_side
|wesnoth.side.matches
|
|-
|helper.all_teams
|wesnoth.side.iterator
|
|}

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

== location_set ==
Class for working with sets of locations

Since this is already nicely compartmentalized, the only proposed change is to move it to wesnoth.location_set rather than being global.

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

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

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

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

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

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

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

LuaWML/Reorganization

2016-11-06T19:22:46Z

DeFender1031: more questions

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

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

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

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

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

The categories and names being proposed are as follows:

== variable ==
APIs for dealing with WML variables
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_variable
|wesnoth.variable.get
|
|-
|wesnoth.set_variable
|wesnoth.variable.set
|
|-
|wesnoth.get_all_vars
|wesnoth.variable.get_all
|
|-
|helper.set_wml_var_metatable
|wesnoth.variable.get_proxy
|
|-
|helper.get_variable_array
|wesnoth.variable.get_array
|
|-
|helper.set_variable_array
|wesnoth.variable.set_array
|
|-
|helper.get_variable_proxy_array
|wesnoth.variable.get_proxy_array
|
|}

== wml ==
APIs for dealing with wml tables and vconfigs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|helper.get_child
|wesnoth.wml.get_child
|
|-
|helper.get_nth_child
|wesnoth.wml.get_nth_child
|
|-
|helper.child_count
|wesnoth.wml.child_count
|
|-
|helper.child_range
|wesnoth.wml.child_range
|
|-
|helper.child_array
|wesnoth.wml.child_array
|
|-
|wesnoth.tovconfig
|wesnoth.wml.tovconfig
|
|-
|helper.literal
|wesnoth.wml.literal
|
|-
|helper.parsed
|wesnoth.wml.parsed
|
|-
|helper.shallow_literal
|wesnoth.wml.shallow_literal
|
|-
|helper.shallow_parsed
|wesnoth.wml.shallow_parsed
|
|-
|wesnoth.debug
|wesnoth.wml.debug
|
|-
|helper.set_wml_tag_metatable
|wesnoth.wml.get_tag_creator
|
|}

== interface ==
APIs for dealing with the main game interface
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.delay
|wesnoth.interface.delay
|
|-
|wesnoth.float_label
|wesnoth.interface.float_label
|
|-
|wesnoth.select_hex
|wesnoth.interface.select_hex
|
|-
|wesnoth.select_unit
|wesnoth.interface.select_unit
|
|-
|wesnoth.highlight_hex
|wesnoth.interface.highlight_hex
|
|-
|wesnoth.deselect_hex
|wesnoth.interface.deselect_hex
|
|-
|wesnoth.get_selected_tile
|wesnoth.map.get_selected_hex
|
|-
|wesnoth.scroll_to_tile
|wesnoth.interface.scroll_to_hex
|
|-
|wesnoth.lock_view
|wesnoth.interface.lock
|
|-
|wesnoth.view_locked
|wesnoth.interface.is_locked
|
|-
|wesnoth.is_skipping_messages
|wesnoth.interface.is_skipping_messages
|
|-
|wesnoth.skip_messages
|wesnoth.interface.skip_messages
|
|-
|wesnoth.add_tile_overlay
|wesnoth.interface.add_hex_overlay
|
|-
|wesnoth.remove_tile_overlay
|wesnoth.interface.remove_hex_overlay
|
|-
|items.place_image
|wesnoth.interface.add_item_image
|
|-
|items.place_halo
|wesnoth.interface.add_item_halo
|
|-
|items.remove
|wesnoth.interface.remove_item
|
|-
|wesnoth.theme_items
|wesnoth.interface.game_display
|
|-
|helper.move_unit_fake
|wesnoth.interface.move_unit_fake
|
|}

== dialog ==
GUI2 APIs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.show_message_dialog
|wesnoth.dialog.show_message
|
|-
|wesnoth.show_popup_dialog
|wesnoth.dialog.show_popup
|
|-
|wesnoth.show_dialog
|wesnoth.dialog.show
|
|-
|wesnoth.set_dialog_value
|wesnoth.dialog.set_value
|
|-
|wesnoth.get_dialog_value
|wesnoth.dialog.get_value
|
|-
|wesnoth.set_dialog_active
|wesnoth.dialog.set_active
|
|-
|wesnoth.set_dialog_callback
|wesnoth.dialog.set_callback
|
|-
|wesnoth.set_dialog_markup
|wesnoth.dialog.set_markup
|
|-
|wesnoth.set_dialog_focus
|wesnoth.dialog.set_focus
|
|-
|wesnoth.set_dialog_visible
|wesnoth.dialog.set_visible
|
|-
|wesnoth.set_dialog_canvas
|wesnoth.dialog.set_canvas
|
|-
|wesnoth.add_dialog_tree_node
|wesnoth.dialog.add_tree_node
|
|-
|wesnoth.remove_dialog_item
|wesnoth.dialog.remove_item
|
|-
|wesnoth.get_displayed_unit
|wesnoth.dialog.get_displayed_unit
|
|-
|helper.get_user_choice
|wesnoth.dialog.get_user_choice
|
|}

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

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

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

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

== unit ==
APIs for working with unit data
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_units
|wesnoth.unit.get_array
|
|-
|wesnoth.get_unit
|wesnoth.unit.get
|
|-
|wesnoth.match_unit
|wesnoth.unit.matches
|
|-
|wesnoth.put_unit
|wesnoth.unit.put
|
|-
|wesnoth.erase_unit
|wesnoth.unit.erase
|
|-
|wesnoth.get_recall_units
|wesnoth.unit.get_recall
|
|-
|wesnoth.put_recall_unit
|wesnoth.unit.put_recall
|
|-
|wesnoth.create_unit
|wesnoth.unit.create
|
|-
|wesnoth.copy_unit
|wesnoth.unit.copy
|
|-
|wesnoth.extract_unit
|wesnoth.unit.extract
|
|-
|wesnoth.advance_unit
|wesnoth.unit.advance
|
|-
|wesnoth.add_modification
|wesnoth.unit.add_modification
|
|-
|wesnoth.unit_resistance
|wesnoth.unit.resistance
|
|-
|wesnoth.unit_defense
|wesnoth.unit.defense
|
|-
|wesnoth.unit_movement_cost
|wesnoth.unit.movement_cost
|
|-
|wesnoth.unit_vision_cost
|wesnoth.unit.vision_cost
|
|-
|wesnoth.unit_jamming_cost
|wesnoth.unit.jamming_cost
|
|-
|wesnoth.unit_ability
|wesnoth.unit.ability
|
|-
|wesnoth.unit_types
|wesnoth.unit.types
|
|-
|wesnoth.transform_unit
|wesnoth.unit.transform
|
|-
|helper.modify_unit
|wesnoth.unit.modify_unit
|
|}

== side ==
APIs for working with sides
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.sides
|wesnoth.side.proxy
|
|-
|wesnoth.get_sides
|wesnoth.side.get_all
|
|-
|wesnoth.is_enemy
|wesnoth.side.is_enemy
|
|-
|wesnoth.match_side
|wesnoth.side.matches
|
|-
|helper.all_teams
|wesnoth.side.iterator
|
|}

== file ==
APIs for working with files
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.dofile
|wesnoth.file.run
|
|-
|wesnoth.require
|wesnoth.file.require
|
|-
|wesnoth.read_file
|wesnoth.file.read
|
|-
|wesnoth.get_image_size
|wesnoth.file.image_size
|
|-
|wesnoth.have_file
|wesnoth.file.exists
|
|}

== location_set ==
Class for working with sets of locations

Since this is already nicely compartmentalized, the only proposed change is to move it to wesnoth.location_set rather than being global.

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

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

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

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

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

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

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

LuaWML/Reorganization

2016-11-06T19:21:20Z

DeFender1031: /* side */ that's clearly a typo

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

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

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

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

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

The categories and names being proposed are as follows:

== variable ==
APIs for dealing with WML variables
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_variable
|wesnoth.variable.get
|
|-
|wesnoth.set_variable
|wesnoth.variable.set
|
|-
|wesnoth.get_all_vars
|wesnoth.variable.get_all
|
|-
|helper.set_wml_var_metatable
|wesnoth.variable.get_proxy
|
|-
|helper.get_variable_array
|wesnoth.variable.get_array
|
|-
|helper.set_variable_array
|wesnoth.variable.set_array
|
|-
|helper.get_variable_proxy_array
|wesnoth.variable.get_proxy_array
|
|}

== wml ==
APIs for dealing with wml tables and vconfigs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|helper.get_child
|wesnoth.wml.get_child
|
|-
|helper.get_nth_child
|wesnoth.wml.get_nth_child
|
|-
|helper.child_count
|wesnoth.wml.child_count
|
|-
|helper.child_range
|wesnoth.wml.child_range
|
|-
|helper.child_array
|wesnoth.wml.child_array
|
|-
|wesnoth.tovconfig
|wesnoth.wml.tovconfig
|
|-
|helper.literal
|wesnoth.wml.literal
|
|-
|helper.parsed
|wesnoth.wml.parsed
|
|-
|helper.shallow_literal
|wesnoth.wml.shallow_literal
|
|-
|helper.shallow_parsed
|wesnoth.wml.shallow_parsed
|
|-
|wesnoth.debug
|wesnoth.wml.debug
|
|-
|helper.set_wml_tag_metatable
|wesnoth.wml.get_tag_creator
|
|}

== interface ==
APIs for dealing with the main game interface
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.delay
|wesnoth.interface.delay
|
|-
|wesnoth.float_label
|wesnoth.interface.float_label
|
|-
|wesnoth.select_hex
|wesnoth.interface.select_hex
|
|-
|wesnoth.select_unit
|wesnoth.interface.select_unit
|
|-
|wesnoth.highlight_hex
|wesnoth.interface.highlight_hex
|
|-
|wesnoth.deselect_hex
|wesnoth.interface.deselect_hex
|
|-
|wesnoth.get_selected_tile
|wesnoth.map.get_selected_hex
|
|-
|wesnoth.scroll_to_tile
|wesnoth.interface.scroll_to_hex
|
|-
|wesnoth.lock_view
|wesnoth.interface.lock
|
|-
|wesnoth.view_locked
|wesnoth.interface.is_locked
|
|-
|wesnoth.is_skipping_messages
|wesnoth.interface.is_skipping_messages
|
|-
|wesnoth.skip_messages
|wesnoth.interface.skip_messages
|
|-
|wesnoth.add_tile_overlay
|wesnoth.interface.add_hex_overlay
|
|-
|wesnoth.remove_tile_overlay
|wesnoth.interface.remove_hex_overlay
|
|-
|items.place_image
|wesnoth.interface.add_item_image
|
|-
|items.place_halo
|wesnoth.interface.add_item_halo
|
|-
|items.remove
|wesnoth.interface.remove_item
|
|-
|wesnoth.theme_items
|wesnoth.interface.game_display
|
|-
|helper.move_unit_fake
|wesnoth.interface.move_unit_fake
|
|}

== dialog ==
GUI2 APIs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.show_message_dialog
|wesnoth.dialog.show_message
|
|-
|wesnoth.show_popup_dialog
|wesnoth.dialog.show_popup
|
|-
|wesnoth.show_dialog
|wesnoth.dialog.show
|
|-
|wesnoth.set_dialog_value
|wesnoth.dialog.set_value
|
|-
|wesnoth.get_dialog_value
|wesnoth.dialog.get_value
|
|-
|wesnoth.set_dialog_active
|wesnoth.dialog.set_active
|
|-
|wesnoth.set_dialog_callback
|wesnoth.dialog.set_callback
|
|-
|wesnoth.set_dialog_markup
|wesnoth.dialog.set_markup
|
|-
|wesnoth.set_dialog_focus
|wesnoth.dialog.set_focus
|
|-
|wesnoth.set_dialog_visible
|wesnoth.dialog.set_visible
|
|-
|wesnoth.set_dialog_canvas
|wesnoth.dialog.set_canvas
|
|-
|wesnoth.add_dialog_tree_node
|wesnoth.dialog.add_tree_node
|
|-
|wesnoth.remove_dialog_item
|wesnoth.dialog.remove_item
|
|-
|wesnoth.get_displayed_unit
|wesnoth.dialog.get_displayed_unit
|
|-
|helper.get_user_choice
|wesnoth.dialog.get_user_choice
|
|}

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

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

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

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

== unit ==
APIs for working with unit data
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_units
|wesnoth.unit.get_array
|
|-
|wesnoth.get_unit
|wesnoth.unit.get
|
|-
|wesnoth.match_unit
|wesnoth.unit.matches
|
|-
|wesnoth.put_unit
|wesnoth.unit.put
|
|-
|wesnoth.erase_unit
|wesnoth.unit.erase
|
|-
|wesnoth.get_recall_units
|wesnoth.unit.get_recall
|
|-
|wesnoth.put_recall_unit
|wesnoth.unit.put_recall
|
|-
|wesnoth.create_unit
|wesnoth.unit.create
|
|-
|wesnoth.copy_unit
|wesnoth.unit.copy
|
|-
|wesnoth.extract_unit
|wesnoth.unit.extract
|
|-
|wesnoth.advance_unit
|wesnoth.unit.advance
|
|-
|wesnoth.add_modification
|wesnoth.unit.add_modification
|
|-
|wesnoth.unit_resistance
|wesnoth.unit.resistance
|
|-
|wesnoth.unit_defense
|wesnoth.unit.defense
|
|-
|wesnoth.unit_movement_cost
|wesnoth.unit.movement_cost
|
|-
|wesnoth.unit_vision_cost
|wesnoth.unit.vision_cost
|
|-
|wesnoth.unit_jamming_cost
|wesnoth.unit.jamming_cost
|
|-
|wesnoth.unit_ability
|wesnoth.unit.ability
|
|-
|wesnoth.unit_types
|wesnoth.unit.types
|
|-
|wesnoth.transform_unit
|wesnoth.unit.transform
|
|-
|helper.modify_unit
|wesnoth.unit.modify_unit
|
|}

== side ==
APIs for working with sides
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.sides
|wesnoth.side.proxy
|
|-
|wesnoth.get_sides
|wesnoth.side.get_all
|
|-
|wesnoth.is_enemy
|wesnoth.side.is_enemy
|
|-
|wesnoth.match_side
|wesnoth.side.matches
|
|-
|helper.all_teams
|wesnoth.side.iterator
|
|}

== file ==
APIs for working with files
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.dofile
|wesnoth.file.run
|
|-
|wesnoth.require
|wesnoth.file.require
|
|-
|wesnoth.read_file
|wesnoth.file.read
|
|-
|wesnoth.get_image_size
|wesnoth.file.image_size
|
|-
|wesnoth.have_file
|wesnoth.file.exists
|
|}

== location_set ==
Class for working with sets of locations

Since this is already nicely compartmentalized, the only proposed change is to move it to wesnoth.location_set rather than being global.

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

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

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

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

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

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

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

LuaWML/Reorganization

2016-11-06T01:40:13Z

DeFender1031: analogous to namespaces

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

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

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

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

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

The categories and names being proposed are as follows:

== variable ==
APIs for dealing with WML variables
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_variable
|wesnoth.variable.get
|
|-
|wesnoth.set_variable
|wesnoth.variable.set
|
|-
|wesnoth.get_all_vars
|wesnoth.variable.get_all
|
|-
|helper.set_wml_var_metatable
|wesnoth.variable.get_proxy
|
|-
|helper.get_variable_array
|wesnoth.variable.get_array
|
|-
|helper.set_variable_array
|wesnoth.variable.set_array
|
|-
|helper.get_variable_proxy_array
|wesnoth.variable.get_proxy_array
|
|}

== wml ==
APIs for dealing with wml tables and vconfigs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|helper.get_child
|wesnoth.wml.get_child
|
|-
|helper.get_nth_child
|wesnoth.wml.get_nth_child
|
|-
|helper.child_count
|wesnoth.wml.child_count
|
|-
|helper.child_range
|wesnoth.wml.child_range
|
|-
|helper.child_array
|wesnoth.wml.child_array
|
|-
|wesnoth.tovconfig
|wesnoth.wml.tovconfig
|
|-
|helper.literal
|wesnoth.wml.literal
|
|-
|helper.parsed
|wesnoth.wml.parsed
|
|-
|helper.shallow_literal
|wesnoth.wml.shallow_literal
|
|-
|helper.shallow_parsed
|wesnoth.wml.shallow_parsed
|
|-
|wesnoth.debug
|wesnoth.wml.debug
|
|-
|helper.set_wml_tag_metatable
|wesnoth.wml.get_tag_creator
|
|}

== interface ==
APIs for dealing with the main game interface
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.delay
|wesnoth.interface.delay
|
|-
|wesnoth.float_label
|wesnoth.interface.float_label
|
|-
|wesnoth.select_hex
|wesnoth.interface.select_hex
|
|-
|wesnoth.select_unit
|wesnoth.interface.select_unit
|
|-
|wesnoth.highlight_hex
|wesnoth.interface.highlight_hex
|
|-
|wesnoth.deselect_hex
|wesnoth.interface.deselect_hex
|
|-
|wesnoth.get_selected_tile
|wesnoth.map.get_selected_hex
|
|-
|wesnoth.scroll_to_tile
|wesnoth.interface.scroll_to_hex
|
|-
|wesnoth.lock_view
|wesnoth.interface.lock
|
|-
|wesnoth.view_locked
|wesnoth.interface.is_locked
|
|-
|wesnoth.is_skipping_messages
|wesnoth.interface.is_skipping_messages
|
|-
|wesnoth.skip_messages
|wesnoth.interface.skip_messages
|
|-
|wesnoth.add_tile_overlay
|wesnoth.interface.add_hex_overlay
|
|-
|wesnoth.remove_tile_overlay
|wesnoth.interface.remove_hex_overlay
|
|-
|items.place_image
|wesnoth.interface.add_item_image
|
|-
|items.place_halo
|wesnoth.interface.add_item_halo
|
|-
|items.remove
|wesnoth.interface.remove_item
|
|-
|wesnoth.theme_items
|wesnoth.interface.game_display
|
|-
|helper.move_unit_fake
|wesnoth.interface.move_unit_fake
|
|}

== dialog ==
GUI2 APIs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.show_message_dialog
|wesnoth.dialog.show_message
|
|-
|wesnoth.show_popup_dialog
|wesnoth.dialog.show_popup
|
|-
|wesnoth.show_dialog
|wesnoth.dialog.show
|
|-
|wesnoth.set_dialog_value
|wesnoth.dialog.set_value
|
|-
|wesnoth.get_dialog_value
|wesnoth.dialog.get_value
|
|-
|wesnoth.set_dialog_active
|wesnoth.dialog.set_active
|
|-
|wesnoth.set_dialog_callback
|wesnoth.dialog.set_callback
|
|-
|wesnoth.set_dialog_markup
|wesnoth.dialog.set_markup
|
|-
|wesnoth.set_dialog_focus
|wesnoth.dialog.set_focus
|
|-
|wesnoth.set_dialog_visible
|wesnoth.dialog.set_visible
|
|-
|wesnoth.set_dialog_canvas
|wesnoth.dialog.set_canvas
|
|-
|wesnoth.add_dialog_tree_node
|wesnoth.dialog.add_tree_node
|
|-
|wesnoth.remove_dialog_item
|wesnoth.dialog.remove_item
|
|-
|wesnoth.get_displayed_unit
|wesnoth.dialog.get_displayed_unit
|
|-
|helper.get_user_choice
|wesnoth.dialog.get_user_choice
|
|}

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

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

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

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

== unit ==
APIs for working with unit data
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_units
|wesnoth.unit.get_array
|
|-
|wesnoth.get_unit
|wesnoth.unit.get
|
|-
|wesnoth.match_unit
|wesnoth.unit.matches
|
|-
|wesnoth.put_unit
|wesnoth.unit.put
|
|-
|wesnoth.erase_unit
|wesnoth.unit.erase
|
|-
|wesnoth.get_recall_units
|wesnoth.unit.get_recall
|
|-
|wesnoth.put_recall_unit
|wesnoth.unit.put_recall
|
|-
|wesnoth.create_unit
|wesnoth.unit.create
|
|-
|wesnoth.copy_unit
|wesnoth.unit.copy
|
|-
|wesnoth.extract_unit
|wesnoth.unit.extract
|
|-
|wesnoth.advance_unit
|wesnoth.unit.advance
|
|-
|wesnoth.add_modification
|wesnoth.unit.add_modification
|
|-
|wesnoth.unit_resistance
|wesnoth.unit.resistance
|
|-
|wesnoth.unit_defense
|wesnoth.unit.defense
|
|-
|wesnoth.unit_movement_cost
|wesnoth.unit.movement_cost
|
|-
|wesnoth.unit_vision_cost
|wesnoth.unit.vision_cost
|
|-
|wesnoth.unit_jamming_cost
|wesnoth.unit.jamming_cost
|
|-
|wesnoth.unit_ability
|wesnoth.unit.ability
|
|-
|wesnoth.unit_types
|wesnoth.unit.types
|
|-
|wesnoth.transform_unit
|wesnoth.unit.transform
|
|-
|helper.modify_unit
|wesnoth.unit.modify_unit
|
|}

== side ==
APIs for working with sides
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.sides
|wesnoth.side.proxy
|
|-
|wesnoth.get_sides
|wesnoth.side.get
|
|-
|wesnoth.is_enemy
|wesnoth.side.is_enemy
|
|-
|wesnoth.match_side
|wesnoth.side.matches
|
|-
|helper.all_teams
|wesnoth.side.iterator
|
|}

== file ==
APIs for working with files
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.dofile
|wesnoth.file.run
|
|-
|wesnoth.require
|wesnoth.file.require
|
|-
|wesnoth.read_file
|wesnoth.file.read
|
|-
|wesnoth.get_image_size
|wesnoth.file.image_size
|
|-
|wesnoth.have_file
|wesnoth.file.exists
|
|}

== location_set ==
Class for working with sets of locations

Since this is already nicely compartmentalized, the only proposed change is to move it to wesnoth.location_set rather than being global.

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

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

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

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

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

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

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

LuaWML/Reorganization

2016-11-05T22:45:45Z

DeFender1031: /* action */ no idea how that lost its prefix

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

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

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

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

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

The categories and names being proposed are as follows:

== variable ==
APIs for dealing with WML variables
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_variable
|wesnoth.variable.get
|
|-
|wesnoth.set_variable
|wesnoth.variable.set
|
|-
|wesnoth.get_all_vars
|wesnoth.variable.get_all
|
|-
|helper.set_wml_var_metatable
|wesnoth.variable.get_proxy
|
|-
|helper.get_variable_array
|wesnoth.variable.get_array
|
|-
|helper.set_variable_array
|wesnoth.variable.set_array
|
|-
|helper.get_variable_proxy_array
|wesnoth.variable.get_proxy_array
|
|}

== wml ==
APIs for dealing with wml tables and vconfigs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|helper.get_child
|wesnoth.wml.get_child
|
|-
|helper.get_nth_child
|wesnoth.wml.get_nth_child
|
|-
|helper.child_count
|wesnoth.wml.child_count
|
|-
|helper.child_range
|wesnoth.wml.child_range
|
|-
|helper.child_array
|wesnoth.wml.child_array
|
|-
|wesnoth.tovconfig
|wesnoth.wml.tovconfig
|
|-
|helper.literal
|wesnoth.wml.literal
|
|-
|helper.parsed
|wesnoth.wml.parsed
|
|-
|helper.shallow_literal
|wesnoth.wml.shallow_literal
|
|-
|helper.shallow_parsed
|wesnoth.wml.shallow_parsed
|
|-
|wesnoth.debug
|wesnoth.wml.debug
|
|-
|helper.set_wml_tag_metatable
|wesnoth.wml.get_tag_creator
|
|}

== interface ==
APIs for dealing with the main game interface
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.delay
|wesnoth.interface.delay
|
|-
|wesnoth.float_label
|wesnoth.interface.float_label
|
|-
|wesnoth.select_hex
|wesnoth.interface.select_hex
|
|-
|wesnoth.select_unit
|wesnoth.interface.select_unit
|
|-
|wesnoth.highlight_hex
|wesnoth.interface.highlight_hex
|
|-
|wesnoth.deselect_hex
|wesnoth.interface.deselect_hex
|
|-
|wesnoth.get_selected_tile
|wesnoth.map.get_selected_hex
|
|-
|wesnoth.scroll_to_tile
|wesnoth.interface.scroll_to_hex
|
|-
|wesnoth.lock_view
|wesnoth.interface.lock
|
|-
|wesnoth.view_locked
|wesnoth.interface.is_locked
|
|-
|wesnoth.is_skipping_messages
|wesnoth.interface.is_skipping_messages
|
|-
|wesnoth.skip_messages
|wesnoth.interface.skip_messages
|
|-
|wesnoth.add_tile_overlay
|wesnoth.interface.add_hex_overlay
|
|-
|wesnoth.remove_tile_overlay
|wesnoth.interface.remove_hex_overlay
|
|-
|items.place_image
|wesnoth.interface.add_item_image
|
|-
|items.place_halo
|wesnoth.interface.add_item_halo
|
|-
|items.remove
|wesnoth.interface.remove_item
|
|-
|wesnoth.theme_items
|wesnoth.interface.game_display
|
|-
|helper.move_unit_fake
|wesnoth.interface.move_unit_fake
|
|}

== dialog ==
GUI2 APIs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.show_message_dialog
|wesnoth.dialog.show_message
|
|-
|wesnoth.show_popup_dialog
|wesnoth.dialog.show_popup
|
|-
|wesnoth.show_dialog
|wesnoth.dialog.show
|
|-
|wesnoth.set_dialog_value
|wesnoth.dialog.set_value
|
|-
|wesnoth.get_dialog_value
|wesnoth.dialog.get_value
|
|-
|wesnoth.set_dialog_active
|wesnoth.dialog.set_active
|
|-
|wesnoth.set_dialog_callback
|wesnoth.dialog.set_callback
|
|-
|wesnoth.set_dialog_markup
|wesnoth.dialog.set_markup
|
|-
|wesnoth.set_dialog_focus
|wesnoth.dialog.set_focus
|
|-
|wesnoth.set_dialog_visible
|wesnoth.dialog.set_visible
|
|-
|wesnoth.set_dialog_canvas
|wesnoth.dialog.set_canvas
|
|-
|wesnoth.add_dialog_tree_node
|wesnoth.dialog.add_tree_node
|
|-
|wesnoth.remove_dialog_item
|wesnoth.dialog.remove_item
|
|-
|wesnoth.get_displayed_unit
|wesnoth.dialog.get_displayed_unit
|
|-
|helper.get_user_choice
|wesnoth.dialog.get_user_choice
|
|}

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

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

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

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

== unit ==
APIs for working with unit data
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_units
|wesnoth.unit.get_array
|
|-
|wesnoth.get_unit
|wesnoth.unit.get
|
|-
|wesnoth.match_unit
|wesnoth.unit.matches
|
|-
|wesnoth.put_unit
|wesnoth.unit.put
|
|-
|wesnoth.erase_unit
|wesnoth.unit.erase
|
|-
|wesnoth.get_recall_units
|wesnoth.unit.get_recall
|
|-
|wesnoth.put_recall_unit
|wesnoth.unit.put_recall
|
|-
|wesnoth.create_unit
|wesnoth.unit.create
|
|-
|wesnoth.copy_unit
|wesnoth.unit.copy
|
|-
|wesnoth.extract_unit
|wesnoth.unit.extract
|
|-
|wesnoth.advance_unit
|wesnoth.unit.advance
|
|-
|wesnoth.add_modification
|wesnoth.unit.add_modification
|
|-
|wesnoth.unit_resistance
|wesnoth.unit.resistance
|
|-
|wesnoth.unit_defense
|wesnoth.unit.defense
|
|-
|wesnoth.unit_movement_cost
|wesnoth.unit.movement_cost
|
|-
|wesnoth.unit_vision_cost
|wesnoth.unit.vision_cost
|
|-
|wesnoth.unit_jamming_cost
|wesnoth.unit.jamming_cost
|
|-
|wesnoth.unit_ability
|wesnoth.unit.ability
|
|-
|wesnoth.unit_types
|wesnoth.unit.types
|
|-
|wesnoth.transform_unit
|wesnoth.unit.transform
|
|-
|helper.modify_unit
|wesnoth.unit.modify_unit
|
|}

== side ==
APIs for working with sides
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.sides
|wesnoth.side.proxy
|
|-
|wesnoth.get_sides
|wesnoth.side.get
|
|-
|wesnoth.is_enemy
|wesnoth.side.is_enemy
|
|-
|wesnoth.match_side
|wesnoth.side.matches
|
|-
|helper.all_teams
|wesnoth.side.iterator
|
|}

== file ==
APIs for working with files
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.dofile
|wesnoth.file.run
|
|-
|wesnoth.require
|wesnoth.file.require
|
|-
|wesnoth.read_file
|wesnoth.file.read
|
|-
|wesnoth.get_image_size
|wesnoth.file.image_size
|
|-
|wesnoth.have_file
|wesnoth.file.exists
|
|}

== location_set ==
Class for working with sets of locations

Since this is already nicely compartmentalized, the only proposed change is to move it to wesnoth.location_set rather than being global.

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

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

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

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

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

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

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

LuaWML/Reorganization

2016-11-05T22:42:25Z

DeFender1031: Well, let's see where this goes.

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

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

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

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

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

The categories and names being proposed are as follows:

== variable ==
APIs for dealing with WML variables
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_variable
|wesnoth.variable.get
|
|-
|wesnoth.set_variable
|wesnoth.variable.set
|
|-
|wesnoth.get_all_vars
|wesnoth.variable.get_all
|
|-
|helper.set_wml_var_metatable
|wesnoth.variable.get_proxy
|
|-
|helper.get_variable_array
|wesnoth.variable.get_array
|
|-
|helper.set_variable_array
|wesnoth.variable.set_array
|
|-
|helper.get_variable_proxy_array
|wesnoth.variable.get_proxy_array
|
|}

== wml ==
APIs for dealing with wml tables and vconfigs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|helper.get_child
|wesnoth.wml.get_child
|
|-
|helper.get_nth_child
|wesnoth.wml.get_nth_child
|
|-
|helper.child_count
|wesnoth.wml.child_count
|
|-
|helper.child_range
|wesnoth.wml.child_range
|
|-
|helper.child_array
|wesnoth.wml.child_array
|
|-
|wesnoth.tovconfig
|wesnoth.wml.tovconfig
|
|-
|helper.literal
|wesnoth.wml.literal
|
|-
|helper.parsed
|wesnoth.wml.parsed
|
|-
|helper.shallow_literal
|wesnoth.wml.shallow_literal
|
|-
|helper.shallow_parsed
|wesnoth.wml.shallow_parsed
|
|-
|wesnoth.debug
|wesnoth.wml.debug
|
|-
|helper.set_wml_tag_metatable
|wesnoth.wml.get_tag_creator
|
|}

== interface ==
APIs for dealing with the main game interface
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.delay
|wesnoth.interface.delay
|
|-
|wesnoth.float_label
|wesnoth.interface.float_label
|
|-
|wesnoth.select_hex
|wesnoth.interface.select_hex
|
|-
|wesnoth.select_unit
|wesnoth.interface.select_unit
|
|-
|wesnoth.highlight_hex
|wesnoth.interface.highlight_hex
|
|-
|wesnoth.deselect_hex
|wesnoth.interface.deselect_hex
|
|-
|wesnoth.get_selected_tile
|wesnoth.map.get_selected_hex
|
|-
|wesnoth.scroll_to_tile
|wesnoth.interface.scroll_to_hex
|
|-
|wesnoth.lock_view
|wesnoth.interface.lock
|
|-
|wesnoth.view_locked
|wesnoth.interface.is_locked
|
|-
|wesnoth.is_skipping_messages
|wesnoth.interface.is_skipping_messages
|
|-
|wesnoth.skip_messages
|wesnoth.interface.skip_messages
|
|-
|wesnoth.add_tile_overlay
|wesnoth.interface.add_hex_overlay
|
|-
|wesnoth.remove_tile_overlay
|wesnoth.interface.remove_hex_overlay
|
|-
|items.place_image
|wesnoth.interface.add_item_image
|
|-
|items.place_halo
|wesnoth.interface.add_item_halo
|
|-
|items.remove
|wesnoth.interface.remove_item
|
|-
|wesnoth.theme_items
|wesnoth.interface.game_display
|
|-
|helper.move_unit_fake
|wesnoth.interface.move_unit_fake
|
|}

== dialog ==
GUI2 APIs
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.show_message_dialog
|wesnoth.dialog.show_message
|
|-
|wesnoth.show_popup_dialog
|wesnoth.dialog.show_popup
|
|-
|wesnoth.show_dialog
|wesnoth.dialog.show
|
|-
|wesnoth.set_dialog_value
|wesnoth.dialog.set_value
|
|-
|wesnoth.get_dialog_value
|wesnoth.dialog.get_value
|
|-
|wesnoth.set_dialog_active
|wesnoth.dialog.set_active
|
|-
|wesnoth.set_dialog_callback
|wesnoth.dialog.set_callback
|
|-
|wesnoth.set_dialog_markup
|wesnoth.dialog.set_markup
|
|-
|wesnoth.set_dialog_focus
|wesnoth.dialog.set_focus
|
|-
|wesnoth.set_dialog_visible
|wesnoth.dialog.set_visible
|
|-
|wesnoth.set_dialog_canvas
|wesnoth.dialog.set_canvas
|
|-
|wesnoth.add_dialog_tree_node
|wesnoth.dialog.add_tree_node
|
|-
|wesnoth.remove_dialog_item
|wesnoth.dialog.remove_item
|
|-
|wesnoth.get_displayed_unit
|wesnoth.dialog.get_displayed_unit
|
|-
|helper.get_user_choice
|wesnoth.dialog.get_user_choice
|
|}

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

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

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

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

== unit ==
APIs for working with unit data
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.get_units
|wesnoth.unit.get_array
|
|-
|wesnoth.get_unit
|wesnoth.unit.get
|
|-
|wesnoth.match_unit
|wesnoth.unit.matches
|
|-
|wesnoth.put_unit
|wesnoth.unit.put
|
|-
|wesnoth.erase_unit
|wesnoth.unit.erase
|
|-
|wesnoth.get_recall_units
|wesnoth.unit.get_recall
|
|-
|wesnoth.put_recall_unit
|wesnoth.unit.put_recall
|
|-
|wesnoth.create_unit
|wesnoth.unit.create
|
|-
|wesnoth.copy_unit
|wesnoth.unit.copy
|
|-
|wesnoth.extract_unit
|wesnoth.unit.extract
|
|-
|wesnoth.advance_unit
|wesnoth.unit.advance
|
|-
|wesnoth.add_modification
|wesnoth.unit.add_modification
|
|-
|wesnoth.unit_resistance
|wesnoth.unit.resistance
|
|-
|wesnoth.unit_defense
|wesnoth.unit.defense
|
|-
|wesnoth.unit_movement_cost
|wesnoth.unit.movement_cost
|
|-
|wesnoth.unit_vision_cost
|wesnoth.unit.vision_cost
|
|-
|wesnoth.unit_jamming_cost
|wesnoth.unit.jamming_cost
|
|-
|wesnoth.unit_ability
|wesnoth.unit.ability
|
|-
|wesnoth.unit_types
|wesnoth.unit.types
|
|-
|wesnoth.transform_unit
|wesnoth.unit.transform
|
|-
|helper.modify_unit
|wesnoth.unit.modify_unit
|
|}

== side ==
APIs for working with sides
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.sides
|wesnoth.side.proxy
|
|-
|wesnoth.get_sides
|wesnoth.side.get
|
|-
|wesnoth.is_enemy
|wesnoth.side.is_enemy
|
|-
|wesnoth.match_side
|wesnoth.side.matches
|
|-
|helper.all_teams
|wesnoth.side.iterator
|
|}

== file ==
APIs for working with files
{| border=1
!Old Access Point
!New Access Point
!Comments
|-
|wesnoth.dofile
|wesnoth.file.run
|
|-
|wesnoth.require
|wesnoth.file.require
|
|-
|wesnoth.read_file
|wesnoth.file.read
|
|-
|wesnoth.get_image_size
|wesnoth.file.image_size
|
|-
|wesnoth.have_file
|wesnoth.file.exists
|
|}

== location_set ==
Class for working with sets of locations

Since this is already nicely compartmentalized, the only proposed change is to move it to wesnoth.location_set rather than being global.

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

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

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

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

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

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

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

SingleUnitWML

2016-10-29T20:19:31Z

DeFender1031: /* Unit Data */ a few more things that can be overridden (put usually shouldn't)

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

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

*'''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''': Can be used to modify existing values.

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

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

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

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

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

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T19:27:56Z

DeFender1031: /* Creation Options */ let's move this down so those that affect the data will be together and those which affect how the creation is done are together.

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

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

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

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

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

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

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T19:26:44Z

DeFender1031: /* Creation Options */ this only works in an event

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

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

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

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.

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

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

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

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T19:16:28Z

DeFender1031: /* Unit Data */ add level

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

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.

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

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

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

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T19:13:52Z

DeFender1031: /* Creation Options */ reword

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

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.

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

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

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

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T19:10:09Z

DeFender1031: that's not how you anchor...

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

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.

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

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

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T19:08:43Z

DeFender1031: add a summary of the categories of data to the intro

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

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.

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

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

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T18:54:17Z

DeFender1031: /* Unit Data */ correct this.

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

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

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

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

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

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

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.

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

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

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

== See Also ==

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

[[Category:WML Reference]]

SingleUnitWML

2016-10-29T18:43:57Z

DeFender1031: major edit restructuring the page into persistent, state, and creation data, also some rewording here and there to clarify some things and remove inaccuracies.

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

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

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

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

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

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable. Mandatory except when the [unit] tag appears inside a [side], in which case it defaults to that side.

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

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

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).

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

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

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

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

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.

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

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

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

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

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

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

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

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

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

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

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

* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).

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

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

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

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

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

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

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

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

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

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

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

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

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

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

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.

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

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

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

== See Also ==

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

[[Category:WML Reference]]

DirectActionsWML

2016-10-29T17:04:36Z

DeFender1031: /* [unit] */ no reason for this to be singled out here. Either all parameters that affect how the unit is created should be here, or none of them. Also, make this more accurate.

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

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

The following tags are actions:

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

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

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

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

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

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

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

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the position to teleport to. If that position is not empty, some other location will be chosen.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

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

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

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

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

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

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

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) floating text to display above the unit, such as a damage amount
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
* '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

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

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

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

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit.
* '''extra_recruit''': the types of units that the side can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

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

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

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

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

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't take any arguments.

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

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''': if 'yes', displays the unit dying (fading away).
* '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.

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

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

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter.
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this to work around a bug when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP, SPECIAL_BACKSTAB, or any other effect that uses variable substitution or when using [effect][filter] with a $this_unit (see http://gna.org/bugs/index.php?18893).
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

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

=== [transform_unit] ===
Transforms every unit matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

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

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

=== [object] ===
Gives some unit an object which modifies their stats in some way.
* '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per scenario. In a campaign objects with the same id can be assigned once per scenario. For filtering objects, custom key can be used, such as item_id.
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} Enables the above behaviour. If set to no, the object ID is not used to prevent the object from being taken more than once, but can still be used to remove it using [remove_object].
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this to work around a bug when adding ABILITY_TELEPORT (or any other effect that uses variable substitution) via an [object] or when using [object][effect][filter]with a $this_unit (see http://gna.org/bugs/index.php?18893). {{DevFeature1.13|5}} ABILITY_LEADERSHIP and SPECIAL_BACKSTAB now also use variable substitution and thus require this to be set to "yes".
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed)
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to true, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
* '''no_write''': {{DevFeature1.13|1}} (bool, default false). If true, the contents of [effect] will be applied to the relevant unit, but the [object] tag will not be written to unit.modifications. This renders duration= irrelevant. {{DevFeature1.13|6}} This is deprecated and will probably be removed in the release after 1.13.6. To get the same effect, use [effect] tags in [modify_unit].

=== [remove_object] ===

{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units matching the filter have matching objects removed
* '''object_id''': The id of the object to be removed.

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

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

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

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

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

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

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

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

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

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".

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

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

''Example:'' (caves in parts of a map)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [remove_time_area] ===

{{DevFeature1.13|2}}

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

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

=== [replace_map] ===

Replaces the entire map.
* '''map''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

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

=== [tunnel] ===

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

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

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

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

=== [do_command] ===

{{DevFeature1.13|0}}

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

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it.

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

This command should always be replay safe.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

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

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

== See Also ==

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

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

UnitTypeWML

2016-10-29T16:46:13Z

DeFender1031: this is documented on game config but not here.

{{WML Tags}}

__TOC__

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:
* '''[advancefrom]''': 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. 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.
* '''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.
* '''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.
* '''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.
* '''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.
* '''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.
* '''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.
* '''hide_help''': determines if the unit type will appear in the in-game help. Possible values ''true'' and ''false'', defaults to ''false''.
* '''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'' should consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
::WARNING : characters "$", "&", "*", "-", "(" and ")" are illegal for use in the unit type id and must be avoided because they might lead to corrupted saved games
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctionWML#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''':(translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
* '''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. 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, khalifate, 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.
* '''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''': Overwrites the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overwrites the attribute in ([[GameConfigWML]]).

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

== 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}}).
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'melee'(default) displays "melee", while 'ranged' displays "ranged". Range can be anything. Standard values are now "melee" and "ranged". From now on, ''short'' and ''long'' will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable.
** '''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; negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon offensively; 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.
** '''attack_weight''': helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack
** '''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
For the weight settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).

== Other tags ==
* '''[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. Attributes in this unit overwrite the copy. Tags modify the corresponding tag of the original, so for example the first '''[attack]''' tag in the derived unit would modify the first attack of the base unit rather than defining a new attack. 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.

* '''[portrait]''': Describes a unit portrait for dialogue. However, generally you should use the profile key instead; [portrait] is mostly for internal use.
** '''size''': The size of the portrait, in pixels.
** '''side''': One of left or right.
** '''mirror''': Whether to flip the image horizontally.
** '''image''': The image path.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* '''[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''': The id of this variation. Defaults to ''variation_name''.
** '''variation_name''': Translatable. The name of the variation.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, which are then overwritten by the keys and tags of this variation. 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. 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]''.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

SingleUnitWML

2016-10-29T16:45:36Z

DeFender1031: /* How to describe a single unit */ this is documented on game config but not here.

{{WML Tags}}
== How to describe a single unit ==

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

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

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].

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

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events.
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.)

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one

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

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

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

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

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

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

* '''variation''': the variation of itself the unit should be created as.

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

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

* '''hp_bar_scaling''': Overwrites the attribute in ([[GameConfigWML]]).

* '''xp_bar_scaling''': Overwrites the attribute in ([[GameConfigWML]]).

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

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

* '''attacks_left''': number of attacks the unit has left. Default is equal to the attacks key for its unit type, that usually is 1 (see ''max_attacks'' below).

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

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

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

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** "unit_image" if 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).

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

* '''max_attacks''': Default is 1. The number of attacks the unit can have per turn.

* '''max_experience''': The experience the unit needs to advance. If left out, this information will be taken from the unit's file.

* '''max_hitpoints''': The maximum hitpoints the unit has. If left out, this information will be taken from the unit's file.

* '''max_moves''': The maximum moves the unit has. If left out, this information will be taken from the unit's file.

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'no'.
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''ai_special = "guardian"'''.
** '''unhealable''': if set to 'yes', the unit cannot be healed.
** {{DevFeature1.13|6}} '''invulnerable''': if 'yes', attacks can't hit the unit.
** One can add other keys to [status], but they must have boolean values. For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].
** '''[advance]''' an advancement the unit has. Same format as [advancement], [[UnitTypeWML]]. Might be used if the unit type has some advancements, but this particular one is supposed to have some of them already taken. {{DevFeature1.13|2}} In 1.13.2 and later this has been renamed to [advancement], to match the UnitTypeWML tag of the same name.

* '''[filter_recall]''' A leader can only recall those units which pass the SUF.
**'''[[StandardUnitFilter]]''' tags and keys

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

* '''[event]''' The event is copied from this unit's wml description into the scenario. The event is carried along with the unit (it can advance etc) and inserted into every scenario where this unit is first created. A [unit][event] requires a non-empty id= attribute.

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

== See Also ==

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

[[Category:WML Reference]]

Git for Wesnoth Crash Course

2016-10-27T19:37:42Z

DeFender1031: /* Setting up our workflow for Wesnoth in Git */ just asked. Apparently aliases are good too as long as they remain consistent.

== Foreword ==

'''''(An essay by, mainly, iceiceice.)'''''

This page is intended for new <cite>Battle for Wesnoth</cite> developers and contributors who have never used '''[//wiki.wesnoth.org/WesnothRepository <cite>Git</cite>]''' before. I'm hoping that it will be written mainly by newbies like myself who have just figured out enough about <cite>Git</cite> to use it successfully, and therefore not include a bunch of information superfluous for that purpose. At the time that I am writing this, I have managed to write about eight GitHub pull requests and get them merged into <cite>Wesnoth</cite>, and I hope you will be able to do the same after reading this.

== What is <cite>Git</cite>? ==

The most effective '''"absolute beginner" introduction to <cite>Git</cite>''' that I found when I started is here: '''[http://gitref.org <cite>gitref.org</cite>]'''.

I suggest that you read this through, beginning to end, navigating through the pages by using the red arrows at the bottom of each page. You can skip the part about ''"stashing"'', but you should carefully read and understand the parts about:

* '''''cloning''''' a ''repository'';
* '''''checking out''''' a ''branch'', creating a '''new branch''', and '''merging branches''';
* '''''adding''''' and '''''committing changes''''';
* viewing '''''diffs''''' to make sure you understand exactly what you are committing;
* '''''resetting''''' your repository state in case you make a mistake and need to undo some steps, and using "'''<kbd>git log</kbd>'''" and "'''<kbd>git reflog</kbd>'''" to assist with this; and
* moving content between local and remote repositories, with "'''<kbd>push</kbd>'''" and "'''<kbd>pull</kbd>'''".

== Setting up our workflow for <cite>Wesnoth</cite> in <cite>Git</cite> ==

It is common when reading about <cite>Git</cite> to see the terms '''''"upstream"''''' and '''''"downstream"'''''. This is often confusing at the beginning -- after all, information is usually flowing in both directions; sometimes, you are getting code from the <cite>Wesnoth</cite> repository, and sometimes you are sending code to it. Which way is up and which is down?

Analogously to a river, ''downstream'' is the direction toward which most information flows. Any user that simply wants to build <cite>Wesnoth</cite> from source, and not make any changes to it, will generally do so by cloning or pulling from <https://github.com/wesnoth/wesnoth>. So [https://github.com/wesnoth/wesnoth <code>wesnoth/wesnoth</code>] (the main <cite>Wesnoth</cite> repository) is the <dfn>upstream</dfn> repository, and the users are <dfn>downstream</dfn>.

If you are a developer, you will '''''fork''''' the upstream repository and edit the source code, and -- hopefully, with work, eventually -- get your edits pulled into the upstream repository. That is the '''<dfn>development cycle</dfn>''', and contributing changes back to upstream is what makes you a developer.

In this guide, we are going to assume that you will use GitHub in addition to the official <cite>Git</cite> command-line program, because GitHub has many useful tools to offer and makes some things nicely easy, especially when comparing a topic branch to the master branch and seeing diffs in a somewhat more advanced interface, and when making ''pull requests''. Technically, this means that you will have '''two repositories''' -- your <dfn>local repository</dfn> on your computer, and a ''fork'' of the <code>wesnoth/wesnoth</code> repository, on GitHub.

The first step of becoming a <cite>Wesnoth</cite> developer is to set up these two repositories. Follow the instructions in [https://help.github.com/articles/fork-a-repo/ GitHub's "<cite>Fork A Repo</cite>" help article], which may be summarized as follows:

<ol>
<li>'''''Fork''''' the <code>wesnoth/wesnoth</code> repository, using the GitHub website.</li>
<li>'''''Clone''''' the fork onto your computer, with the command "<kbd>git clone</kbd>".</li>
<li>Configure '''<dfn>remotes</dfn>''' (''remote'' repositories that are essentially bookmarked).
GitHub's <cite>Fork A Repo</cite> article describes how to set the <code>wesnoth/wesnoth</code> repository as a remote with the name "<code>upstream</code>". Because you cloned from your fork, the fork is automatically set as a remote with the name "<code>origin</code>". You can see your remotes with the command "<kbd>git remote -v</kbd>".
You might find this naming scheme confusing, given that the name "<code>origin</code>" might also aptly describe the <code>wesnoth/wesnoth</code> repository. So it might be good to rename that remote to "<code>fork</code>" (with the command "<kbd>git remote rename origin fork</kbd>"). But if you do that, note that much of the GitHub help pages will assume the name "<code>origin</code>".</li>
</ol>

Additionally, we ask that you configure <cite>Git</cite> to use your full real name or a consistent alias, per the instructions in [https://help.github.com/articles/setting-your-username-in-git/ GitHub's "<cite>Setting your username in Git</cite>" help article], so that we can associate a concrete person with every commit merged into <cite>Wesnoth</cite>. Your GitHub profile should also display the same name.

== The basic workflow ==

Here's the picture we now have, with 3 repositories:

upstream

origin (fork)

local

There are four basic steps in the development cycle, which are as follows:

# ensuring that your local repository is '''up-to-date''' with the upstream repository;
# creating a '''topic branch''' for your changes;
# '''committing''' your changes to the topic branch and '''pushing''' them to your fork; and
# filing a GitHub '''pull request''', having that request granted, then finally cleaning up.

=== Keeping your local repository up-to-date ===

In this step, you will make sure your local <code>master</code> branch is up-to-date with the most recent development changes before beginning work.

First make sure you are on your <code>master</code> branch:

git checkout master
git status

Now, pull the upstream <code>master</code> branch to your local repository:

upstream
|
|
| origin (fork)
|
v
local

git pull upstream master

At this point your local master is up to date. While you are at it, you might as well update your fork as well:

upstream

.--> origin (fork)
/
/
local --'

git push origin master

At this point, the <code>master</code> branch should be the same in all three repositories.

=== Creating a topic branch ===

In this guide, we will never make any changes directly on the <code>master</code> branch, and will only make code changes on a topic branch, so regardless of which repository you look at, the <code>master</code> branch should be the same, and <cite>Git</cite> will be comparing your work against the upstream <code>master</code> branch.

Now you are ready to create a new '''[https://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches <dfn>topic branch</dfn>]''', which will hold your work for this patch. We are on the <code>master</code> branch, as running "<kbd>git status</kbd>" will confirm. Create your new topic branch -- named, in this example, "<code>new-feature</code>" -- by running the following command:

git checkout -b new-feature

As shown in the <cite>gitref.org</cite> guide, you could also have done this with the following commands:

git branch new-feature
git checkout new-feature

Given that you were on the <code>master</code> branch when you created the <code>new-feature</code> topic branch, the <code>new-feature</code> branch will branch off from the ''tip'' of your current <code>master</code> branch, which is best, to avoid conflicts when the <code>new-feature</code> branch is eventually merged upstream.

=== Committing your changes and pushing to your fork ===

Now, you will make your changes to <cite>Wesnoth</cite>, test them, and commit them to your local repository, with the commands "<kbd>git add</kbd>" and "<kbd>git commit</kbd>", as shown in the <cite>gitref.org</cite> guide.

==== Committing guidelines ====

<ol>
<li>
<h5 style="font-size: larger">Write good commit messages</h5>

A commit message should fully explain what changes were made in the commit, and why those changes were made. A good commit message is structured like an email message.

The first line, which summarizes the commit, has special importance -- to quote the <cite>[[DeveloperGuide]]</cite> page, <q cite="http://wiki.wesnoth.org/DeveloperGuide#Commit_messages">This is the first (and often the only) line someone using browsing tools will see</q>. It should ideally be at most 80 characters (TODO: inconsistent with current policy), and is like the subject line of an email message. Commit message summary lines should be written in the imperative present tense, e.g., "Add field to <var>some_class</var>, with accessor methods", "Fix <var>other_class</var>'s constructor", "Delete unnecessary #include", etc.

After the summary line, there must be a blank line, after which comes the '''commit message body''', which is analogous to the body of an email message.

'''Optimally''', a commit's message would be so clearly and comprehensively explanatory that it would answer any questions that anyone might have about the commit, now, the next day, or years into the future -- which is especially important because the author of the commit likely won't always be around to answer those questions.

See also [//wiki.wesnoth.org/DeveloperGuide#Commit_messages the <cite>DeveloperGuide</cite> page's "Commit messages" section] and [https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines the official Git book's "Commit Guidelines" section].
</li>
<li>
<h5 style="font-size: larger">Make appropriately sized commits</h5>

Each commit should correspond to a single logical step in your programming task. The commits constitute the project's development history; people will look at your commits to try to figure out how we got to where we are today, and may at some point need to undo the changes made in some of your commits to fix a future issue.

If you find it difficult to write a succinct commit message that fully explain what changes were made in the commit, and why those changes were made, then the commit is insufficiently fine-grained -- too large and too complicated. Another guideline is, you should at least think about committing almost every time you compile (depending on your habits).

On the other hand, you shouldn't make a commit for every line of code typed. If it would never make sense to revert the repository's code to its current state from a future state, you probably shouldn't commit. For example, if you define a field of an object, but it has no accessors and no way to be used in code, it would never make sense to revert to that time in the repository's history, so those changes should be saved together in a single commit. If you have a commit that merely adjusts whitespace in a file, that should be squashed in with another commit, according to current (2015-07-25) policy.

It is better to commit more often than less often, because, before you submit your changes to upstream, you will have the opportunity to edit your commit history, and it is much easier to ''squash'' commits together than to split up an overly-large commit.

See also [//wiki.wesnoth.org/DeveloperGuide#Commits the <cite>DeveloperGuide</cite> page's "Commits" section].
</li>
<li>
<h5 style="font-size: larger">Keep the change-logs, release notes, and credits up-to-date</h5>

After committing your changes, add an entry in the '''<code>changelog</code>''' document, and commit it with the message "Update changelog".

We also have a '''<code>players_changelog</code>''' document, which should contain only changes that most players are likely to notice, and be less technical than the main, technical <code>changelog</code>.

There is also a '''<code>RELEASE_NOTES</code>''' document, which basically is copied into the next <cite>Wesnoth</cite> release's release announcement post in the forums, so if there is a new feature or bug fix that should be advertised, add that to <code>RELEASE_NOTES</code>.

If this is your first commit, the development team will ask you to add an appropriate note about yourself in the '''credits document''', '''<code>data/about.cfg</code>'''.

See also [//wiki.wesnoth.org/DeveloperGuide#Changelogs_and_release_notes the <cite>DeveloperGuide</cite> page's "Changelogs and release notes" section].
</li>
</ol>

Finally, when your branch is ready, push it to your fork.

upstream

.--> origin (fork)
/
/
local --'

git push origin new-feature

Now, if you navigate to your fork's page on GitHub, you should see a message such as "recently pushed branch new-feature (3 minutes ago)". Click "Compare" to compare it against the <code>master</code> branch. You should now see a list of the commits you made on the <code>new-feature</code> branch, and color-highlighted diffs of the files you changed. You can click through the commits in order to see each of the changes you made and understand how your project progressed -- this is exactly what the development team will do when they review your pull request.

In the GitHub interface, you can always see a list of branches by clicking on "branches" in the line near the middle of the page that looks like the following:

10,000+ commits 27 branches 248 releases 85 contributors

You can also look at a specific branch using the "Branch" menu below that line, and you can compare branches using the green "Compare" button to the left of the "Branch" menu.

=== Cleaning up your branch ===

Before filing your pull request, if, looking at the diffs and the history (the list of commits) for your topic branch, you saw anything confusing or not quite right, now is your opportunity to change it.

From the <cite>gitref.org</cite> guide, you should know how to add more commits, and you should know that you can use "<kbd>reset</kbd>" to go back in time and redo things.

"'''<kbd>reset</kbd>'''" is especially good if your last commit was too big and you want to break it up into a series of smaller commits -- the command "<kbd>git reset "@~"</kbd>" will leave your working directory the same, but jump back in time one commit and unstage all of those changes, so you can add a smaller subset of the files, commit those, then add the others, etc.

More generally, you can use "'''<kbd>git reflog</kbd>'''" to see how to reset back over any number of commits or other <cite>Git</cite> operations.

You can also use "'''<kbd>git commit --amend</kbd>'''" to edit the commit message of the most recent commit.

There are several more advanced cleanup features available with <cite>Git</cite>, but we'll defer any further discussion of them.

Every time you make changes, you should to push them to your fork to keep it up-to-date. If you rewrote your commit history, then the push would be rejected, because the commit histories won't match. Therefore, to push a rewritten history, you must '''''force push''''', which will -- this is a potentially dangerous operation! -- discard the old commit history and replace it with the new history:

upstream

.--> origin (fork)
/
/
local --'

git push --force origin new-feature

You can and should do this throughout your development if you want to look at the diffs of your changes as you work -- after all, the <cite>Wesnoth</cite> code-base is vast and it is easy to forget exactly where you are in your project. You can and should keep cleaning up in this way until you are satisfied with the result. Doing this, your GitHub fork ends up being rather like a personal Web-based IDE plug-in or extension to help you with development.

=== Filing a pull request ===

When you finish working on your feature or bug fix, select your topic branch on your fork (with the "Branch" menu), and click the green button to file a pull request. By default, the target of the pull request -- the repository and branch into which it is requesting that your changes be pulled -- will be "<samp>wesnoth:master</samp>", the <code>master</code> branch of the main <cite>Wesnoth</cite> repository.

The message that you enter for the pull request should become the commit message of the merge operation performed in the upstream repository if the pull request is granted. (Note: if you are granting someone's PR through the GitHub Web interface, please ensure that this happens.)

If you fixed a bug, you should say, e.g., "Fixed bug #5678" in the pull-request message, which should automatically link to [https://gna.org/bugs/index.php?group=wesnoth&set=custom&report_id=101&status_id=1&chunksz=150&boxoptionwanted=1 our Gna! bug tracker].

If you want more information, you could read [https://help.github.com/articles/creating-a-pull-request/ GitHub's "<cite>Creating a pull request</cite>" help article].

upstream <-.
\
\
'- origin (fork)

local

You should then see your pull request in [https://github.com/wesnoth/wesnoth/pulls the main <cite>Wesnoth</cite> repository's "pull requests" page].

At the time of writing this, we also have configured [https://travis-ci.org Travis CI], a [https://en.wikipedia.org/wiki/Continuous_integration continuous integration] system, to automatically try to compile <cite>Wesnoth</cite> with your changes, to make sure that it still works before your pull request is granted. However, it is not mandatory for the Travis build to complete successfully for the pull request to be granted. Additionally, you may still make changes to your pull request by pushing more changes to your topic branch in your fork, after which Travis should try to compile the updated topic branch. You can even still force push to erase the content of the topic branch (on which the pull request is based) and replace it with new content -- however, you shouldn't file a pull request for a topic branch until you are ready for it to be merged.

Now, wait for a member of the development team to review your pull request. You can often find someone on the development [//wiki.wesnoth.org/Support#IRC IRC] channel, <code>#wesnoth-dev</code>. Additionally, developers may comment directly on your pull request with questions, so you should check it periodically.

=== Cleaning up at the end ===

Congratulations, a developer granted your pull request! Now it's time to clean up and update your local repository.

On the GitHub page for your pull request, you should now see a button with the option "delete this branch". Since the content of new-feature is now merged into master, this branch no longer needs to exist as you won't work on it anymore, and future work will go onto a different branch. So you should delete it, which will delete the branch on *origin*, your github-associated repo.

Since master has now changed and we want master to be synced up, you should now do step 1 again:

upstream
|
|
| origin (fork)
|
v
local

git checkout master
git pull upstream master

At this point git will understand that new-feature has been merged into master, so when you ask to delete this branch from local as well, it will do it:

git branch -d new-feature

If you do these steps out of order, i.e. try to delete the branch before before syncing master, it will make a warning "Are you sure? You have unmerged changes on this branch..." etc.

Finally, sync master on the origin as well:

upstream

origin (fork)
/-->
--/
local

git push origin master

That's the end of the development cycle, and now you can begin on your next patch. Note that throughout the cycle, information only flowed counter-clockwise:

upstream
| <--\
| \--
| origin (fork)
| /-->
v --/
local

If for some reason you find yourself doing something where information is flowing the other way, that is a good sign that something is going wrong, at least as far as this guide is concerned! (The exception is the steps in which we set up our repos -- don't overthink this.)

== Advanced / Alternative workflows ==

You can use pull requests as described above whether you have commit access or not -- if you have commit access, then you can click to accept your own pull requests.

However, if you have commit access, you may prefer not to use github / pull requests at all, and instead to push directly to wesnoth:master. You can still use topic branches to hold your work, and merge them to your local master using git merge, then use 'git push upstream master' to push them to the main wesnoth repo.

If you are lazy, you might even skip making a topic branch and just commit to local master, although IMO this can make things more confusing if you get a merge conflict later.

Either way, afaik the vast majority of wesnoth developers prefer to push directly to wesnoth:master.

An extreme option appropriate for small changes is to skip the local repo as well, and simply commit changes directly from the github web interface. This might be appropriate for example if you forgot to commit a changelog entry in an earlier patch, or are simply changing some numbers used as parameters somewhere. Obviously if you change source code this way, you should make certain that everything still compiles immediately after! (Note: Don't actually do that.)

== The ultimate cleanup power tool: git rebase ==

Using things in the gitref guide, you can see how to use reset to undo mistakes you made by backing up and trying again, and for small commits that is probably fine. However, if you have a large and complicated series of changes, the better way to do this is using git rebase. Using git rebase in interactive mode, you can rewrite history by

* reordering your commits
* discarding unwanted commits
* squashing commits together
* editing the content changes represented by an individual commit
* editing the commit message

For our purposes, we assume you are working on a topic branch, and then you will only need to use the form

git rebase -i master

You can see some documentation for using this command here: https://help.github.com/articles/interactive-rebase

Using 'git rebase', you can make your commit history very *clean* -- instead of the history saying "I tried a bunch of things, undid some of them, tried some other things, and found something I liked", your commit history can basically be "I took the simplest and most logical route to the solution that was finally the best". When you review your commits, instead of feeling like a nasty blood-and-elbow-grease engineering project, it should feel like folding a perfect origami crane, to the extent possible ;)

But to reiterate, this has a purpose.
# Other devs need to be able to understand the history.
# It should be possible to jump back in time by checking out one of your commits and find ourselves in a sensible state when we do so.
# If something breaks or some feature become incompatible, it should be possible to roll back only a piece of the implementation of your feature without removing the whole thing.

If you want to use rebase to cleanup your history, it is important to do it *before* it is pulled into wesnoth, as once that happens it is basically no longer possible. If we rewrite history in the main wesnoth repo, then afterwards whenever any dev tries to 'git pull upstream master', their git will give them strange merge errors, stemming from the incompatible history, and then they will become nervous, jump on irc and exclaim some variation of "omg wtf bbq". So except in extreme circumstances, we will never rebase the main wesnoth master, and for the same reason, we will never use "git push --force upstream master". That's why if you want to do these things, it is important to do them on your *fork* before it makes it onto master.

If you feel like it, you might read this, which is a historical email between early users / developers of git, in which Linus Torvalds explains about shared history of repos and when it is appropriate to use git rebase.

http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html

When you become comfortable with git rebase -i, it will greatly improve your workflow, as you will know that you can easily review and revise commit messages later, and easily reorder and squash commits. Typically I will now commit every single time I compile, and even if it is a commit which e.g. fixes a compile time error, or for some other reason I know it will be squashed in somewhere else, I give it the commit message "fixup", as a note to myself to mark it thusly in the first git rebase pass. (Actually, while writing this I have just learned about the --autosquash feature of git rebase which takes this idea further, good stuff there.)

Note that unlike Linus and github, in this guide we aren't thinking about your github fork repo as public -- we prefer to think of it as your personal private IDE/tool as I described earlier. If other wesnoth devs are cloning it or pulling your topic branches, we assume you will work it out with them. With that caveat the philosophies expressed on github and by Linus should generally apply to the wesnoth project as well.

=== Solving merge conflicts with git rebase ===

Github version: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request

Suppose that you modify a file in the same place as someone else, and their change gets merged before yours. If git can't figure out how to merge, then someone will have to fix it. This could be done by whoever is merging the new content into master, but if you don't have commit access then that person is not you. One way that *you* could fix it is to resync your master to get the new changes locally, and then rebase your topic branch so that your changes are applied *after* the most recent changes.

git rebase master

To understand what is happening, we should understand a bit more about how git works. Intuitively, git is all about "snapshots" of the project content. Every commit represents a snapshot, and you can look at this snapshot by checking out the commit. However git does not store each snapshot separately -- instead git defines the snapshots in terms of one another, and stores only the diffs. When you rebase your topic branch onto master, this will also update the "point of departure" where your branch was created, so that in the history, it will depart from the current head of master with the most recent changes. (Obviously, if you don't sync master until you are done working, then this subtlety to 'git rebase' is irrelevant.)

If merging your branch with the current master would create a conflict, then when git rebase gets to the commit that creates the conflict, it will get confused when it tries to apply that diff, stop, tell you about the problem, and ask you to resolve it -- you can open up the offending file and go to the point where the conflict is happening, and git will leave a note for you of the content it is having trouble with. The note will look similar to what happens in the gitref guide here, under "merge conflicts".

http://gitref.org/branching/#merge

You just have to remove the note, make the file look like it should to make everything compatible, and type

git add .
git rebase --continue

Then the rebasing process will continue, and at the end your branch should be compatible with master and ready to be merged in.

You can read more about this aspect of git rebase here if you like, although most likely you won't actually need more than we just talked about for wesnoth development.

http://git-scm.com/book/en/Git-Branching-Rebasing

That's all for this guide, have fun hacking on wesnoth!

== Addendum ==
The following section contains commands with the -f / --force options. Those are usually used to rewrite history, which is fine for your own fork but disallowed for upstream. Do not use them on the main repository.

If a command goes awry, you can go to "git reflog", find the point just before you typed it, and reset --hard to that commit, and it should be like the bad thing never happened

revert every file in the repo to look like it did at the HEAD commit (last successful sync)
git reset --hard HEAD

get a clean slate by syncing with upstream
git fetch upstream
git checkout -B master upstream/master
git push --force origin master
if this errors, try again after
git reset --hard HEAD

undo n commits, split/squash and apply again
git reset HEAD~n
git add -p
git commit
git push -f

You can also push from one ‘ref’ to a different one:
$ git push <remote> <from>:<to>

completely overwrite branch b with a (from a to b)
git push -f origin a:b

before any commit:

* if the diff shows an invisible change in the first line - stop! Fix the file encoding back to UTF8 without BOM.

* don't forget the changelog (and, for visible changes, the players_changelog)

* try to keep the summary at 50 characters or less, maximum 72

== See Also ==

* [[Project#Developers]]

[[Category:Development]]

UnitTypeWML

2016-10-26T19:42:54Z

DeFender1031: /* Attacks */ more intuitive place for this information.

{{WML Tags}}

__TOC__

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:
* '''[advancefrom]''': 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. 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.
* '''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.
* '''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.
* '''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.
* '''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.
* '''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.
* '''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.
* '''hide_help''': determines if the unit type will appear in the in-game help. Possible values ''true'' and ''false'', defaults to ''false''.
* '''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'' should consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
::WARNING : characters "$", "&", "*", "-", "(" and ")" are illegal for use in the unit type id and must be avoided because they might lead to corrupted saved games
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctionWML#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''':(translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
* '''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. 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, khalifate, 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.
* '''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).

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

== 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}}).
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'melee'(default) displays "melee", while 'ranged' displays "ranged". Range can be anything. Standard values are now "melee" and "ranged". From now on, ''short'' and ''long'' will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable.
** '''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; negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon offensively; 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.
** '''attack_weight''': helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack
** '''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
For the weight settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).

== Other tags ==
* '''[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. Attributes in this unit overwrite the copy. Tags modify the corresponding tag of the original, so for example the first '''[attack]''' tag in the derived unit would modify the first attack of the base unit rather than defining a new attack. 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.

* '''[portrait]''': Describes a unit portrait for dialogue. However, generally you should use the profile key instead; [portrait] is mostly for internal use.
** '''size''': The size of the portrait, in pixels.
** '''side''': One of left or right.
** '''mirror''': Whether to flip the image horizontally.
** '''image''': The image path.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* '''[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''': The id of this variation. Defaults to ''variation_name''.
** '''variation_name''': Translatable. The name of the variation.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, which are then overwritten by the keys and tags of this variation. 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. 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]''.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

InternalActionsWML

2016-10-20T19:50:25Z

DeFender1031: /* [store_villages] */ the note as it was was misleading, conflating a convention (*^V* for villages) with a rule (gives_income means it's a village).

{{WML Tags}}

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

== Variable Actions ==

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

=== [set_variable] ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.

=== [set_variables] ===

Manipulates a WML array or container

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

* '''mode''': one of the following values:
** ''replace'': will clean the array '''name''' and replace it with given data
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

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

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

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

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

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

=== Capturing Game Data ===

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

==== [store_gold] ====

Stores a side's gold into a variable.

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

==== [store_locations] ====

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

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

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

==== [store_reachable_locations] ====

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

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

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

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

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")

'''Result'''

Variable will contain following members:
* '''color''': It indicates team color. Can be one of the following:
{| border = 1
| ''color''
| red
| blue
| green
| purple
| black
| brown
| orange
| white
| teal
|-
| ''value''
| 1
| 2
| 3
| 4
| 5
| 6
| 7
| 8
| 9
|}
* '''controller''': Indicates type of player that control this side. ''In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''network''': In multiplayer for sides that client does not control, both what would normally be human and ai. For host values are as usual, this is where OOS comes from.
** '''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 have.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Base income for this side (without villages).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''team_name''': String representing the team's description.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.

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

==== [store_time_of_day] ====

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

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

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

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

==== [store_turns] ====

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

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

==== [store_unit] ====

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

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

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

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

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

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

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

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

==== [store_unit_type] ====

* '''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")

==== [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. Without them, [store_villages] will behave the same way as [store_locations] will if 'owner_side' is set to include all sides (including 0 for unowned).

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

==== [store_items] ====

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

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

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

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

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

==== [find_path] ====

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

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

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

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

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

=== [clear_variable] ===

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

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

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

=== [sync_variable] ===

{{DevFeature1.13|0}}

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

== Other Internal Actions ==

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

=== [fire_event] ===

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

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

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

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

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

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

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

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

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

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

=== [insert_tag] ===

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

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

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

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

=== [role] ===

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

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

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

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

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

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

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

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

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

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

=== Flow control actions ===

{{DevFeature1.13|2}}

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

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. No further WML actions are executed in this context. If there was another event queued, that event will be run as usual.

== Examples ==

=== Using [set_variables] to Create Arrays of 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}

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

=== [insert_tag] Example ===

[event]
name=moveto

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

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

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]

This is effectively identical to:

[event]
name=moveto

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

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

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

DirectActionsWML

2016-07-09T18:14:57Z

DeFender1031: /* [allow_undo] */ spelling

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

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

The following tags are actions:

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

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

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

=== [unit] ===
Places a unit on the map. For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''to_variable''': spawn directly into a variable instead of on the map.

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

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

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

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the position to teleport to. If that position is not empty, some other location will be chosen.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

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

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

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

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) floating text to display above the unit, such as a damage amount
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
* '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit.
* '''extra_recruit''': the types of units that the side can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't take any arguments.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''': if 'yes', displays the unit dying (fading away).
* '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter.
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this to work around a bug when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP, SPECIAL_BACKSTAB, or any other effect that uses variable substitution or when using [effect][filter] with a $this_unit (see http://gna.org/bugs/index.php?18893).
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

=== [transform_unit] ===
Transforms every unit matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way.
* '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per scenario. In a campaign objects with the same id can be assigned once per scenario. For filtering objects, custom key can be used, such as item_id.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this to work around a bug when adding ABILITY_TELEPORT (or any other effect that uses variable substitution) via an [object] or when using [object][effect][filter]with a $this_unit (see http://gna.org/bugs/index.php?18893). {{DevFeature1.13|5}} ABILITY_LEADERSHIP and SPECIAL_BACKSTAB now also use variable substitution and thus require this to be set to "yes".
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed)
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to true, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
* '''no_write''': {{DevFeature1.13|1}} (bool, default false). If true, the contents of [effect] will be applied to the relevant unit, but the [object] tag will not be written to unit.modifications. This renders duration= irrelevant.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_view=yes).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recruitment, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.

Due to a bug in 1.12 (https://gna.org/bugs/?23323) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.syncronize_choice

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. Note that if delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are '''not''' available.

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the "harm_amount" key.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* [[TimeWML]]: the new schedule.
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain). ([http://forums.wesnoth.org/viewtopic.php?f=21&t=14749&p=405667&hilit=tunnel#p405667 source])

* '''id''' identifier for the tunnel, to allow removing (optional).
* '''remove''': (boolean) yes/no value. If yes, removes all defined tunnels with the same ID (then only id= is necessary). (default: no)
* '''bidirectional''': (boolean) if yes, creates also a tunnel in the other direction. (default: yes)
* '''always_visible''': (boolean) if yes, the possible movement of enemies under fog can be seen. (default: no)
* '''[source]''': [[StandardLocationFilter]] the source hex(es) (required).
* '''[target]''': [[StandardLocationFilter]] the target hex(es) (required).
* '''[filter]''': [[StandardUnitFilter]] the units which can use the tunnel (required). Leave empty for "all units".

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should always be replay safe.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

AnimationWML

2016-03-20T13:29:04Z

DeFender1031: /* How animations are chosen */ singular

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays its attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine.

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=<red, green, blue>
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

* a '''plain string''' — e.g., “abc” or “123”;
* a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
* a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

Ranges can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be '''backward''' — from a greater number to a lesser number (e.g., “5~1”).

===== Range expansion =====

Each '''range''' ''<var>x</var>~<var>y</var>'' is expanded within its expansion list to a comma-separated list of radix-10 integers (which are plain strings), starting from the first endpoint <var>x</var> and ending at the second endpoint <var>y</var>.

If '''<var>x</var> < <var>y</var>''', then the numbers in this list increase by increments of 1; if '''<var>x</var> > <var>y</var>''', then the numbers in this list decrease by decrements of 1. E.g., “1~3” would become “1,2,3”, and “3~1” would become “3,2,1”.

If '''<var>x</var> = <var>y</var>''', then this list has only one element, which is <var>x</var> (and is also <var>y</var>, of course). E.g., “2~2” would becomes “2”.

If either <var>x</var> or <var>y</var> (or both) are padded with '''leading zeros''', then each number in the resultant list will be padded with leading zeros such that it is expressed in at least <var>z</var>+1 digits, where <var>z</var> is the quantity of leading zeros with which one or both endpoints are padded. E.g.,
* “07~11” would become “07,08,09,10,11”,
* “098~100” would become “98,99,100”,
* “003~1” (or “3~001”) would become “003,002,001”, and
* “0098~100” would become “098,099,100” (although poor form), and
* “01~100” would become “01,02,...,10,11,...,999,100”.

If both endpoints are padded with leading zeros, they should both be padded with the same quantity of leading zeros.

===== Repetition expansion =====

Each '''repetition''' ''<var>s</var>*<var>n</var>'' is expanded within its expansion list to a comma-separated list with <var>n</var> elements, each of which is the string <var>s</var>. E.g., “abc*3” would become “abc,abc,abc”.

===== Square bracket expansion =====

A single '''progressive string value''' may contain multiple '''square-bracketed expansion lists''', which must all be of the same length in elements (after range and repetition expansion). This length shall be referred to as <var>L</var> for the remainder of this section.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list with <var>L</var> elements.

For each integer <var>n</var> from 1 to <var>L</var>, the <var>n</var>-th element of this list shall be a copy of the progressive string, with each expansion list it contains replaced with that expansion list’s <var>n</var>-th element (after range and repetition expansion).

When a progressive string that contains expansion lists is processed it is transformed at each bracket pair into a comma-separated list, which is generated as follows (in pseudo code):
for each comma separated string entry
for all square brackets entries at once
expand outwards such that S[A~B]T expands to SAT, ..., SBT preserving any leading zeros
expand outwards such that S[A,B]T expands to SAT, SBT
expand outwards such that S[A*N]T expands to SAT, ..., SAT (n times)
and any combination of above separated by commas executed sequentially
next
next

==== Field Description ====

* '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
* '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
* '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
* '''image''': the image, or sequence of images, to display during the frame.
* '''image_diagonal''': the image, or sequence of images, to display when the attack occurs diagonally (directions ne,se,sw,nw).
* '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
* '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
* '''halo''': the halo to display at the time.
* '''halo_x''', '''halo_y''': the position the halo is displayed in pixel relative to the unit's center. These are directional, taking into account the direction the unit is facing.
* '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
* '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
* '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
* '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255); this color will be mixed to the frame to give it a tint.
* '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
* '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
* '''text_color''': the color of the above floating label.
* '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
* '''x''': x offset applied to the frame
* '''y''': y offset applied to the frame
* '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
* '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
* '''layer''': layer used to draw the frame, see discussion bellow
* '''auto_hflip''': should the image flip horizontally depending on sprite orientation
* '''auto_vflip''': should the image flip vertically depending on sprite orientation
* '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_color=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_color=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_alpha=<progressive float>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_directional_x=<progressive int>
xxx_directional_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

Note that xxx_ parameters (e.g. missile_offset) are shortcuts to access parameters from outside of their corresponding frame and have no effect inside of them.

== How animations are chosen ==
Within a unit description block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criterion that fails on the current situation
* Take the animations that have the most matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelout ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

==== levelin ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:600" blend_color=255,255,255''

==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison damage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''

==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, and from 1.11.7+ you can nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2016-03-16T07:56:27Z

DeFender1031: lose, not loose

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus percentage (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Places a unit on the map. For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''to_variable''': spawn directly into a variable instead of on the map.

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/SingleUnitWML filter_recall] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the position to teleport to. If that position is not empty, some other location will be chosen.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) floating text to display above the unit, such as a damage amount
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
* '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit.
* '''extra_recruit''': the types of units that the side can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't take any arguments.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''': if 'yes', displays the unit dying (fading away).
* '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the :inspect command. It can add [trait]s and [object]s without needing to wrap them inside a [modifications] tag, and their effects are applied immediately. Cannot remove things. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.
example usage (see also the test scenario):
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

note: The syntax allowed is somehow vague. Just try things and possibly correct/add/modify this documentation. (a [http://forums.wesnoth.org/viewtopic.php?f=21&t=31676& forum thread] discusses some related issues).

=== [transform_unit] ===
Transforms every unit matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way.
* '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per scenario. In a campaign objects with the same id can be assigned once per scenario. For filtering objects, custom key can be used, such as item_id.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this to work around a bug when adding ABILITY_TELEPORT via an [object] or when using [object][effect][filter]with a $this_unit (see http://gna.org/bugs/index.php?18893).
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed)
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to true, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
* '''no_write''': {{DevFeature1.13|1}} (bool, default false). If true, the contents of [effect] will be applied to the relevant unit, but the [object] tag will not be written to unit.modifications. This renders duration= irrelevant.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_view=yes).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===

Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recruitment, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.

Due to a bug in 1.12 (https://gna.org/bugs/?23323) '''[allow_undo]''' should not be used in events that use one of the following things brcause it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.syncronize_choice

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the "harm_amount" key.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* [[TimeWML]]: the new schedule.
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain). ([http://forums.wesnoth.org/viewtopic.php?f=21&t=14749&p=405667&hilit=tunnel#p405667 source])

* '''id''' identifier for the tunnel, to allow removing (optional).
* '''remove''': (boolean) yes/no value. If yes, removes all defined tunnels with the same ID (then only id= is necessary). (default: no)
* '''bidirectional''': (boolean) if yes, creates also a tunnel in the other direction. (default: yes)
* '''always_visible''': (boolean) if yes, the possible movement of enemies under fog can be seen. (default: no)
* '''[source]''': [[StandardLocationFilter]] the source hex(es) (required).
* '''[target]''': [[StandardLocationFilter]] the target hex(es) (required).
* '''[filter]''': [[StandardUnitFilter]] the units which can use the tunnel (required). Leave empty for "all units".

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should always be replay safe.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]