The Battle for Wesnoth Wiki - User contributions [en]

EventWML

2009-06-25T12:42:44Z

A Guy:

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.

'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker misses,defender misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

==== Predefined 'name' Key Values ====

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else. Spaces in event names can be interchanged with underscores (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

; preload {{DevFeature}}
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc. '''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

; prestart
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead. '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything. '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; new turn
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

; side turn
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.

; turn refresh
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

; turn ''X''
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.

; time over
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])

; enemies defeated
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.

; victory
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])

; defeat
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])

Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

; moveto
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.

; sighted
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)

; attack
: Triggers when the primary unit attacks the secondary unit.

; attack end
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

; attacker hits
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

; attacker misses
: Same as ''attacker hits'', but is triggered when the attacker misses.

; defender hits
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

; defender misses
: Same as ''defender hits'', but is triggered when the defender misses.

; stone
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.

; die
: Triggers when the primary unit is killed by the secondary unit.

; capture
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.

; recruit
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

; prerecruit
: Triggers when the primary unit is recruited but before it is displayed.

; recall
: Triggers after a unit is recalled.

; prerecall
: Triggers when a unit is recalled but before it is displayed.

; advance
: Triggers just before the primary unit is going to advance to another unit.

; post advance
: Triggers just after the primary unit has advanced to another unit.

; select
: Triggers when the primary unit is selected. Also triggers when ending a move, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

; menu item X
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== Custom events.

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives.

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will every time the criteria are met instead of only the first time.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'' and ''attack end''. For more information and other filter keys, see [[FilterWML]].
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [event] ====
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

It is only possible to use [message] with input and random numbers in events that are synchronous. This limitation is caused because that WML requires data from remote hosts which is only available after network synchronisation.

List of event that are synchronous:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
* events fired from WML event handler that is synchronous
* new turn {{DevFeature}}
* side turn {{DevFeature}}
* turn X {{DevFeature}}
* turn refresh {{DevFeature}}

There is also event that are synchronous if fired by engine but they can be fired by wml tags too from non-synchronous event. So when you are using them you must be extra careful. For example [unsotre_unit] unit may trigger unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

It is perfectly possible (and, in fact, useful) to have multiple events with the same predefined name and thus the same trigger condition. However, it is not defined what order such events will fire in, so you need to code so the order
will not matter.

Because of the above, you need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display the turn on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

How to play Horseman

2009-06-17T19:12:02Z

A Guy: Previously, the paragraph was blatantly wrong.

==Introduction==
The Horseman is a very powerful unit. It can scout for villages and pick off lone units, but it can also form your front line of combat or hang back and kill wounded units in the middle of a battle. It has high HP, a good attack, many moves, and resists most damage types. The one downside: It costs a lot.

Hopefully, this guide will make the Horseman worth its cost to you, or even worth more than that.

==When to get the Horseman==
The Horseman has a very different role in campaigns, as opposed to multiplayer. In campaigns, the goal is usually to win quickly, which the Horseman excels at, while in multiplayer, the goal is to win at all, which entails many different strategies.

===Campaigns===
There are very few situations in a campaign in which Horsemen would not benefit you. Early on, Horsemen can win you some quick victories and gold; later, a corps of Knights or Grand Knights is perfect for doing the real heavy work of a battle. The Grand Knight is one of the highest-HP units in the game, so it makes a very good line-holder in an open area without normal defensive terrain, which would otherwise be a weakness.

The Knight really isn't a unit that you can do without, if you're allowed to get it. Knights are the perfect shock troops to use where other units fail you. In Heir to the Throne, Horsemen and Knights can win quickly in a battle which would otherwise involve slogging through streams of enemies, such as Crossroads or Northern Winter; in The Rise of Wesnoth, many scenarios, like the Midlands have open ground, easy for horse units to dominate, and lots of Orcs, often the ideal opponents of Knights; in the Eastern Invasion, Knights can be made into Paladins, perfect for fighting the Undead, or Grand Knights, which massacre everything else in the campaign, and can be given holy ankhs to make them even more devastating than Paladins.

It's usually not such a good idea, though, to use Horsemen in cave scenarios. The exception is when you have a Paladin and face Undead; if the map is small enough that you can get it to the battle, its holy weaponry makes up for its other weaknesses.

===Multiplayer===
The Horseman is significantly less valuable here. In campaigns, you often have more gold than you could possibly spend, making cost no issue; in multiplayer, cost is always an issue.

For this reason, in multiplayer, you cannot get hordes of Horsemen, and deal devastating damage to all the enemies. However, you can still get a few horsemen and deal devastating damage to a few enemies.

If the enemy fields too many low-melee archers, get a horseman. If the enemy fields too many Drakes, get a horseman, If the enemy fields too many Spearmen, don't get a horseman! Overall, in the Default era, the Horseman is best against Northerners, mediocre against Rebels, Drakes, and Knalgans, and downright bad against Loyalists and Undead.

Never get Horsemen against Loyalists. Loyalists regularly use Spearmen, Bowmen, and Heavy Infantry, all of which are devastating to Horsemen. As a scout, the Cavalryman is cheaper and less likely to get massacred.

Don't get Horsemen against Undead either, unless the Undead player has already recruited stupidly (e.g. all Dark Adepts.) Even in that situation, Cavalrymen may be the better choice.

None of the Knalgans' units is that great against the Horseman, but only the Poacher is weak to the Horseman, and it's best not to field Horsemen unless they can be sure of some effectiveness.

Elves are frail and easy to take down with a Horseman, but if you let it near them, an Elvish Shaman would be very nasty, and the Horseman is no good at all against Woses. (Side note: A Knight is very effective against Woses.) If he goes with Shamans and Woses, don't get a horseman. If the opponent uses Elvish Fighters and Archers a lot, do get a horseman. Just don't be stupid and attack them in forest.

Drakes are another dubious case. If the opponent gets Clashers or Saurian Skirmishers, then the Horseman is very vulnerable and shouldn't be recruited; however, if they don't, then a Horseman will easily cut down Burners, Augurs, and even Fighters. On the other hand, it's a pretty weak opponent who will fail to get either Clashers or Skirmishers when faced with a Loyalist opponent.

Against Northerners, a Horseman is almost always effective. All northerner units are Chaotic, meaning that you can get a damage bonus while your opponents have a damage penalty. No northerner unit except the Goblin Spearman is any challenge to the properly played Horseman, and the Spearman, though it is a risky fight, is so weak that it can often be killed in one hit.

==What do do with the Horseman==

===General tactics===
Attack the following: Low-melee archers, low-defense one-hit-kills, and units that need to die ASAP to win the battle.
Do not attack the following: High-melee units, high-defense full-HP units, and units that can kill the Horseman and thereby lose you the battle.

The Horseman is an opportunist. If there's something to attack, do so. If there's nothing to attack, run away and grab a village.

A common mistake with the Horseman is to attack, kill something easily, and then have the Horseman cut to ribbons the next turn by archers. This is no good. The Horseman costed more than that unit. One thing never to do is to attack with the Horseman when it is open to attack like this. Always defend the Horseman if it attacks from a position open to enemy units.

Defense isn't always that obvious, though. If the Horseman can attack, be killed by archers, and then your army can kill the archers, then the Horseman is defended. If the Horseman can attack, be killed by archers, and then you can break through their battle lines which are no longer supported by the archers, then the Horseman is defended. If the Horseman can attack, be killed by archers, and then you can grab enemy villages and split the enemy army, then the Horseman is defended.

Of course, you can always defend it by putting units around it, but be careful that you won't lose the battle just because the enemy kills a guard and then sneaks in and shoots down the Horseman. Threats are more secure, if the enemy can't remove them.

Another common mistake with the Horseman is to attack a high-defense fighter that can kill the Horseman, just because the Horseman can kill it in one hit. Now, if killing that fighter is crucial to your victory in the battle, then by all means, do it; but if the fighter is in an insignificant side position, then the attack is suicidal. Remember, a wounded unit is probably worth about half as much as the Horseman. If you let it do damage to you, it had better be very little damage, or very unlikely, because otherwise, you're losing out.

Also, never attack a unit that can kill the Horseman and level up by doing so, unless it is the only way to stop it, even if that unit is in 20% defense and can be killed in one hit.

A third mistake, just as bad as the others, is to leave the Horseman running around grabbing villages and never reaching the main battle. It's a waste of gold. You can save five gold on that by using Cavalrymen instead (or Elvish Scouts if this is HttT) but even then, it's pretty wasteful. The unit has an attack and is meant to use it.

At the very least, if there are truly no attack opportunities, keep the horseman close enough to the battle to strike at any moment. The threat cripples your opponent's strategy, especially relating to his leader. The leader is often a level 2 unit which can be taken out in one attack by a lucky Horseman; if you see an opportunity to swing for the enemy leader, (although not so much one of several enemy leaders in team games) you should usually take it. It gives you a chance to win the game immediately, and even the worst-case situation, losing the Horseman and doing no damage, doesn't decrease your overall chance to win by that much.

Finally, remember the time of day. You don't have to worry about it too much in itself, as long as you check how much damage you're actually doing, but you'll find that the horseman is much more effective during the day, obviously - you may want to retreat your other units at night, or not commit to a battle that will last until night, if you want to rely on Horseman support.

===Leveling up===
You choose, when leveling up, between the Knight and the Lancer.

In campaigns, always get the Knight. The Lancer is easier to kill and doesn't advance, which are important in campaigns, while a few extra moves and more raw damage are not. In campaigns, you can't afford to lose random level 2 units, and the Lancer really can't hold the line either.

In multiplayer, a lancer may be a decent alternative choice. They have more strikes with their charging weapon, giving them more damage potential overall. The huge movement they have also allows them to get through enemy defenses and hit a leader.

===Campaign-specific tactics===
In Heir to the Throne, or The Rise of Wesnoth, where gold is plentiful, a prime strategy is to recruit castle after castle of Horsemen and run down the enemy by sheer numbers. Low-XP horsemen can be used for suicide rushes on powerful units, while high-XP horsemen can be used to take out weak units, such as one hit kills or Archers and Troll Whelps during the day. If you are going for level 3 knights, then many units can be killed in one hit by a Knight's charge, but if you want more level 2 knights, their swords are also very useful for softening up enemies for Horsemen to kill.

==See also==
[[How to play Loyalists]] article

[[How to play...]] series

[[Category: How to Play]]

User:A Guy

2009-05-25T20:54:13Z

A Guy:

Hello, there. These are the scenarios I have so far.

[[http://wesnoth.org/forum/viewtopic.php?f=15&t=23019| 3p Rivalry]] (By Golbeeze and A_Guy)

[[http://wesnoth.org/forum/viewtopic.php?f=15&t=23019| Modern Combat]] (By PsychoticKittens and A_Guy)

I'm an above average WML writer.

User:A Guy

2009-05-25T20:53:59Z

A Guy:

User:A Guy

2009-05-25T20:53:35Z

A Guy:

2008-08-25T15:17:33Z

A Guy: /* [event] */

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''': a unit passing this filter with >0 HP exists
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)
** '''count''' {{DevFeature}}: if used, the given number of units must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]
** '''count''' {{DevFeature}}: if used, the given number of location must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

* '''[and]''': If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if]: if these evaluate to true, [and] evaluates to true.

* '''[or]''': If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if]: if these evaluate to true, '''[or]''' evaluates to true.

* '''[not]''': If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if]: if these evaluate to true, [not] evaluates to false.

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of Only one of the following keys should be used for comparing the value of the variable to another value:
** '''equals''': $name is equal (string wise) to this
** '''not_equals''': $name is not equal to this
** '''greater_than''': $name is numerically greater than this
** '''less_than''': $name is less than this
** '''greater_than_equal_to''': $name is not less than this
** '''less_than_equal_to''': $name is not greater than this
** '''numerical_not_equals''': $name is greater than or less than this
** '''numerical_equals''': $name is not greater than or less than this
** '''boolean_equals''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

After condition tags:
* '''[then]''': contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''': contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [switch] {{DevFeature}} ==

Executes different sets of action based on the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': name of the variable to check.
* '''[case]''': Case block. Contains:
** '''value''': value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

== [while] ==

Executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the {{LinkMacro|FOREACH}} and {{LinkMacro|NEXT}} predefined macros.

=== {REPEAT} ===
You can use the {{LinkMacro|REPEAT}} macro to perform a quick iteration for a number of times you specify.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}
** '''name''': the name of the variable to manipulate
** '''value''': set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** '''format''': set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.
** '''add''': add the given amount to the variable. To subtract, add a negative number.
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** '''divide''': divide the variable by the given number. The result is an integer.
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''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.
** {{DevFeature}} '''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).
** {{DevFeature}} '''[join]''' joins an array of strings to a textual list
***variable: name of the array
***key: array[$i].key to look for the strings
***separator: separator to connect the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[set_variables]''': manipulates a WML array
** '''name''': the name of the 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'''
** '''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, example:
[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}
=>bar; more
** '''[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: array[$i].key to put the elements in
***separator: separator to separate the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[fire_event]''': trigger a WML event
** '''name''': the name of event to trigger
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)
** both tags have some keys which are optional :
*** '''x,y''': location of this unit
*** '''weapon''': weapon that this unit was supposed to use for this event

* '''[store_unit]''': stores details about units into game variables. 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 [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 [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** '''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.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.
:* advanceto
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[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' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)
** '''side''': the side whose starting location is to be stored
** '''variable''': (default='location'): the name of the variable to store the location 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 {{DevFeature}} 'owner_side' (villages only).
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''': Stores a series of locations of villages 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 {{DevFeature}} 'owner_side'.
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
* '''[store_gold]''': Stores a side's gold into a variable.
** '''side''': (default=1) the side for which the gold should be stored
** '''variable''': (default='gold') the name of the variable to store the gold in
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''side''': the side whose information should be stored
** '''variable''': the name of the variable to store the information in
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** '''name''': the name of the variable to clear.
* '''[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 [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[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''.
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML
**'''name''': the ["name"] to be given to the tag
**'''variable''': name of the variable to be inserted

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

[[Category: WML Reference]]

InternalActionsWML

2008-08-25T02:03:30Z

A Guy: /* [event] */

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''': a unit passing this filter with >0 HP exists
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)
** '''count''' {{DevFeature}}: if used, the given number of units must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]
** '''count''' {{DevFeature}}: if used, the given number of location must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

* '''[and]''': If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if]: if these evaluate to true, [and] evaluates to true.

* '''[or]''': If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if]: if these evaluate to true, '''[or]''' evaluates to true.

* '''[not]''': If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if]: if these evaluate to true, [not] evaluates to false.

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of Only one of the following keys should be used for comparing the value of the variable to another value:
** '''equals''': $name is equal (string wise) to this
** '''not_equals''': $name is not equal to this
** '''greater_than''': $name is numerically greater than this
** '''less_than''': $name is less than this
** '''greater_than_equal_to''': $name is not less than this
** '''less_than_equal_to''': $name is not greater than this
** '''numerical_not_equals''': $name is greater than or less than this
** '''numerical_equals''': $name is not greater than or less than this
** '''boolean_equals''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

After condition tags:
* '''[then]''': contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''': contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [switch] {{DevFeature}} ==

Executes different sets of action based on the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': name of the variable to check.
* '''[case]''': Case block. Contains:
** '''value''': value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

== [while] ==

Executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the {{LinkMacro|FOREACH}} and {{LinkMacro|NEXT}} predefined macros.

=== {REPEAT} ===
You can use the {{LinkMacro|REPEAT}} macro to perform a quick iteration for a number of times you specify.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}
** '''name''': the name of the variable to manipulate
** '''value''': set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** '''format''': set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.
** '''add''': add the given amount to the variable. To subtract, add a negative number.
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** '''divide''': divide the variable by the given number. The result is an integer.
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''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.
** {{DevFeature}} '''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).
** {{DevFeature}} '''[join]''' joins an array of strings to a textual list
***variable: name of the array
***key: array[$i].key to look for the strings
***separator: separator to connect the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[set_variables]''': manipulates a WML array
** '''name''': the name of the 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'''
** '''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, example:
[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}
=>bar; more
** '''[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: array[$i].key to put the elements in
***separator: separator to separate the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[fire_event]''': trigger a WML event
** '''name''': the name of event to trigger
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)
** both tags have some keys which are optional :
*** '''x,y''': location of this unit
*** '''weapon''': weapon that this unit was supposed to use for this event

* '''[store_unit]''': stores details about units into game variables. 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 [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 [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** '''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.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.
:* advanceto
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[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' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)
** '''side''': the side whose starting location is to be stored
** '''variable''': (default='location'): the name of the variable to store the location 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 {{DevFeature}} 'owner_side' (villages only).
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''': Stores a series of locations of villages 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 {{DevFeature}} 'owner_side'.
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
* '''[store_gold]''':Stores a side's gold into a variable.
** '''side''': (default=1) the side for which the gold should be stored
** '''variable''': (default='gold') the name of the variable to store the gold in
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''side''': the side whose information should be stored
** '''variable''': the name of the variable to store the information in
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** '''name''': the name of the variable to clear.
* '''[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 [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[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''.
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML
**'''name''': the ["name"] to be given to the tag
**'''variable''': name of the variable to be inserted

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

[[Category: WML Reference]]